diff --git a/.github/release.json b/.github/release.json index 3a48fe6..c79fa55 100644 --- a/.github/release.json +++ b/.github/release.json @@ -1 +1 @@ -{"base":"2.0.0","prerelease":"alpha"} +{"base":"2.0.0","prerelease":""} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b7ccd37..d069ff2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,8 @@ go test -race -count=1 -timeout 8m ./... Select the pinned target for your platform from `internal/binaries/manifest.json`. Windows uses `x86_64-pc-windows-msvc`, including on ARM64. Linux targets distinguish -`gnu` and `musl`. Install the native prerequisites in [non-root execution](docs/non-root.md). +`gnu` and `musl`. Check the OS and loader requirements in [non-root execution](docs/non-root.md); +the corrected pinned bundles include their third-party runtime libraries. Without fixture variables, real PostgreSQL tests skip; that is not full validation. ## Coverage and checks @@ -57,7 +58,7 @@ change. Test mirror/download failures, immutable cache leases, unsafe archives a offline behavior when changing acquisition code. The master workflow publishes automatically only after every required job passes. -Releases currently use the alpha channel. See [release policy](docs/releases.md) before +Releases use the stable channel. See [release policy](docs/releases.md) before changing `.github/release.json`. Do not merge unfinished migrations merely to exercise publishing. Keep provider and hook reference code compilable with the normal module tests. diff --git a/README.md b/README.md index 2c1caff..6ad9e1e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Run real PostgreSQL in your tests. Each test gets its own database, an available port, and automatic cleanup. A CLI provides the same lifecycle for other languages. The production Go packages have **zero third-party dependencies**. -**v2 is available as an alpha release.** Requires Go 1.26 or newer. Upgrading from +**v2 is stable.** Requires Go 1.26 or newer. Upgrading from v1? Start with the [migration guide](docs/migration-v2.md). ## A database scoped to a test @@ -33,7 +33,8 @@ func TestRepository(t *testing.T) { ``` The first start downloads PostgreSQL and the matching supervisor; later starts -reuse the cache. PostgreSQL needs the [native runtime requirements for your OS](docs/non-root.md). +reuse the cache. The pinned PostgreSQL bundles include third-party runtime libraries; +the [OS and loader requirements](docs/non-root.md) still apply. Choose your own SQL driver, and close connection pools before test cleanup. For configuration, import `github.com/fergusstrange/embedded-postgres/v2` as `postgres` @@ -132,8 +133,9 @@ not a separate LTS edition. Binary checksums are pinned in the reviewed manifest automatic library releases do not silently change those pins. Native CI covers Linux and macOS AMD64/ARM64, Windows AMD64, and Windows ARM64 -with x64 PostgreSQL emulation. Alpine 3.21 AMD64 has a separate musl integration job (the upstream bundle -requires ICU 74; see the platform guide). +with x64 PostgreSQL emulation. Alpine 3.21 AMD64 has a separate musl integration job, +and published consumers cover native x64/ARM64 musl. The corrected bundles include +ICU; no host ICU 74 package is needed. See the [platform guide](docs/non-root.md). Other Linux architectures can use a source-built companion when a pinned bundle exists. FreeBSD needs a custom distribution and companion; it is not in the supported release matrix. diff --git a/docs/issues-v2.md b/docs/issues-v2.md index e35ef25..fc79ed4 100644 --- a/docs/issues-v2.md +++ b/docs/issues-v2.md @@ -8,8 +8,15 @@ that the v2 solution meets the original use case. Reporter confirmation is welco closure records implementation, not confirmation on every downstream setup. FreeBSD #169 remains open because its supported distribution and native CI work -are not complete. The separate Alpine update #172 also remains open: the current -musl PostgreSQL bundle requires ICU 74, which the proposed Alpine 3.24 image lacks. +are not complete. The separate Alpine update #172 still needs its dependency-update +review and CI. Its earlier host ICU 74 blocker is removed by the corrected pinned +bundles, which include ICU and other third-party runtime libraries. + +The later Arch Linux [issue #181](https://github.com/fergusstrange/embedded-postgres/issues/181) +was closed after the published alpha.5 and PostgreSQL 15–18 passed clean Arch +validation without `libxml2-legacy`. The +[report and reproduction steps](https://github.com/fergusstrange/embedded-postgres/issues/181#issuecomment-6259458842) +record the emulated x64 scope and invite the reporter's confirmation. ## Requests reviewed for v2 @@ -17,7 +24,7 @@ musl PostgreSQL bundle requires ICU 74, which the proposed Alpine 3.24 image lac |---|---|---| | [#170](https://github.com/fergusstrange/embedded-postgres/issues/170), Windows `.exe` lookup | Addressed | Platform suffix applied to every required tool; native Windows cache and lifecycle tests | | [#168](https://github.com/fergusstrange/embedded-postgres/pull/168), [#167](https://github.com/fergusstrange/embedded-postgres/issues/167), cleanup | Addressed with clarified ownership | Disposable children removed; shared cache intentionally retained; explicit lease-aware prune | -| [#164](https://github.com/fergusstrange/embedded-postgres/issues/164), update policy | Addressed | Pinned supported major releases, security checks, automatic tested master releases and explicit prerelease channel | +| [#164](https://github.com/fergusstrange/embedded-postgres/issues/164), update policy | Addressed | Pinned supported major releases, security checks, automatic tested master releases with reviewed channel settings | | [#161](https://github.com/fergusstrange/embedded-postgres/pull/161), [#128](https://github.com/fergusstrange/embedded-postgres/issues/128), dynamic ports | Addressed | `Port(0)`, `GetPort`, actual connection URL and bounded collision retries; parallel native tests | | [#160](https://github.com/fergusstrange/embedded-postgres/issues/160), parent death | Addressed | Independent owner-pipe supervision, Unix owned process groups, Windows Job Objects; forced termination and panic tests | | [#157](https://github.com/fergusstrange/embedded-postgres/issues/157), test timeouts | Addressed | Startup deadline, lifetime context, bounded shutdown, `eptest.Start` and `eptest.Run` | diff --git a/docs/migration-v2.md b/docs/migration-v2.md index 720954f..43eb74c 100644 --- a/docs/migration-v2.md +++ b/docs/migration-v2.md @@ -3,6 +3,12 @@ Change imports to `github.com/fergusstrange/embedded-postgres/v2`. v1 remains available under its original module path. v2 requires Go 1.26 or newer. +After updating imports, select the stable release: + +```bash +go get github.com/fergusstrange/embedded-postgres/v2@v2.0.0 +``` + | v1 usage | v2 behaviour or replacement | | --- | --- | | `NewDatabase`, `DefaultConfig`, `Start`, `Stop` | Retained; add `StartContext`, `StopContext`, or idempotent `Close` | @@ -19,7 +25,7 @@ available under its original module path. v2 requires Go 1.26 or newer. | `Logger(io.Writer)` | Retained; receives a redacted tail (up to 32 KiB) during cleanup | | Implicit lib/pq registration | Removed; explicitly import/register your own driver | -Defaults are PostgreSQL 18.6, database/user/password `postgres`, locale `C`, +Defaults are PostgreSQL 18.6 (distribution 18.6.1), database/user/password `postgres`, locale `C`, encoding `UTF8`, startup timeout two minutes, shutdown timeout ten seconds, loopback TCP, and no console logging. `Start` remains compatible with fixed port 5432. `eptest.Start` without a config uses an automatic port and automatic cleanup. diff --git a/docs/non-root.md b/docs/non-root.md index 46f257b..77b79f9 100644 --- a/docs/non-root.md +++ b/docs/non-root.md @@ -74,6 +74,16 @@ The Go executable is built with CGO_ENABLED=0; PostgreSQL remains a native binar Native CI tests both ordinary callers and a root test runner launching PostgreSQL as a separate user. +## Arch Linux + +The corrected PostgreSQL 15–18 pins include `libxml2.so.2`; installing +`libxml2-legacy` or setting `LD_LIBRARY_PATH` is not required. The published Go +module and CLI passed a clean Arch x64 container check with system libxml2 2.15, +including XML, `xml2`, `pgcrypto`, offline reuse, persistence and cleanup. +See the [results and reproduction steps](https://github.com/fergusstrange/embedded-postgres/issues/181#issuecomment-6259458842) +for the image pin and emulation scope. Explicitly selecting an old distribution +can still reproduce the missing-library error. + ## Alpine / musl The corrected musl bundles include ICU and the other third-party libraries; diff --git a/docs/release-notes-v2.md b/docs/release-notes-v2.md index e8c24e6..fd5984b 100644 --- a/docs/release-notes-v2.md +++ b/docs/release-notes-v2.md @@ -1,4 +1,4 @@ -# embedded-postgres v2 alpha +# embedded-postgres v2.0.0 Run real PostgreSQL in Go tests with automatic cleanup, or use the CLI with any test runner. v2 requires Go 1.26+ and has no third-party production Go dependencies. @@ -19,15 +19,17 @@ cover installation and configuration. ## Corrected PostgreSQL distributions -This alpha updates the default and supported pins to PostgreSQL 18.6.1, 17.11.1, +The default and supported distribution pins are PostgreSQL 18.6.1, 17.11.1, 16.15.1 and 15.19.1. These upstream packaging revisions include the Windows and relocatable-library fixes. New downloads use the corresponding SHA-256 pins; explicit older distribution versions retain their existing catalog entries. Windows ARM64 continues to select x64 PostgreSQL under emulation. See the [published-binary regression report](https://github.com/theseus-rs/postgresql-binaries/pull/35#issuecomment-6256273450) -for the platform matrix, verification evidence and two unreproduced Windows -findings. +for the platform matrix and verification evidence. The +[clean Arch regression](https://github.com/fergusstrange/embedded-postgres/issues/181#issuecomment-6259458842) +also verifies PostgreSQL 15–18 without `libxml2-legacy`, including XML, extensions, +offline reuse and persistent restart. The old bundle reproduces the original error. ## Included in v2 @@ -37,9 +39,12 @@ findings. explicit persistent-data storage. Caller-supplied data is never automatically erased. - Independent supervision for cleanup after owner exit or panic, and explicit Unix UID/GID support for tests running as root. +- Restricted Windows child tokens work from PowerShell and detached Node launches + while keeping administrator groups disabled. - Custom binary providers and lifecycle hooks for migrations and extensions. - CLI foreground, command-scoped and background modes, plus protocol 1 for wrappers. PostgreSQL's [native runtime requirements](https://github.com/fergusstrange/embedded-postgres/blob/master/docs/non-root.md) still apply. Source checkouts and local module replacements need an explicitly -selected supervisor. v2 remains a prerelease while downstream migrations are validated. +selected supervisor. The stable release follows downstream migration testing and +verification of the published Go module, CLI and Node wrapper on supported platforms. diff --git a/docs/releases.md b/docs/releases.md index 77a9424..444c08c 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,12 +1,12 @@ # Releases -v2 is available as an alpha. The Go module and CLI are released together on the +v2 is stable. The Go module and CLI are released together on the [releases page](https://github.com/fergusstrange/embedded-postgres/releases). The [migration guide](migration-v2.md) explains the changes from v1. ## Install -For Go tests, add the newest published v2 version (currently an alpha): +For Go tests, add the newest stable v2 version: ```bash go get github.com/fergusstrange/embedded-postgres/v2@latest @@ -23,18 +23,19 @@ export PATH="$HOME/.local/bin:$PATH" embedded-postgres exec -- npm test ``` -The installer selects the newest published v2 release, including alphas. To pin a -version, set `EP_VERSION` on the `bash` command: +The installer selects the newest published v2 release. It can also install +explicit prerelease tags. To pin a version, set `EP_VERSION` on the `bash` command: ```bash -curl -fsSL https://raw.githubusercontent.com/fergusstrange/embedded-postgres/master/install/install.sh | EP_VERSION=v2.0.0-alpha.1 bash +curl -fsSL https://raw.githubusercontent.com/fergusstrange/embedded-postgres/master/install/install.sh | EP_VERSION=v2.0.0 bash ``` Windows users can use Git Bash or the [PowerShell installer](../install/install.ps1). See the [CLI guide](cli.md) for installation paths and configuration. -PostgreSQL is downloaded on first use and cached for later tests. Its native -platform requirements still apply; see the [platform guide](non-root.md). +PostgreSQL is downloaded on first use and cached for later tests. The pinned +bundles include third-party runtime libraries; OS and loader requirements still +apply. See the [platform guide](non-root.md). ## What a release contains @@ -52,7 +53,7 @@ gh attestation verify ./embedded-postgres_linux_amd64 --repo fergusstrange/embed ## Maintainer release process -Every successful `master` push publishes the next alpha. No manual tag or version +Every successful `master` push publishes the next stable patch. No manual tag or version commit is needed. The workflow waits for all native tests, PostgreSQL 15–18, Alpine, minimum/current Go, security checks and **at least 90% aggregate production coverage**. The coverage report is available in the workflow artifacts. @@ -62,8 +63,8 @@ all review conversations resolved. `master` disallows force pushes and deletion. The release job builds and attests the binaries before publishing. Retrying the same commit resumes its draft or leaves an already published release unchanged. -PR, manual and scheduled workflows do not publish. Alpha releases do not replace -v1 as GitHub's latest stable release. +PR, manual and scheduled workflows do not publish. Stable v2 releases become +GitHub's latest release; v1 remains available under its original Go module path. After publication, the public **Published consumers** workflow installs the exact Go module from the public proxy, verifies its source revision and checksum, @@ -86,10 +87,11 @@ disabled. It never changes an existing consumer directory's ACL. Release settings live in [`.github/release.json`](../.github/release.json): -- `base: "2.0.0"`, `prerelease: "alpha"` produces `v2.0.0-alpha.1`, `.2`, and so on. -- After migration and downstream validation, set `prerelease` to `""` to publish - stable `v2.0.0`. Subsequent master builds increment the patch version. +- The current `base: "2.0.0"`, `prerelease: ""` starts at stable `v2.0.0`. + Subsequent master builds increment the patch version. - Set `base` explicitly when starting a new minor release. +- A nonempty `prerelease` channel is reserved for a deliberately reviewed future + prerelease series; it is not the current release policy. Actions are pinned to commit hashes and Dependabot groups their updates for review. The workflow checks that production Go code uses only the standard diff --git a/docs/v2-development.md b/docs/v2-development.md index a51f87a..12e8895 100644 --- a/docs/v2-development.md +++ b/docs/v2-development.md @@ -3,7 +3,9 @@ This is a historical record of the migration. Each entry describes the state at that milestone; later reviews supersede earlier pending checks and design notes. For current setup and published releases, use the [README](../README.md) and -[release guide](releases.md). +[release guide](releases.md). Early missing-library and host ICU notes describe +older bundles; the stable release uses corrected PostgreSQL 15–18 distributions. +See the current [platform guide](non-root.md) for runtime requirements. One implementation branch and one final PR. Each milestone has its own commit, validation, and diff review. PostgreSQL 14 and older are excluded. CircleCI is diff --git a/install/install.sh b/install/install.sh index 3b41cfe..832ed93 100755 --- a/install/install.sh +++ b/install/install.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # Usage: curl -fsSL https://raw.githubusercontent.com/fergusstrange/embedded-postgres/master/install/install.sh | bash -# Pin with EP_VERSION=v2.0.0-alpha.1; choose location with EP_INSTALL_DIR. +# Pin with EP_VERSION=v2.0.0; choose location with EP_INSTALL_DIR. set -euo pipefail repo=fergusstrange/embedded-postgres version=${EP_VERSION:-} diff --git a/scripts/check-published.py b/scripts/check-published.py index ff8d78f..721a7be 100644 --- a/scripts/check-published.py +++ b/scripts/check-published.py @@ -1,6 +1,6 @@ """Check a public Go module and CLI in an isolated consumer (no source override). -Usage: python scripts/check-published.py v2.0.0-alpha.5 COMMIT [EVIDENCE_DIR] +Usage: python scripts/check-published.py v2.0.0 COMMIT [EVIDENCE_DIR] Requires Go, Python and authenticated gh for public build-attestation verification. """ import hashlib