diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6f8c035..f95ce7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Deprecated
+
+- **This project is deprecated.** The SQL sink has been folded into the main
+  [`substreams` CLI](https://github.com/streamingfast/substreams) as `substreams sink postgres` and
+  `substreams sink clickhouse`, shipped in substreams **v1.20.2**. The standalone binary is in
+  maintenance mode for one year — security fixes only, if any, and no new features — after which the
+  repository is archived read-only. Existing releases, tags and Docker images stay available.
+
+  Databases are compatible in place — cursor tables and schemas are unchanged, so the CLI resumes from
+  the stored cursor. See the
+  [migration guide](https://github.com/streamingfast/substreams/blob/develop/docs/how-to-guides/sinks/sql/migration.md)
+  for the full command and flag mapping. Notable differences: there is no `run` subcommand (the engine
+  command runs the sink), no `from-proto` subcommand (the mode is detected from the output module type),
+  `create-user` was removed, the DSN moved to `--dsn`/`SUBSTREAMS_SINK_DSN`, block ranges moved to
+  `-s`/`-t`, and `--metrics-listen-addr` became `--prometheus-addr`.
+
 ## v4.13.1
 
 ### Fixed
diff --git a/README.md b/README.md
index 56cb779..fe92d91 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,36 @@
 # Substreams:SQL Sink
 
+> [!IMPORTANT]
+> ## Deprecated — this sink now lives in the `substreams` CLI
+>
+> `substreams-sink-sql` has been folded into the main [`substreams` CLI](https://github.com/streamingfast/substreams)
+> and is available as `substreams sink postgres` and `substreams sink clickhouse` starting with
+> **substreams v1.20.2**. This repository is in maintenance mode for one year: security fixes only, if
+> any, and no new features. It is then archived read-only — existing releases, tags and Docker images
+> stay available, so anything already running keeps working. Please migrate.
+>
+> **Your database does not need to change.** The cursor tables and schemas are identical, so the CLI
+> resumes exactly where this binary left off — point it at the same DSN.
+>
+> | `substreams-sink-sql` | `substreams` CLI |
+> | --- | --- |
+> | `run $DSN manifest.yaml 100:200` | `substreams sink postgres manifest.yaml -s 100 -t 200 --dsn $DSN` |
+> | `from-proto $DSN manifest.yaml` | `substreams sink postgres manifest.yaml --dsn $DSN` (mode auto-detected) |
+> | `setup $DSN manifest.yaml` | `substreams sink postgres setup manifest.yaml --dsn $DSN` |
+> | `generate-csv $DSN manifest.yaml 0:100` | `substreams sink postgres generate-csv manifest.yaml -t 100 --dsn $DSN` |
+> | `inject-csv $DSN ./csv table 0:100` | `substreams sink postgres inject-csv ./csv table 0:100 --dsn $DSN` |
+> | `tools --dsn $DSN cursor read` | `substreams sink postgres tools cursor read --dsn $DSN` |
+> | `create-user ...` | removed — create the user directly in your database |
+>
+> Swap `postgres` for `clickhouse` when targeting ClickHouse. Note there is **no `run` subcommand**: the
+> engine command runs the sink itself, and the mapping mode is detected from the output module's type.
+> The Docker image changes from `ghcr.io/streamingfast/substreams-sink-sql` to `ghcr.io/streamingfast/substreams`.
+>
+> Full command and flag mapping, including DSN, block-range and metrics flag changes:
+> **[Migration guide](https://github.com/streamingfast/substreams/blob/develop/docs/how-to-guides/sinks/sql/migration.md)**.
+>
+> The documentation below describes the deprecated standalone binary and is kept for users still running it.
+
 The Substreams:SQL sink helps you quickly and easily sync Substreams modules to a PostgreSQL or Clickhouse database.
 
 It supports two different Substreams output formats, each with distinct advantages: