From 95d62acf7ebae1d75004c742e6ad02c2931b1039 Mon Sep 17 00:00:00 2001 From: 0xGabey Date: Wed, 29 Jul 2026 16:55:48 +0700 Subject: [PATCH 1/2] chore: deprecate in favor of the built-in substreams sink commands The SQL sink was folded into the substreams CLI (streamingfast/substreams#830) and ships in v1.20.2 as `substreams sink postgres` / `substreams sink clickhouse`. Add a deprecation banner with the command mapping and a pointer to the upstream migration guide, plus a CHANGELOG entry. Databases are compatible in place, so the note leads with that. --- CHANGELOG.md | 17 +++++++++++++++++ README.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f8c035..48c8eef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,23 @@ 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 and will stop receiving releases. + + 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..17450db 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,35 @@ # 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: no new features, and it will stop +> receiving releases. 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: From e73178eb49b0dea0f78167da57b6fbd0b5f00ac6 Mon Sep 17 00:00:00 2001 From: 0xGabey Date: Tue, 18 Aug 2026 21:13:09 +0700 Subject: [PATCH 2/2] docs: clarify deprecation timeline Maintenance mode lasts one year with security fixes only, then the repo is archived read-only. Previous wording claimed releases stop entirely, which is wrong. --- CHANGELOG.md | 3 ++- README.md | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 48c8eef..f95ce7c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **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 and will stop receiving releases. + 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 diff --git a/README.md b/README.md index 17450db..fe92d91 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ > > `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: no new features, and it will stop -> receiving releases. Please migrate. +> **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.