# Versioning And Compatibility

pgGraph 1.x uses semantic versioning for its documented SQL API, configuration,
diagnostics, packages, and operational behavior. PostgreSQL tables remain the
source of truth across upgrades, and pgGraph can rebuild its graph indexes from
those tables.

## Supported Release Matrix

pgGraph 1.1 supports PostgreSQL 14 through 18. PostgreSQL 17 is the default
development and playground reference version. Published container images target
Linux on AMD64 and ARM64, and PGXN carries the verified 1.1.0 source bundle.

A patch release never removes a PostgreSQL major. A minor 1.x release may
retire a major only after upstream PostgreSQL support ends, with at least one
minor release and 90 days of notice. The final compatible pgGraph minor remains
the supported line for installations that cannot yet upgrade PostgreSQL.

## Stable 1.x Surfaces

Within the 1.x line, pgGraph preserves documented SQL function names,
signatures, argument defaults, result shapes, volatility and security context;
documented GUC names, accepted values, and defaults; standard SQLSTATE classes
and stable `PGxxx` diagnostic identifiers; extension-catalog meaning and
supported upgrade paths; and documented script entry points, flags, environment
variables, exit semantics, and user-visible output locations.

Minor releases may add new functions, configuration values, or supported query
capabilities. They do not append fields to an existing result row or otherwise
change a positional contract. A new result shape uses a new explicitly
versioned function or contract.

Undocumented internal Rust modules, extension-owned catalog tables, helper
scripts, temporary files, and artifact bytes are not public APIs. They may
change, but supported upgrades migrate internal catalogs safely and never ask
users to edit them directly.

## Artifacts And Rebuilds

Before loading a persisted graph index, pgGraph checks its format, version, and
completeness. Compatible indexes load normally. An index that is corrupt,
incomplete, or from an incompatible version is rejected with instructions to
rebuild it; pgGraph never guesses how to interpret the file.

pgGraph publishes a replacement index only after validating it and retains the
last valid index so other backends do not see a partial update. These guarantees
apply to every 1.x release.

If a release cannot reuse an existing graph index, rebuild it from the
PostgreSQL tables. Release notes identify releases that require a rebuild and
provide the exact build, validation, and rollback steps.

## Deprecation

An ordinary 1.x deprecation provides a documented replacement, retains the old
surface for at least two minor releases and six months (whichever is longer),
and tests both paths throughout that window. Removal waits for a major release.
Security or data-corruption emergencies may require a faster change; those
releases include an upgrade preflight, prominent migration instructions, and a
supported restore or rebuild procedure.

## Upgrade Procedure

Before upgrading, take a PostgreSQL backup and record the installed version and
graph state:

```bash
pg_dump --format=custom --file=pggraph-before-upgrade.dump DBNAME
psql -X -d DBNAME -c "SELECT extversion FROM pg_extension WHERE extname = 'graph';"
psql -X -d DBNAME -c "SELECT * FROM graph.status();"
```

For a supported 1.x-to-1.x update, install the new package for the same
PostgreSQL major, then run and validate:

```sql
ALTER EXTENSION graph UPDATE TO 'X.Y.Z';
SELECT extversion FROM pg_extension WHERE extname = 'graph';
SELECT * FROM graph.status();
```

For the 1.0.0-to-1.1.0 update, use:

```sql
ALTER EXTENSION graph UPDATE TO '1.1.0';
SELECT extversion FROM pg_extension WHERE extname = 'graph';
SELECT * FROM graph.status();
```

The update preserves the existing SQL signatures, adds relationship-typed
shortest-path overloads, and changes traversal, connected-components, and
component-statistics entry points to caller-preserving `SECURITY INVOKER`.
Existing v6 artifacts remain compatible. If an RLS-active relationship mapping
lacks a usable durable relationship identity, the query fails closed with
diagnostic `PG023` until `graph.build()` publishes a replacement.

To move from an alpha release to 1.0, preserve or restore the PostgreSQL source
tables, install 1.0 cleanly, reapply the reviewed graph registration, and run
`graph.build()`. Do not reuse alpha extension catalogs or graph files. The
repository's signed `v0.1.8` migration fixture verifies this source-preserving
path.

pgGraph 1.1 does not support an in-place SQL downgrade to 1.0.0. Keep the
pre-upgrade database backup and matching 1.0.0 package until cutover is
accepted. Rollback restores that backup into a clean database/server using the
1.0.0 package; do not install an older shared library over 1.1 catalogs or
artifacts. A logical restore assigns new relation OIDs, so treat the projection
as derived state: run `graph.reset()`, re-register the restored source tables
and relationships, and run `graph.build()` before serving graph queries.

Installing an older binary over 1.x catalogs or artifacts is unsupported.
Binary downgrade is supported only when the target release notes say its
catalogs and artifacts remain compatible. Otherwise restore the pre-upgrade
backup and package. pgGraph stops before an irreversible migration when a safe
rollback cannot be guaranteed.

## Compatibility Inventory

The repository maintains `release/v1-contract.json` as a machine-readable
inventory of supported PostgreSQL majors, distribution targets, SQL function
names, GUCs, diagnostics, and the declared GQL profile. Release checks compare
that inventory with implementation sources. Any drift requires an explicit
compatibility review before the inventory can be regenerated.