---

## Releasing to PGXN

pg_vault_tde's distribution metadata lives in [META.json](META.json)
(mandatory for [PGXN](https://pgxn.org/), the PostgreSQL Extension Network)
and [Changes](Changes) (release history). This section is for maintainers
cutting a new release, not for end users installing the extension — see
"1. Install" above or [wiki: Installation](https://github.com/miriade/pg_vault_tde/wiki/Installation)
for that.

### One-time setup

Register a PGXN Manager account at
<https://manager.pgxn.org/account/register> if you don't already have one.
No API token/CLI upload path is offered by PGXN Manager — every release is
uploaded by hand through its web UI.

### Every release

1. **Bump the version in lockstep**, in three places that must agree:
   - `pg_vault_tde.control` → `default_version = 'X.Y'` — PostgreSQL's own
     extension version, tied 1:1 to the `sql/pg_vault_tde--X.Y.sql` filename
     and to `extversion` in `pg_extension`. Stays 2-part; nothing outside
     PostgreSQL reads this file, so it does not need to follow semver.
   - `VERSION` and `META.json` (top-level `"version"` **and**
     `provides.pg_vault_tde.version`) → `X.Y.0` — PGXN requires a 3-part
     semantic version (`https://pgxn.org/spec/` — "three-part dotted
     integers, such as `1.2.0`"). `VERSION` is also compiled into the
     extension itself (the Makefile embeds its content as
     `-DPG_VAULT_TDE_BUILD_VERSION`, returned by
     `pg_vault_tde_build_version()` / the `build_version` column of
     `pg_vault_tde_health_check()`) — it distinguishes binary builds that
     share the same `extversion` (e.g. a C-only bugfix with no SQL script
     change), so it must always mirror `META.json`'s `"version"` exactly,
     and a plain `make` after bumping it needs a preceding `make clean` for
     the new string to actually take effect (CFLAGS changes alone don't
     invalidate already-built `.o` files).
     Both map 1:1 to the control file's `X.Y` with a trailing `.0`.
   - Add the corresponding `sql/pg_vault_tde--X.Y.sql` (and, if upgrading an
     already-installed extension in place, an
     `sql/pg_vault_tde--<old>--X.Y.sql` migration script) and point
     `META.json`'s `provides.pg_vault_tde.file` at the new SQL file.
2. **Add an entry to [Changes](Changes)** for the new version.
3. **Build and smoke-test the exact bundle PGXN will receive**:
   ```bash
   make dist                       # → dist/pg_vault_tde-X.Y.zip (git archive of HEAD;
                                    #   commit the version bump first, or it won't be in the zip)
   cd /tmp && unzip -o /path/to/dist/pg_vault_tde-X.Y.zip && cd pg_vault_tde-X.Y

   # PGXN's own build/test recipe — must pass before uploading:
   make USE_PGXS=1
   make USE_PGXS=1 install
   make USE_PGXS=1 installcheck PGDATABASE=postgres   # needs a running server with
                                                       # shared_preload_libraries=pg_vault_tde;
                                                       # see ci/scripts/run-regress.sh /
                                                       # run-isolation.sh for the required GUCs
   ```
4. **Validate META.json** before uploading (catches schema mistakes PGXN
   Manager would otherwise reject at upload time):
   ```bash
   pip install pgxnclient
   pgxn validate-meta META.json   # or: validate_pgxn_meta META.json, if you have
                                   # the Perl PGXN::Meta::Validator tooling installed
   ```
5. **Upload**: log in at <https://manager.pgxn.org/>, click "Upload" in the
   side navigation, and submit `dist/pg_vault_tde-X.Y.zip`. PGXN Manager
   parses `META.json` from the zip, so double-check the version inside the
   zip matches what you intend to release before submitting — once a
   version is published it cannot be re-uploaded under the same number.
6. **Tag the release** in git (`git tag vX.Y && git push --tags`) — this
   repo currently has only a `v1.6` tag; `default_version` in the control
   file had already moved on to later versions in-tree before being tagged,
   so don't assume the control file version and the latest git tag are the
   same thing when preparing a release.