PLAN_VERSIONING.md — Semantic Versioning & Compatibility Policy

Status: Draft
Target version: v1.0.0
Author: pg_trickle project

1. Overview

pg_trickle follows Semantic Versioning 2.0.0 from v1.0.0 onward. Prior to 1.0 (0.x.y), minor-version bumps may include breaking changes to the catalog schema or SQL API.

2. Version Number Rules

MAJOR.MINOR.PATCH
  │      │     └── Backwards-compatible bug fixes only
  │      └──────── New SQL functions / GUCs / catalog columns (non-breaking)
  └─────────────── Incompatible catalog schema changes or SQL API removals

What constitutes a MAJOR (breaking) change

Change Breaking?
Rename / drop a SQL function in schema pgtrickle Yes
Remove or rename a column in pgtrickle.pgt_stream_tables Yes
Change a GUC name Yes
Change the default behavior of an existing function Yes
Require a new ALTER EXTENSION UPDATE migration Yes
Add a new optional GUC No
Add a new monitoring view No
Add a new SQL function No
Add a nullable/defaulted column to a catalog table No

Pre-1.0 policy (0.x.y)

  • 0.MINOR.0 bumps MAY break catalog schema.
  • 0.x.PATCH bumps MUST NOT break the catalog schema.
  • All breaking changes MUST be documented in CHANGELOG.md.

3. PostgreSQL Extension Upgrade Scripts

3.1 File naming

Upgrade scripts live in the repository root (alongside pg_trickle.control):

pg_trickle--0.1.0.sql          # Initial install script
pg_trickle--0.1.0--0.2.0.sql  # Upgrade path 0.1.0 → 0.2.0
pg_trickle--0.2.0--0.3.0.sql  # Upgrade path 0.2.0 → 0.3.0

Multi-hop upgrades are supported by PostgreSQL automatically (it chains individual step scripts), but we SHOULD also provide direct paths for common jumps (e.g., 0.1.0--1.0.0.sql) to reduce downtime.

3.2 pg_trickle.control fields

default_version = '0.1.0'     # Updated on every release
module_pathname = '$libdir/pg_trickle'
relocatable = false
schema = pgtrickle
requires = ''

default_version MUST be bumped as part of every release PR before tagging.

3.3 Running an upgrade

ALTER EXTENSION pg_trickle UPDATE;                -- to latest
ALTER EXTENSION pg_trickle UPDATE TO '0.2.0';    -- to specific version
SELECT extversion FROM pg_extension WHERE extname = 'pg_trickle';

Detailed migration SQL authoring guidelines: see PLAN_UPGRADE_MIGRATIONS.md.

4. Public API Definition

The following surface area is considered public and governed by semver:

Surface Location
SQL functions All CREATE FUNCTION in schema pgtrickle
Catalog table columns pgtrickle.pgt_stream_tables.*
GUC names pg_trickle.* parameters in postgresql.conf
Change buffer schema pgtrickle_changes.changes_<oid> column names
SQL error codes Any SQLSTATE codes documented in SQL_REFERENCE.md

The following are internal and NOT subject to semver:

  • Function names prefixed with _pgtrickle_ (internal helpers)
  • Trigger function names (_pgtrickle_cdc_trigger, etc.)
  • Shared memory layout
  • Background worker names

5. Deprecation Policy

  1. Functions/GUCs marked deprecated remain available for one full MINOR version before removal.
  2. A deprecation notice appears in the SQL function comment and in CHANGELOG.md.
  3. A WARNING-level notice is emitted at call time: sql RAISE WARNING 'pgtrickle.foo() is deprecated and will be removed in v2.0. Use pgtrickle.bar() instead.';
  4. The deprecated item is removed in the next MAJOR bump.

6. Compatibility Matrix

pg_trickle PostgreSQL pgrx Notes
0.1.x 18.x 0.17.x Pre-release
0.2.x 18.x 0.17.x
0.3.x 18.x 0.17.x
1.0.x 18.x 0.17.x First stable
1.1.x 18.x, 19.x 0.18+ See PLAN_PG19_COMPAT.md

7. Release Checklist

  • [ ] Bump default_version in pg_trickle.control
  • [ ] Bump version in Cargo.toml
  • [ ] Write upgrade SQL script for all supported upgrade paths
  • [ ] Add ## vX.Y.Z section to CHANGELOG.md
  • [ ] Tag commit vX.Y.Z after CI passes
  • [ ] Push tag to trigger GitHub Actions packaging workflow

References