From f4121b2166518f27daf59cc612642f9520737db6 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 9 Oct 2026 20:38:29 +0000 Subject: [PATCH 1/2] Point the release candidate page at RC2 RC2 replaces RC1's tags, assets and known issues; RC1 hosts and volumes can't be reused. Signed-off-by: Guanzhou Song --- getting-started/release-candidate.md | 51 ++++++++++++++++++---------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/getting-started/release-candidate.md b/getting-started/release-candidate.md index 504b5b3..b086514 100644 --- a/getting-started/release-candidate.md +++ b/getting-started/release-candidate.md @@ -1,43 +1,51 @@ --- title: Try the 1.0 Release Candidate -description: Try DocumentDB 1.0 RC1 from release assets or container images. For testing only, with no upgrade path and no fixes to RC1. No date for 1.0 yet. +description: Try DocumentDB 1.0 RC2 from release assets or container images. For testing only, with no upgrade path and no fixes to RC2. No date for 1.0 yet. --- # Try the 1.0 release candidate -[DocumentDB v1.0-RC1](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1) is a preview of 1.0 for testing. Try your applications and workloads against it and [report what breaks](#report-issues) before 1.0 ships. +[DocumentDB v1.0-RC2](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) is a preview of 1.0 for testing. Try your applications and workloads against it and [report what breaks](#report-issues) before 1.0 ships. There is no date for 1.0 yet. A release candidate is meant to be close to what 1.0 ships, apart from fixes found during testing; 1.0 follows once the release candidates stop turning up blocking issues. The upgrade and support policy from 1.0 onward will be published with the final release. > **For testing only.** Don't use a release candidate for production or for data you need to keep. > > - **No upgrade path.** Upgrades from 0.117 to an RC, between release candidates, and from an RC to 1.0 are not supported. Start from an empty instance or volume, and expect to discard it. -> - **No fixes to RC1.** Fixes go into the next release candidate or 1.0, not into RC1. Expect an RC2. +> - **No fixes to RC2.** Fixes go into the next release candidate or 1.0, not into RC2. > - **Not the default.** GitHub marks the RC as a pre-release. The package repository, the container `latest` tag and GitHub's latest release stay on the current stable release, v0.117-0. You only get the RC by asking for it explicitly, as shown below. +## Changes since RC1 + +- **Gateway v2 runtime.** The gateway now runs on its v2 runtime by default. +- **Init script errors stop startup.** RC1's known issue is fixed: an error in an `--init-data-path` script now stops the container with an error. The run isn't retried on restart, so fix the script and start from a new volume. +- **Permission fixes.** `find` and `aggregate` with `batchSize: 0` now check that the caller can read the collection, and `$merge` and `$out` now need insert or update permission on the target collection, not just read. + +The [changelog](https://github.com/documentdb/documentdb/blob/v1.0-RC2/CHANGELOG.md) lists every change. There is no upgrade from RC1: if you tested RC1, start RC2 on a fresh host or a new volume. + ## Container image -The RC images are tagged `pg15-1.0-rc1`, `pg16-1.0-rc1`, `pg17-1.0-rc1` and `pg18-1.0-rc1`, for Linux amd64 and arm64. Include the container's `Release Version` log line when you [report issues](#report-issues). Use a new volume, not one a 0.117 container has used: +The RC images are tagged `pg15-1.0-rc2`, `pg16-1.0-rc2`, `pg17-1.0-rc2` and `pg18-1.0-rc2`, for Linux amd64 and arm64. Include the container's `Release Version` log line when you [report issues](#report-issues). Use a new volume, not one a 0.117 or RC1 container has used: ```bash -docker run -dt -p 127.0.0.1:10260:10260 -v documentdb-rc1-data:/data --name docdb-rc1 \ +docker run -dt -p 127.0.0.1:10260:10260 -v documentdb-rc2-data:/data --name docdb-rc2 \ -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \ -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \ - ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0-rc1 + ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0-rc2 ``` Everything else in [DocumentDB Local](../documentdb-local/index.md) applies, with these differences: -- **Health check.** The first health check runs about 30 seconds after start. Wait until `docker inspect -f '{{.State.Health.Status}}' docdb-rc1` reports `healthy`. -- **A stale `postmaster.pid` refuses to start.** After `docker kill`, `docker rm -f` or a crash, the next container on that volume refuses to start; 0.117 removed the stale file automatically. Re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it. Run `docker stop` before `docker rm` to avoid this. As in 0.117, a second container on a volume that is already in use exits immediately. -- **Known issue: init script errors don't stop startup.** In RC1, an error in an `--init-data-path` script is logged but the container still reports success and marks the volume as initialized. Check `docker logs` after the first start; after fixing the script, start from a new volume. Fixed in the next release candidate. +- **Health check.** The first health check runs about 30 seconds after start. Wait until `docker inspect -f '{{.State.Health.Status}}' docdb-rc2` reports `healthy`. +- **Stale `postmaster.pid`.** After `docker kill`, `docker rm -f` or a crash, the next start removes the stale file, as 0.117 did, but only when the volume's lock shows an RC2 container wrote it. Otherwise it refuses to start: re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it. Don't share a volume between hosts. As in 0.117, a second container on a volume that is already in use exits immediately. +- **PostgreSQL loss stops the container.** If PostgreSQL inside the container stops, the gateway fails requests straight away and the container exits after 20 seconds (`DOCUMENTDB_POSTMASTER_EXIT_TIMEOUT`). - **`--disable-extended-rum` is ignored**, apart from a deprecation warning. - **`--toast-compression lz4|pglz|default`** is new and defaults to `lz4`. To remove the test instance and its data: ```bash -docker stop docdb-rc1 && docker rm docdb-rc1 && docker volume rm documentdb-rc1-data +docker stop docdb-rc2 && docker rm docdb-rc2 && docker volume rm documentdb-rc2-data ``` ## Linux packages @@ -46,14 +54,14 @@ The RC is not in the package repository. Use a clean, disposable Ubuntu 24.04 or ```sh curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh && -sh documentdb-install.sh --version v1.0-RC1 +sh documentdb-install.sh --version v1.0-RC2 ``` -It enables PGDG (plus EPEL and CRB on EL9), downloads this host's five RC1 packages from the [release](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1), verifies them against its `SHA256SUMS` and runs the setup wizard. It doesn't add the DocumentDB package repository, so the host never picks up a stable release by accident. PostgreSQL 18 is the default; add `--pg-major 17` for 17, or `--dry-run` to see the plan first. Without `--version`, the same installer sets up v0.117-0. +It enables PGDG (plus EPEL and CRB on EL9), downloads this host's five RC2 packages from the [release](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2), verifies them against its `SHA256SUMS` and runs the setup wizard. It doesn't add the DocumentDB package repository, so the host never picks up a stable release by accident. PostgreSQL 18 is the default; add `--pg-major 17` for 17, or `--dry-run` to see the plan first. Without `--version`, the same installer sets up v0.117-0. -After an RC run, the installer refuses that host, even in stable mode. Use a fresh host for anything else. +After an RC run, the installer refuses that host, even in stable mode or for a later RC, so an RC1 host can't take RC2. Use a fresh host for anything else. -To check what you got, run `dpkg-query -W 'documentdb*' '*-documentdb'` or `rpm -qa '*documentdb*'`. RC1 packages are version `1.0~rc1`, `documentdb-gateway --version` prints `1.0.0-rc1`, and the extension version is `1.0-0`. +To check what you got, run `dpkg-query -W 'documentdb*' '*-documentdb'` or `rpm -qa '*documentdb*'`. RC2 packages are version `1.0~rc2`, `documentdb-gateway --version` prints `1.0.0-rc2`, and the extension version is `1.0-0`. ### Manual installation @@ -89,8 +97,8 @@ sudo dnf -qy module disable postgresql Download and verify the release files: ```bash -base=https://github.com/documentdb/documentdb/releases/download/v1.0-RC1 -mkdir pkgs-rc1 && cd pkgs-rc1 && +base=https://github.com/documentdb/documentdb/releases/download/v1.0-RC2 +mkdir pkgs-rc2 && cd pkgs-rc2 && curl -fsSLO "$base/SHA256SUMS" && awk '{print $2}' SHA256SUMS | xargs -I{} curl -fsSLO "$base/{}" && sha256sum -c SHA256SUMS @@ -131,13 +139,20 @@ To remove the RC, uninstall its packages and discard the host or its data direct ## Known issues -- **The setup admin can't create users with `readAnyDatabase` or `readWriteAnyDatabase`** ([#752](https://github.com/documentdb/documentdb/issues/752)). `createUser` with those roles fails with `User is not authorized to perform this action`. This also affects v0.117-0. On a package install, create the user on the host instead: +- **`distinct` or `count` on a grouped view can crash the server.** `distinct` on a view whose pipeline ends in `$group`, or `count` with a query on such a view, crashes the PostgreSQL backend. PostgreSQL restarts and disconnects every other session. +- **An expensive `$replaceAll` can outlive `maxTimeMS`.** A very costly `$replaceAll` on a large string can keep running after `maxTimeMS` expires and can't be cancelled. +- **`updateOne` can miss a match.** With a filter on a field other than `_id`, `updateOne` can report no match when PostgreSQL runs the statement with a generic plan. This is rare with default settings. Setting `plan_cache_mode = force_custom_plan` in the PostgreSQL configuration avoids it. +- **The setup admin can't create or drop users.** The admin user created at setup can't run `createUser` or `dropUser` over the MongoDB protocol. On a package install, manage users on the host instead: ```bash sudo documentdb-gateway-admin create-user --username app --password-file app.pw \ --roles '[{"role":"readAnyDatabase","db":"admin"}]' + sudo documentdb-gateway-admin drop-user --username app ``` +- **Container options.** `--log-level` and `--enable-telemetry` have no effect, and a `--data-path` that contains a space fails. +- **Collation is off by default.** `find`, `aggregate` and `count` with a `collation` fail as unsupported unless `documentdb_core.enableCollation` is on. + ## Report issues -Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) and include `v1.0-RC1`, your PostgreSQL major version, and either the package versions or the `Release Version` line from `docker logs docdb-rc1`, which names the build commit. The [release notes](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC1) list what changed since 0.117. +Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) and include `v1.0-RC2`, your PostgreSQL major version, and either the package versions or the `Release Version` line from `docker logs docdb-rc2`, which names the build commit. The [release notes](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) list what changed since 0.117. From bf1cdd80ef29a2fa89779611525e7656173327b3 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 9 Oct 2026 20:38:53 +0000 Subject: [PATCH 2/2] Disclose the documentdb-local usage telemetry added in RC2 The RC2 image sends usage data by default; 0.117 images and native packages don't, so the text is scoped to RC2. Signed-off-by: Guanzhou Song --- documentdb-local/index.md | 12 +++++++++++- getting-started/release-candidate.md | 2 ++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 4e0573c..1c75ba4 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -116,7 +116,7 @@ The following table summarizes the available Docker commands for configuring the | Specify a directory of scripts for database initialization. | `--init-data-path [value]` | Overrides `INIT_DATA_PATH` environment variable | STRING | `/init_doc_db.d` | JavaScript files run alphabetically using `mongosh`, once per fresh data volume. Syntax or runtime errors abort initialization. An attempted script run is not repeated on restart, so fix the scripts and use a fresh volume to retry. | | Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | `true`, `false` (`SKIP_INIT_DATA` only - the flag itself takes no value) | N/A | Legacy alias for `--init-data false`. Note that `SKIP_INIT_DATA=false` does the opposite of the flag: with `INIT_DATA` unset it enables the built-in sample data. Does not affect `--init-data-path`. | | Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A (takes no value) | N/A | Extended RUM is enabled by default. **Known issue:** this flag does not currently disable it - the container still starts with `documentdb_extended_rum` configured. | -| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | **Known issue:** the value is validated at startup but no telemetry is currently emitted - the gateway's metrics and tracing exporters are disabled in this image, and an invalid value only serves to abort startup. | +| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | The gateway's operational metrics, unrelated to [usage telemetry](#usage-telemetry). **Known issue:** the value is validated at startup but no telemetry is currently emitted - the gateway's metrics and tracing exporters are disabled in this image, and an invalid value only serves to abort startup. | | Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | **Known issue:** the value is validated at startup but does not currently change what the container logs. To change the gateway's own verbosity, set the `DOCUMENTDB_LOG_LEVEL` environment variable instead; it takes a tracing filter such as `info` or `debug` (`quiet` is not one of its values). | > `--skip-init-data` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-extended-rum false` - is rejected as an unexpected argument and the container exits. @@ -134,6 +134,16 @@ docker run -dt \ --init-data true ``` +## Usage telemetry + +Starting with the 1.0 RC2 images (`pg15-1.0-rc2` to `pg18-1.0-rc2`), DocumentDB Local sends anonymous usage data by default. The 0.117 images used on this page send none, and neither do the native packages. + +At startup and then hourly, the image reports its version, platform and CPU architecture to [Scarf](https://scarf.sh). It never sends database, collection or user names, queries, documents or credentials. A `[TELEMETRY]` notice in the container log says when it is on. + +To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false`, `-e NO_ANALYTICS=1` or `-e DO_NOT_TRACK=1` before the image name, or `--disable-usage-telemetry` after it. In CI, turn it off explicitly: the image skips telemetry when `CI` is set inside the container, but `docker run` doesn't pass the host's `CI` through. `--enable-telemetry` is a separate setting for the gateway's own metrics and doesn't affect this. + +The [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-RC2/documentdb-local/PRIVACY.md) has the details. The image also includes it at `/home/documentdb/PRIVACY.md`. + ## Built-in sample data Release 0.117 replaces the earlier small `sampledb` seed with the complete `StoreData` dataset. Loading remains opt-in: add `--init-data true` to the container arguments, as in the example above. diff --git a/getting-started/release-candidate.md b/getting-started/release-candidate.md index b086514..1472dcb 100644 --- a/getting-started/release-candidate.md +++ b/getting-started/release-candidate.md @@ -17,6 +17,7 @@ There is no date for 1.0 yet. A release candidate is meant to be close to what 1 ## Changes since RC1 +- **Usage telemetry in the container image.** The RC2 image sends anonymous usage data by default; native packages send nothing. See [Container image](#container-image). - **Gateway v2 runtime.** The gateway now runs on its v2 runtime by default. - **Init script errors stop startup.** RC1's known issue is fixed: an error in an `--init-data-path` script now stops the container with an error. The run isn't retried on restart, so fix the script and start from a new volume. - **Permission fixes.** `find` and `aggregate` with `batchSize: 0` now check that the caller can read the collection, and `$merge` and `$out` now need insert or update permission on the target collection, not just read. @@ -36,6 +37,7 @@ docker run -dt -p 127.0.0.1:10260:10260 -v documentdb-rc2-data:/data --name docd Everything else in [DocumentDB Local](../documentdb-local/index.md) applies, with these differences: +- **Usage telemetry is on by default.** At startup and then hourly, the image reports its version, platform and CPU architecture to Scarf, and nothing about your data, queries or credentials. Turn it off with `-e DOCUMENTDB_USAGE_TELEMETRY=false`, `-e NO_ANALYTICS=1` or `-e DO_NOT_TRACK=1`, or pass `--disable-usage-telemetry` after the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry). - **Health check.** The first health check runs about 30 seconds after start. Wait until `docker inspect -f '{{.State.Health.Status}}' docdb-rc2` reports `healthy`. - **Stale `postmaster.pid`.** After `docker kill`, `docker rm -f` or a crash, the next start removes the stale file, as 0.117 did, but only when the volume's lock shows an RC2 container wrote it. Otherwise it refuses to start: re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it. Don't share a volume between hosts. As in 0.117, a second container on a volume that is already in use exits immediately. - **PostgreSQL loss stops the container.** If PostgreSQL inside the container stops, the gateway fails requests straight away and the container exits after 20 seconds (`DOCUMENTDB_POSTMASTER_EXIT_TIMEOUT`).