From fce03dd0b186d3ea5e7b851de1cfffba14aac494 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 24 Aug 2026 16:21:00 -0400 Subject: [PATCH] Document the v0.116-0 package layout The pre-built packages page still described v0.114-0: the release link and date, the feature summary, the package matrix, the example filenames, the install commands, and the GHCR tag list (which named pg15/16/17 and said `latest` aliases `pg17-0.114.0`). v0.116-0 also changed the shape of a release, so the page's central claim -- that a release publishes one extension package per PostgreSQL major -- was no longer true. Describe what a release now contains: the five packages and their roles, the two version grammars, and the Tier-1 matrix (Ubuntu 24.04 and RHEL-compatible 9 on PostgreSQL 17 and 18), with a pointer to the package repository for the distributions this release did not build. Give install commands that work. The packages depend on each other, so installing the meta package alone fails with an unmet `documentdb-18` dependency; the commands now pass the whole per-platform set at once. Add the setup wizard and connect steps, since installing the packages no longer leaves you one step from an endpoint, and note that the gateway binds all interfaces by default while the connect example says 127.0.0.1. Also correct two claims elsewhere that v0.116-0 invalidated: the gateway service IS now published as a release asset, and functions.md described v0.114-0 as "the current release". Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8df9084a-ccaf-432c-b015-2ccd8893a9d8 Signed-off-by: Guanzhou Song --- getting-started/prebuilt-packages.md | 117 ++++++++++++++++++++++----- postgres-api/configuration.md | 2 +- postgres-api/functions.md | 2 +- 3 files changed, 99 insertions(+), 22 deletions(-) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 63f7bdc..0122416 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -9,38 +9,108 @@ Download and install DocumentDB using the pre-built packages and container image ## Latest Release -The current release is [`v0.114-0`](https://github.com/documentdb/documentdb/releases/tag/v0.114-0), published on 2026-07-16. +The current release is [`v0.116-0`](https://github.com/documentdb/documentdb/releases/tag/v0.116-0), published on 2026-08-20. It also carries the changes prepared for `v0.115-0`, which was never published. -This release enables schema validation by default, extends `enableNewNamespaceValidation` to protect reserved collections in the `admin`, `local`, and `config` databases, adds non-blocking background builds for unique ordered indexes via `CREATE INDEX CONCURRENTLY` (enabled by default), lets the gateway be configured through `DOCUMENTDB_*` environment variables for systemd-managed installs (with a new `documentdb-gateway check` connectivity probe), and speeds up `$sample` after filter stages with a single-pass reservoir scan. +This release introduces a redesigned Linux packaging layout (see below), fixes a gateway connection-pool bug that evicted pools while they were still in use, fixes a backend crash on insert into a sharded collection from a pooled session on PostgreSQL 18.6 or newer, defaults TOAST compression to `lz4`, and stamps build provenance into the `documentdb-local` image. -> `v0.114-0` publishes Linux packages only. macOS and Windows installers are not part of this release. +> `v0.116-0` publishes Linux packages only. macOS and Windows installers are not part of this release. + +## What ships in a release + +Before `v0.116-0` a release published a single package per PostgreSQL major — the extension. It now publishes a set: + +| Package | Role | +| --- | --- | +| `documentdb` (meta) + `documentdb-N` | Full stand-alone install. Pins PostgreSQL major N and its extension, and owns the systemd lifecycle. The meta package pins PostgreSQL 18. | +| `postgresql-N-documentdb` | The PostgreSQL extension for major N (files only). | +| `documentdb-gateway` | Wire-protocol runtime that serves the MongoDB-compatible endpoint. | +| `documentdb-postgresql-tools` | Administrator helpers: `documentdb-tune`, `documentdb-createcluster`, `documentdb-register-gateway`, `documentdb-gateway-admin`. | +| `documentdb-common` | Shared, PostgreSQL-agnostic payload: `documentdb-setup`, the systemd template units, helper scripts and sample data. | + +Two version grammars are in play by design: on DEB the extension keeps the control-file form `0.116-0` while every other package uses `0.116.0`; on RPM everything is `0.116.0` (the extension's `-0` becomes the RPM release field, giving `0.116.0-1`). ## Package Matrix -| Package family | Supported distributions | PostgreSQL versions | Architectures | Downloads | +`v0.116-0` builds and tests a first-party matrix of Ubuntu 24.04 and RHEL-compatible 9: + +| Package family | Distributions | PostgreSQL versions | Architectures | Downloads | | --- | --- | --- | --- | --- | -| DEB | Debian 11, Debian 12, Debian 13, Ubuntu 22.04, Ubuntu 24.04 | 16, 17, 18 | amd64, arm64 | [v0.114-0 release assets](https://github.com/documentdb/documentdb/releases/tag/v0.114-0) | -| RPM | RHEL 8, RHEL 9 | 16, 17, 18 | x86_64, aarch64 | [v0.114-0 release assets](https://github.com/documentdb/documentdb/releases/tag/v0.114-0) | +| DEB | Ubuntu 24.04 | 17, 18 | amd64, arm64 | [v0.116-0 release assets](https://github.com/documentdb/documentdb/releases/tag/v0.116-0) | +| RPM | RHEL-compatible 9 | 17, 18 | x86_64, aarch64 | [v0.116-0 release assets](https://github.com/documentdb/documentdb/releases/tag/v0.116-0) | + +Other combinations — PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, RHEL-compatible 8 — are not built by first-party CI for this release. Build them on demand from the tag with the scripts in [`packaging/`](https://github.com/documentdb/documentdb/blob/main/packaging/README.md), or install the newest release that did build them from the package repository (see below). PostgreSQL 15 is extension-only: `documentdb-setup` and `documentdb-register-gateway` require PostgreSQL 16 or newer. + +Choose the asset whose filename matches your distribution, PostgreSQL major version, and CPU architecture. For example: + +- `ubuntu24.04-documentdb_0.116.0_all.deb` +- `ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb` +- `rhel9-postgresql18-documentdb-0.116.0-1.el9.x86_64.rpm` + +Every release also ships `SHA256SUMS` and `manifest.txt`. Verify what you downloaded: + +```bash +gh release download v0.116-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS +``` + +## Repository-backed install (recommended) + +Installing from is easier than downloading assets, because the package manager resolves the dependencies between the packages for you. See [Package Installation](https://documentdb.io/packages) for the exact command for your distribution. + +The repository also keeps the most recent package for distributions a given release did not build, so Ubuntu 22.04, Debian 11/12/13 and RHEL-compatible 8 continue to resolve the extension package from an earlier release. + +## Install from downloaded assets + +The packages depend on each other, so **installing the meta package on its own fails**: -Choose the asset whose filename matches your Linux distribution, PostgreSQL major version, and CPU architecture. For example: +```text +documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable +``` -- `ubuntu24.04-postgresql-17-documentdb_0.114-0_amd64.deb` -- `rhel9-postgresql17-documentdb-0.114.0-1.el9.x86_64.rpm` +Pass the whole set for your platform to one command. -## Install a DEB Package +### DEB (Ubuntu 24.04, PostgreSQL 18, amd64) ```bash -curl -LO https://github.com/documentdb/documentdb/releases/download/v0.114-0/ubuntu24.04-postgresql-17-documentdb_0.114-0_amd64.deb -sudo apt install ./ubuntu24.04-postgresql-17-documentdb_0.114-0_amd64.deb +sudo apt install ./ubuntu24.04-documentdb_0.116.0_all.deb \ + ./ubuntu24.04-documentdb-18_0.116.0_all.deb \ + ./ubuntu24.04-documentdb-common_0.116.0_all.deb \ + ./ubuntu24.04-documentdb-postgresql-tools_0.116.0_all.deb \ + ./ubuntu24.04-documentdb-gateway_0.116.0_amd64.deb \ + ./ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb ``` -## Install an RPM Package +### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64) ```bash -curl -LO https://github.com/documentdb/documentdb/releases/download/v0.114-0/rhel9-postgresql17-documentdb-0.114.0-1.el9.x86_64.rpm -sudo dnf install ./rhel9-postgresql17-documentdb-0.114.0-1.el9.x86_64.rpm +sudo dnf install ./documentdb-0.116.0-1.noarch.rpm \ + ./documentdb-18-0.116.0-1.noarch.rpm \ + ./documentdb-common-0.116.0-1.noarch.rpm \ + ./documentdb-postgresql-tools-0.116.0-1.noarch.rpm \ + ./documentdb-gateway-0.116.0-1.el9.x86_64.rpm \ + ./rhel9-postgresql18-documentdb-0.116.0-1.el9.x86_64.rpm ``` +The `ubuntu24.04-` and `rhel9-` filename prefixes disambiguate release assets; they are not part of the package name. + +Both families need the PostgreSQL upstream (PGDG) repository enabled first, and RHEL-compatible hosts additionally need EPEL and CRB. See [Package Installation](https://documentdb.io/packages) for those prerequisites. + +## Set up and connect + +Installing the packages puts files on disk. The setup wizard creates the PostgreSQL instance, installs the extensions, bootstraps the admin user and starts the gateway: + +```bash +sudo documentdb-setup --admin-user admin +``` + +It prompts for the admin password; for servers and CI pass `--admin-password-file ` or `--admin-password-stdin` together with `--yes`. Then connect (`mongosh` is not shipped by these packages): + +```bash +mongosh 'mongodb://admin:@127.0.0.1:10260/mydb?tls=true&tlsAllowInvalidCertificates=true' \ + --eval 'db.runCommand({ping: 1})' +``` + +> The gateway binds all interfaces (`0.0.0.0:10260`) by default, even though the connect string above says `127.0.0.1`. Firewall the port and supply a real certificate before exposing it to a network. + ## Docker Images Use the official `documentdb-local` image from GHCR: @@ -60,9 +130,16 @@ docker run -dt -p 10260:10260 --name documentdb-container ghcr.io/documentdb/doc > > **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly. -`v0.114-0` publishes the following multi-architecture tags (linux/amd64 and linux/arm64) to GHCR: +`v0.116-0` publishes the following multi-architecture tags (linux/amd64 and linux/arm64) to GHCR: -- `ghcr.io/documentdb/documentdb/documentdb-local:pg15-0.114.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:pg16-0.114.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.114.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:latest` (currently aliases `pg17-0.114.0`) +- `ghcr.io/documentdb/documentdb/documentdb-local:pg15-0.116.0` +- `ghcr.io/documentdb/documentdb/documentdb-local:pg16-0.116.0` +- `ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.116.0` +- `ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.116.0` +- `ghcr.io/documentdb/documentdb/documentdb-local:latest` (currently aliases `pg17-0.116.0`) + +Each image records the release it was built from in `/version.txt` and in its OCI labels: + +```bash +docker run --rm --entrypoint cat ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.116.0 /version.txt +``` diff --git a/postgres-api/configuration.md b/postgres-api/configuration.md index e47195e..0f052a8 100644 --- a/postgres-api/configuration.md +++ b/postgres-api/configuration.md @@ -50,7 +50,7 @@ Unlike the flags above, these two produce an error rather than a missing effect, The gateway (`pg_documentdb_gw`) reads its settings from a JSON configuration file and/or `DOCUMENTDB_*` environment variables. Environment variables override the JSON file, which makes them convenient for systemd-managed and container deployments. *(Environment-variable configuration added in v0.114-0.)* -> **Note:** The packaged gateway service (its systemd unit and `gateway.env` file) is not yet published as a release asset — the v0.114-0 GitHub release ships the PostgreSQL extension packages only. The `DOCUMENTDB_*` settings below apply to the `documentdb-gateway` binary (which the `documentdb-local` container image configures internally) and to downstream packaging that installs the systemd unit. +> **Note:** Since v0.116-0 the packaged gateway service — its systemd unit and per-major `gateway.env` file — is published as a release asset (`documentdb-gateway`, together with `documentdb-common`, which owns the unit templates). The `DOCUMENTDB_*` settings below apply to that packaged service, to the `documentdb-gateway` binary directly (which the `documentdb-local` container image configures internally), and to downstream packaging that installs its own unit. On a packaged install, `documentdb-setup` writes the managed block in `/etc/documentdb/local//gateway.env`; edits outside that block are preserved, but the managed block is rebuilt whenever the wizard re-runs. | Environment variable | Purpose | | --- | --- | diff --git a/postgres-api/functions.md b/postgres-api/functions.md index 83caddc..f2697d1 100644 --- a/postgres-api/functions.md +++ b/postgres-api/functions.md @@ -9,7 +9,7 @@ description: Reference for the PostgreSQL functions exposed by the pg_documentdb All BSON parameters are encoded as PostgreSQL `bson` values (provided by the `pg_documentdb_core` extension). For example, you can pass a literal BSON spec using the cast `'{ ... }'::documentdb_core.bson` in `psql`. -> **This page describes v0.114-0**, the current release. Behavior added upstream after that tag is not documented here. +> **This page describes v0.114-0.** It has not yet been revised for the current release (v0.116-0); behavior added upstream after the v0.114-0 tag is not documented here. > **Reading the signatures below.** Parameter names are the ones the extension actually declares in `pg_documentdb/sql/udfs/`, so they are safe to use in named-argument calls such as `p_database_name => 'mydb'`. They are unquoted identifiers, so PostgreSQL folds them to lower case — `\df documentdb_api.*` prints `commandspec` where the source writes `commandSpec`, and `bigint`/`boolean`/`double precision` where the source writes `int8`/`bool`/`float8`. Either spelling works in a call. Types are written unqualified: `bson` and `bsonsequence` live in `documentdb_core`. A function with **two or more** `OUT` parameters returns a `record` and should be called as `SELECT * FROM ...`; one with a single `OUT` parameter returns that parameter's type directly, so a plain `SELECT fn(...)` is fine. A few wire-protocol entry points are PostgreSQL `PROCEDURE`s and must be invoked with `CALL`; these are called out individually.