Prepare for the first release - #4
Merged
Merged
Conversation
The first release needs a version that is not the 0.0.0 placeholder the install script has seeded since the version table existed. The seeded row stays the version's only home: the release tooling reads it from here rather than keeping a copy that could drift.
Consumers currently need the repository and knowledge of the sql/ file order to install. A tagged release with downloadable artifacts removes both: scripts/build-release.sh concatenates the numbered scripts into an all-in bundle, a core-only file and one file per extension library, with checksums, reading the version from the row 000_install.sql seeds. Concatenation is safe because every script opens and closes its own transactions. The workflow is workflow_dispatch only and guarded to main on emfga/cel4postgres: publishing is a deliberate act, never a side effect of a push, and forks carrying this file must not release. Before publishing it boots the same pinned postgres image compose uses with the all-in and core artifacts as the initdb script and asserts cel.version() answers, so a bundle that fails to install can never reach a release. The tag is created by the release itself, so re-running for an already published version fails rather than republishing.
pg_tle is the recommended install path on RDS and Aurora, so a release that only proved the psql channel could ship artifacts that fail through CREATE EXTENSION. The release workflow now wraps the exact dist/ files into pgtle.install_extension at test time and installs them as a real extension before anything publishes: a matrix covers the all-in bundle, the core alone, and the core with each extension library, and each variant must evaluate an expression that needs its environment -- env rows exist even in a core-only install, so only a working call is evidence the extension's items are there. The wrapper strips top-level BEGIN/COMMIT because a pg_tle script runs inside CREATE EXTENSION's own transaction, and refuses input containing its dollar-quote tag rather than emit a script that breaks somewhere deep in pg_tle. The image builds aws/pg_tle, pinned like every other reference, on the same postgres image compose pins, extracted from compose.yaml so the two cannot drift. Nothing built here is published; the channel is validated, the wrapped form is not (yet) an artifact.
Comments across the tree cited planning notes that were never committed -- numbered documents, rulings, phase labels -- so a reader without that context met references that resolve to nothing. Each one now either states its fact directly, names an in-tree source (CLAUDE.md, docs/CONFORMANCE.md, a pinned cel-go location), or is gone. A few were not just unreachable but wrong: the install header named a script that does not exist, two files pointed at a sql/ext/ directory that was never created, the optionals header promised as future work what part two of the same file already implements, and the conformance package comment predated the corpus runner. Those are corrected against the tree, and the full bundle was reinstalled afterwards to prove the SQL still loads.
The README's install section assumed a checkout and knowledge of the sql/ file order, and said nothing about the release artifacts or managed PostgreSQL. The guide documents both channels -- plain SQL anywhere, and pg_tle on RDS/Aurora for real extension semantics -- plus checksum verification, the grants an application role needs, and the current upgrade story. Every command in it was run before being written down: the pg_tle path is the one CI validates per release, and the grants snippet was exercised with a fresh non-superuser role (evaluation works, registry writes are denied).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Bump the schema version to 0.0.1
The first release needs a version that is not the 0.0.0
placeholder the install script has seeded since the version
table existed. The seeded row stays the version's only home:
the release tooling reads it from here rather than keeping a
copy that could drift.
Add a manual release workflow and artifact build
Consumers currently need the repository and knowledge of the
sql/ file order to install. A tagged release with downloadable
artifacts removes both: scripts/build-release.sh concatenates
the numbered scripts into an all-in bundle, a core-only file
and one file per extension library, with checksums, reading
the version from the row 000_install.sql seeds. Concatenation
is safe because every script opens and closes its own
transactions.
The workflow is workflow_dispatch only and guarded to main on
emfga/cel4postgres: publishing is a deliberate act, never a
side effect of a push, and forks carrying this file must not
release. Before publishing it boots the same pinned postgres
image compose uses with the all-in and core artifacts as the
initdb script and asserts cel.version() answers, so a bundle
that fails to install can never reach a release. The tag is
created by the release itself, so re-running for an already
published version fails rather than republishing.
Validate releases through pg_tle before publishing
pg_tle is the recommended install path on RDS and Aurora, so a
release that only proved the psql channel could ship artifacts
that fail through CREATE EXTENSION. The release workflow now
wraps the exact dist/ files into pgtle.install_extension at
test time and installs them as a real extension before anything
publishes: a matrix covers the all-in bundle, the core alone,
and the core with each extension library, and each variant must
evaluate an expression that needs its environment -- env rows
exist even in a core-only install, so only a working call is
evidence the extension's items are there.
The wrapper strips top-level BEGIN/COMMIT because a pg_tle
script runs inside CREATE EXTENSION's own transaction, and
refuses input containing its dollar-quote tag rather than emit
a script that breaks somewhere deep in pg_tle. The image builds
aws/pg_tle, pinned like every other reference, on the same
postgres image compose pins, extracted from compose.yaml so the
two cannot drift. Nothing built here is published; the channel
is validated, the wrapped form is not (yet) an artifact.
Make code comments stand alone on a fresh checkout
Comments across the tree cited planning notes that were never
committed -- numbered documents, rulings, phase labels -- so a
reader without that context met references that resolve to
nothing. Each one now either states its fact directly, names an
in-tree source (CLAUDE.md, docs/CONFORMANCE.md, a pinned cel-go
location), or is gone.
A few were not just unreachable but wrong: the install header
named a script that does not exist, two files pointed at a
sql/ext/ directory that was never created, the optionals header
promised as future work what part two of the same file already
implements, and the conformance package comment predated the
corpus runner. Those are corrected against the tree, and the
full bundle was reinstalled afterwards to prove the SQL still
loads.
Add an installation guide for AWS and self-hosted
The README's install section assumed a checkout and knowledge of
the sql/ file order, and said nothing about the release artifacts
or managed PostgreSQL. The guide documents both channels -- plain
SQL anywhere, and pg_tle on RDS/Aurora for real extension
semantics -- plus checksum verification, the grants an
application role needs, and the current upgrade story.
Every command in it was run before being written down: the pg_tle
path is the one CI validates per release, and the grants snippet
was exercised with a fresh non-superuser role (evaluation works,
registry writes are denied).