Upgrading SQLStreams

A SQLStreams upgrade can change both the Go library and the tables it uses in Postgres. Before starting an updated application, check whether its release needs database migrations and whether older instances can keep running.

This guide uses v0.1.4 → v0.1.5 as the example. That pair needs no database migration. The version checks below identify when migration work is required for the release you choose.

Before you begin

Read the target release’s release notes and the compatibility table. Confirm the release supports your PostgreSQL version.

Install the SQLStreams CLI at the version matching your target library release.

The database connection below uses the Quickstart. For another installation, use its database URL and schema.

1. Check and update database versions

Connect the new CLI to the application’s database:

sqlstreams_database_url='postgres://username:password@localhost:5432/quickstart?sslmode=disable'
sqlstreams --database-url "$sqlstreams_database_url" migrate status

Example output from v0.1.5 with the Quickstart stream registered:

latest available: system 1, stream 1

system: current 1, available 1

STREAM                 CURRENT   AVAILABLE
__system.alerts        1         1
__system.metrics       1         1
__system.schedules     1         1
signup.welcome-email   1         1

Confirm that the output lists the intended installation’s streams. It shows the installed system version and each stream’s CURRENT version beside the AVAILABLE version supported by this CLI.

If the system and all streams already match, continue to step 2.

If a system or stream is behind, follow the release’s deployment requirements before migrating. Keep old instances running only when the release is compatible with them. For an incompatible change, stop the old producers, consumers, and other SQLStreams processes first. Let consumers stop gracefully before proceeding.

Migrate the system first if needed, then any streams that are behind:

sqlstreams --database-url "$sqlstreams_database_url" \
  migrate system up --target-version {system_version}
sqlstreams --database-url "$sqlstreams_database_url" \
  migrate streams up --target-version {stream_version}

Replace each placeholder with that scope’s numeric AVAILABLE version. System and stream versions are independent. These numbers describe SQLStreams’ tables, not your message payload’s SchemaVersion.

Repeat the status command with the same database URL. Continue once the installed versions match their targets. If a command fails, resolve the reported problem before deploying. Migration lock timeout covers blocked schema changes.

2. Deploy the updated application

Deploy your application built with the target library release. For a compatible upgrade, replace instances gradually and let each old consumer stop gracefully. If you stopped all old instances for an incompatible migration, start the new ones now.

Check that producers and consumers start successfully and that your application processes a message. If startup reports SQL0022 or SQL0023, use Schema version mismatch to identify the database or application version that needs correcting.

Compatibility table

Release maintenance and deprecation

Only the latest stable release receives fixes. Bug and security fixes ship in a new release, with no promised backports to older release lines.

Before removing or incompatibly changing a supported public API, SQLStreams announces the deprecation in release notes, marks affected Go declarations with Deprecated:, and documents the replacement and migration steps. The API remains available through at least one subsequent minor release, including during v0.x development. An urgent security exception states its reason and migration steps in the release notes.

Related topics

• Migrate database schemas — Migration API, individual-stream commands, and partial completion behavior.
• Stop a consumer gracefully — Allow active work to finish before replacing an instance.
• Schema version mismatch — Investigate SQL0022 and SQL0023.
• Migration lock timeout — Find what is blocking a migration and retry it.