Skip to content

Prepare for the first release - #4

Merged
lemuelroberto merged 5 commits into
emfga:mainfrom
lemuelroberto:develop
Aug 31, 2026
Merged

Prepare for the first release#4
lemuelroberto merged 5 commits into
emfga:mainfrom
lemuelroberto:develop

Conversation

@lemuelroberto

Copy link
Copy Markdown
Member
  • 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).

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).
@lemuelroberto lemuelroberto changed the title develop Prepare for the first release Aug 31, 2026
@lemuelroberto
lemuelroberto merged commit 018513d into emfga:main Aug 31, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant