From 27c76fa36afc09cfa07a268908a62dae84ed131c Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 16 Oct 2026 13:46:53 -0400 Subject: [PATCH 01/13] Add the 1.0 release notes and retire the release candidate page Signed-off-by: Guanzhou Song --- getting-started/navigation.yml | 4 +- getting-started/release-candidate.md | 160 +-------------------------- getting-started/release-notes-1.0.md | 64 +++++++++++ 3 files changed, 71 insertions(+), 157 deletions(-) create mode 100644 getting-started/release-notes-1.0.md diff --git a/getting-started/navigation.yml b/getting-started/navigation.yml index 63c49d2..c0fb341 100644 --- a/getting-started/navigation.yml +++ b/getting-started/navigation.yml @@ -12,5 +12,5 @@ link: mongo-shell-quickstart.md - title: Pre-built Packages link: prebuilt-packages.md -- title: Try the 1.0 Release Candidate - link: release-candidate.md +- title: 1.0 Release Notes + link: release-notes-1.0.md diff --git a/getting-started/release-candidate.md b/getting-started/release-candidate.md index 1472dcb..458d390 100644 --- a/getting-started/release-candidate.md +++ b/getting-started/release-candidate.md @@ -1,160 +1,10 @@ --- -title: Try the 1.0 Release Candidate -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. +title: 1.0 Release Candidates +description: The DocumentDB 1.0 release candidates have ended. DocumentDB 1.0 is released; hosts and volumes that ran a release candidate can't be upgraded. --- -# Try the 1.0 release candidate +# 1.0 release candidates -[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. +The 1.0 release candidates have ended: [DocumentDB 1.0](release-notes-1.0.md) was released on 2026-10-19, from the same commit as v1.0-RC2. -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 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 - -- **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. - -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-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-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-rc2 -``` - -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`). -- **`--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-rc2 && docker rm docdb-rc2 && docker volume rm documentdb-rc2-data -``` - -## Linux packages - -The RC is not in the package repository. Use a clean, disposable Ubuntu 24.04 or RHEL-compatible 9 host that has never had DocumentDB installed and runs systemd (not WSL without systemd, a chroot or a plain container). Then run the installer with `--version`: - -```sh -curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh && -sh documentdb-install.sh --version v1.0-RC2 -``` - -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 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*'`. 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 - -Enable PGDG first, but not the DocumentDB package repository. On Ubuntu 24.04: - -```bash -sudo apt update && -sudo apt install -y postgresql-common gnupg && -sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y -``` - -On RHEL-compatible 9, also enable EPEL and CRB. Enable CRB on Rocky Linux, AlmaLinux or CentOS Stream 9: - -```bash -sudo dnf install -y dnf-plugins-core && -sudo dnf config-manager --set-enabled crb -``` - -Or on RHEL 9: - -```bash -sudo subscription-manager repos --enable "codeready-builder-for-rhel-9-$(arch)-rpms" -``` - -Then enable EPEL and PGDG: - -```bash -sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && -sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm && -sudo dnf -qy module disable postgresql -``` - -Download and verify the release files: - -```bash -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 -``` - -Continue only if every file reports `OK`. The install commands below check again and stop on any mismatch. - -Install the five packages for PostgreSQL 18. On Ubuntu 24.04: - -```bash -arch=$(dpkg --print-architecture) -sha256sum -c --quiet SHA256SUMS && -sudo apt install -y ./ubuntu24.04-documentdb-{18,common,postgresql-tools}_*_all.deb \ - ./ubuntu24.04-documentdb-gateway_*_"$arch".deb \ - ./ubuntu24.04-postgresql-18-documentdb_*_"$arch".deb -``` - -On RHEL-compatible 9: - -```bash -sha256sum -c --quiet SHA256SUMS && -sudo dnf install -y ./documentdb-{18,common,postgresql-tools}-[0-9]*.noarch.rpm \ - ./documentdb-gateway-*.el9.$(uname -m).rpm \ - ./rhel9-postgresql18-documentdb-*.el9.$(uname -m).rpm -``` - -For PostgreSQL 17, replace `18` with `17` in the first and last package names, and in `--pg-version` below. - -The setup wizard binds the gateway on all interfaces on port 10260, with a self-signed TLS certificate. On a host reachable from other networks, block port 10260 with the host firewall first. Then run the wizard: - -```bash -sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin -``` - -The wizard now sets `default_toast_compression = 'lz4'`. To keep another setting, run the wizard directly and pass it through `sudo`, for example `sudo DOCUMENTDB_TOAST_COMPRESSION=pglz documentdb-setup ...`; `default` leaves PostgreSQL's own setting alone. The installer doesn't forward this variable. - -To remove the RC, uninstall its packages and discard the host or its data directories. Don't reuse them for a stable installation. - -## Known issues - -- **`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-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. +Hosts and data volumes that ran a release candidate can't be upgraded to 1.0, by the installer or by hand. Install 1.0 on a fresh host or a new volume, following [Pre-built Packages](prebuilt-packages.md) or [DocumentDB Local](../documentdb-local/index.md), and move any data you need with `mongodump` and `mongorestore`. diff --git a/getting-started/release-notes-1.0.md b/getting-started/release-notes-1.0.md new file mode 100644 index 0000000..3761f98 --- /dev/null +++ b/getting-started/release-notes-1.0.md @@ -0,0 +1,64 @@ +--- +title: DocumentDB 1.0 Release Notes +description: What's new in DocumentDB 1.0, where to get it, how to upgrade from 0.117, and the known issues that ship with it. +--- + +# DocumentDB 1.0 release notes + +[DocumentDB v1.0-0](https://github.com/documentdb/documentdb/releases/tag/v1.0-0) was released on **2026-10-19**. It is built from the same commit as the second release candidate, v1.0-RC2. The [changelog](https://github.com/documentdb/documentdb/blob/v1.0-0/CHANGELOG.md) lists every change. + +## Where to get it + +| Channel | 1.0 version | Platforms | +| --- | --- | --- | +| [Linux packages](prebuilt-packages.md) | packages `1.0.0`, extension `1.0-0` | Ubuntu 24.04 and RHEL-compatible 9, PostgreSQL 17 and 18, amd64 and arm64 | +| [Container image](../documentdb-local/index.md) | `pg15-1.0.0` to `pg18-1.0.0`; `latest` is `pg17-1.0.0` | Linux amd64 and arm64 | +| [Kubernetes operator](../kubernetes-operator/index.md) | operator `1.0.0`, which runs engine `1.0-0` | Kubernetes 1.35+, or 1.33-1.34 with the `ImageVolume` feature gate | + +The SQL extension version is `1.0-0` everywhere, and `hello` reports it in `internal.documentdb_versions`. + +## What's new since 0.117 + +- **Usage telemetry in the container image.** The `documentdb-local` image reports its version, platform and CPU architecture to Scarf at startup and hourly, on by default. Native packages send nothing. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry) to turn it off. +- **Security fixes.** `find` and `aggregate` with `batchSize: 0` now check that the caller can read the collection. `$merge` and `$out` now need insert or update permission on the target collection, not just read. `createUser` and `updateUser` reject passwords that fail SASLprep. +- **Collation** now works with `count` and the `$stdDevPop`, `$stdDevSamp`, `$median` and `$percentile` accumulators, and applies to the symbol type. Collation is still off by default; see [Known issues](#known-issues). +- **Custom roles.** With `documentdb.enableRoleCrud` on (off by default), `createRole` and `dropRole` keep custom roles in a roles catalog. `updateRole` is still unsupported. +- **`compact`** reports `bytesFreed` as the measured change in on-disk size. +- **Gateway.** The gateway runs on its new v2 runtime by default. It now returns retryable or specific error codes for backend connection and pool failures instead of `InternalError`, and exits with an error instead of panicking when PostgreSQL is unreachable at startup. +- **Crash and correctness fixes**, including `$getField`/`$setField`/`$unsetField` on system variables, `$firstN`/`$lastN` without a sort, `$documents` inside `$facet`, `find`/`count`/`distinct` on views that end in `$group`, `$near`/`$geoNear` ordering on `2dsphere` indexes, overlapping `dropIndexes` deadlocks, and several RUM index scan and vacuum fixes. +- **Container behavior.** An error in an `--init-data-path` script now stops the container. A stale `postmaster.pid` left by an unclean stop is removed on the next start, and the container exits if PostgreSQL inside it stops. TOAST compression defaults to `lz4`, and `--disable-extended-rum` is deprecated and ignored. See [Container lifecycle](../documentdb-local/index.md#container-lifecycle). +- **Packages.** The setup wizard sets `default_toast_compression = 'lz4'`; pass `DOCUMENTDB_TOAST_COMPRESSION=pglz` or `default` through `sudo` to keep another setting. + +## Upgrading + +- **Packages:** 0.116 and 0.117 installations can be upgraded in place: upgrade the packages, then update the extensions. See [Upgrading to 1.0](prebuilt-packages.md#upgrading-to-10). +- **Containers:** a 1.0 image on an existing volume doesn't update the extensions. Move the data to a new volume with `mongodump` and `mongorestore`. See [Upgrading the image](../documentdb-local/index.md#upgrading-the-image). +- **Release candidates:** hosts and volumes that ran an RC can't be upgraded. Start 1.0 on a fresh host or a new volume. + +## Known issues + +- **The setup admin can't create or drop users** ([#752](https://github.com/documentdb/documentdb/issues/752)). `createUser` from the admin user created at setup fails with `User is not authorized to perform this action`. On a package install, manage users on the host instead: + + ```bash + printf 'Password for app: '; stty -echo; read -r APP_PASSWORD; stty echo; echo + printf '%s' "$APP_PASSWORD" | sudo documentdb-gateway-admin create-user --username app \ + --password-stdin --roles '[{"role":"readAnyDatabase","db":"admin"}]' + sudo documentdb-gateway-admin drop-user --username app + ``` + +- **A newer container image doesn't upgrade an existing volume** ([#773](https://github.com/documentdb/documentdb/issues/773)). The image never runs `ALTER EXTENSION ... UPDATE`, and a changed `--password` on an existing volume is ignored. +- **`updateOne` with `let` can miss a match.** An update with `multi: false` that filters on fields other than `_id` through `let` variables can report no match when PostgreSQL runs it with a generic plan. This is rare with default settings; setting `plan_cache_mode = force_custom_plan` in the PostgreSQL configuration avoids it. +- **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. +- **Collation is off by default.** `find`, `aggregate`, `count` and `delete` with a `collation` fail as unsupported unless `documentdb_core.enableCollation` is on. `distinct`, `findAndModify` and `update` don't support `collation` at all. +- **Container options that do nothing.** `--log-level` and `--enable-telemetry` are validated but have no effect, and a `--data-path` that contains a space fails. +- **Open packaging and container issues:** + - [#771](https://github.com/documentdb/documentdb/issues/771): package remove, purge, upgrade and rerun paths that can leave the stack down or stuck. + - [#759](https://github.com/documentdb/documentdb/issues/759): container init, runtime and quick-start gaps. + - [#758](https://github.com/documentdb/documentdb/issues/758): container settings that aren't secure by default. + - [#735](https://github.com/documentdb/documentdb/issues/735): gateway state ownership isn't preserved across an RPM erase and reinstall. + - [#685](https://github.com/documentdb/documentdb/issues/685): a `--password` argument is readable in the container's process list; pass `-e PASSWORD` instead. + - [#389](https://github.com/documentdb/documentdb/issues/389): the Debian packages lack a copyright file. + +## Report issues + +Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) with your DocumentDB and PostgreSQL versions, and either the package versions or the `Release Version` line from `docker logs`. From 1150cec467fb056d6f26d701dc7aa0705eeca8f1 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 16 Oct 2026 13:46:53 -0400 Subject: [PATCH 02/13] Point the packages page at 1.0 and document upgrading from 0.117 The build scripts need --version 1.0.0: v1.0-0 shares a commit with v1.0-RC2, so git describe can pick the RC tag and build 1.0~rc2. Signed-off-by: Guanzhou Song --- getting-started/prebuilt-packages.md | 107 ++++++++++++++++++++------- 1 file changed, 79 insertions(+), 28 deletions(-) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 9a47f22..a2e2612 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -19,7 +19,7 @@ Get first-party packages from [documentdb.io](https://documentdb.io/packages), e ## First-party packages -The current release is [`v0.117-0`](https://github.com/documentdb/documentdb/releases/tag/v0.117-0), published on **2026-09-10**. First-party CI builds and tests the full stack for: +The current release is [`v1.0-0`](https://github.com/documentdb/documentdb/releases/tag/v1.0-0), published on **2026-10-19**. See the [1.0 release notes](release-notes-1.0.md) for what changed and the known issues. First-party CI builds and tests the full stack for: | Distribution | PostgreSQL | Architectures | | --- | --- | --- | @@ -28,8 +28,6 @@ The current release is [`v0.117-0`](https://github.com/documentdb/documentdb/rel Ubuntu 24.04 with PostgreSQL 18 is the recommended default. Other targets may be available through PGDG or the build scripts; they are not part of this hosted matrix. -The 1.0 release candidate is available for testing but is not in the package repository; see [Try the 1.0 release candidate](release-candidate.md). - For a clean host, the installer configures repositories, installs packages, and runs setup: @@ -38,12 +36,12 @@ curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh && sh documentdb-install.sh ``` -This installs v0.117-0 on PostgreSQL 18. Use `--pg-major 17` for PostgreSQL 17. -The manual steps below install the same release. +This installs the current release on PostgreSQL 18. Use `--pg-major 17` for PostgreSQL 17. +The manual steps below install the same release. To move an existing installation to 1.0, see [Upgrading to 1.0](#upgrading-to-10) instead. ## Set up and connect -These steps are for a **new stand-alone installation**. For an existing deployment, read [Upgrades and retired targets](#upgrades-and-retired-targets) first. +These steps are for a **new stand-alone installation**. For an existing deployment, read [Upgrading to 1.0](#upgrading-to-10) first. ### 1. Install the stack @@ -129,7 +127,7 @@ sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -v ON_ERROR_STOP=1 -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;" ``` -In v0.117, both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`. +Both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`. For a **new** Debian/Ubuntu cluster, `sudo documentdb-createcluster 18 docdb --start` combines cluster creation, tuning, startup, and extension creation. Choose a cluster name that does not already exist. @@ -175,30 +173,32 @@ No package for your target? The supplied scripts build DEB or RPM packages with Use a Linux build environment with Git, Docker, Bash 4+, and GNU utilities, on the target architecture. For example, build the extension for Debian 12 and PostgreSQL 18: ```bash -git clone --depth 1 --branch v0.117-0 https://github.com/documentdb/documentdb.git +git clone --depth 1 --branch v1.0-0 https://github.com/documentdb/documentdb.git cd documentdb -./packaging/build_packages.sh --os deb12 --pg 18 --output-dir packages +./packaging/build_packages.sh --os deb12 --pg 18 --version 1.0.0 --output-dir packages ``` +Pass `--version 1.0.0` explicitly. The `v1.0-0` tag shares its commit with `v1.0-RC2`, and without `--version` the build takes its version from the tag `git describe` picks, which can be the release candidate. + For the full stand-alone DEB set, make `dpkg-deb` available on the build host, then build the gateway and shared packages: ```bash ./packaging/gateway/build_gateway_packages.sh --os deb12 --pg 18 \ - --version 0.117.0 --output-dir packages + --version 1.0.0 --output-dir packages ./packaging/build_extra_packages.sh --type deb --pg 18 \ - --version 0.117.0 --output-dir packages + --version 1.0.0 --output-dir packages ``` -Outputs go into `packages/`. RPM extras instead require host `rpmbuild` and applicable RPM macros. The [versioned packaging guide](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md) lists targets, prerequisites, and clean-install checks. +Outputs go into `packages/`. RPM extras instead require host `rpmbuild` and applicable RPM macros. The [versioned packaging guide](https://github.com/documentdb/documentdb/blob/v1.0-0/packaging/README.md) lists targets, prerequisites, and clean-install checks. Validate builds for targets outside the first-party CI matrix in your environment. PostgreSQL 15 is extension-only; package-managed gateway setup requires PostgreSQL 16 or newer. ## Download and verify -Use release assets when you need an exact first-party version rather than a repository install. `v0.117-0` includes 22 Linux packages, `SHA256SUMS`, and `manifest.txt`. +Use release assets when you need an exact first-party version rather than a repository install. Each release publishes its Linux packages with `SHA256SUMS` and `manifest.txt`. ```bash -gh release download v0.117-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS +gh release download v1.0-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS ``` This downloads all formats, architectures, and PostgreSQL major versions. Install only the matching subset below, not every downloaded file. @@ -214,11 +214,11 @@ These examples install `documentdb-18` and its dependencies; the optional `docum For arm64, replace `amd64` with `arm64`. Only the gateway and extension files are architecture-specific. ```bash -sudo apt install ./ubuntu24.04-documentdb-18_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-common_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-postgresql-tools_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-gateway_0.117.0_amd64.deb \ - ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb +sudo apt install ./ubuntu24.04-documentdb-18_1.0.0_all.deb \ + ./ubuntu24.04-documentdb-common_1.0.0_all.deb \ + ./ubuntu24.04-documentdb-postgresql-tools_1.0.0_all.deb \ + ./ubuntu24.04-documentdb-gateway_1.0.0_amd64.deb \ + ./ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb ``` ### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64) @@ -226,26 +226,77 @@ sudo apt install ./ubuntu24.04-documentdb-18_0.117.0_all.deb \ For arm64, replace `x86_64` with `aarch64`; leave `noarch` files unchanged. ```bash -sudo dnf install ./documentdb-18-0.117.0-1.noarch.rpm \ - ./documentdb-common-0.117.0-1.noarch.rpm \ - ./documentdb-postgresql-tools-0.117.0-1.noarch.rpm \ - ./documentdb-gateway-0.117.0-1.el9.x86_64.rpm \ - ./rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm +sudo dnf install ./documentdb-18-1.0.0-1.noarch.rpm \ + ./documentdb-common-1.0.0-1.noarch.rpm \ + ./documentdb-postgresql-tools-1.0.0-1.noarch.rpm \ + ./documentdb-gateway-1.0.0-1.el9.x86_64.rpm \ + ./rhel9-postgresql18-documentdb-1.0.0-1.el9.x86_64.rpm ``` For PostgreSQL 17, replace the two PostgreSQL-specific files with their `17` equivalents; the shared packages stay the same. The `documentdb` meta package always selects PG18. For extension-only use, install the extension and tools files, then [configure PostgreSQL](#extension-only-installation). For a full stack, [run the wizard](#2-run-the-setup-wizard) with the installed major: use `--pg-version 17` for PG17. -Filename prefixes such as `ubuntu24.04-` and `rhel9-` identify release assets, not package names. DEB extensions use version `0.117-0`, while other packages use `0.117.0`; RPMs use `0.117.0` with release `1` or `1.el9`. +Filename prefixes such as `ubuntu24.04-` and `rhel9-` identify release assets, not package names. DEB extensions use version `1.0-0`, while other packages use `1.0.0`; RPMs use `1.0.0` with release `1` or `1.el9`. ### Offline / air-gapped Release assets do not include the full dependency set. Stage PostgreSQL, its required extensions, and all other dependencies on a connected machine of the **same distro, release, and architecture**. Include dependencies already installed on the staging machine. Follow [Offline / air-gapped install](https://documentdb.io/docs/linux-packages/offline/) to serve the bundle as a local repository. -## Upgrades and retired targets +## Upgrading to 1.0 + +A 0.116 or 0.117 package installation can be upgraded in place; move the whole stack together. Upgrading the packages replaces the libraries and installs the upgrade scripts, but doesn't change the databases: each PostgreSQL instance keeps reporting the old extension version until its extensions are updated. Back up first; there is no downgrade. + +A host that ever ran a release candidate can't be upgraded, by the installer or by hand. Install 1.0 on a fresh host and move the data with `mongodump` and `mongorestore`. + +### Stand-alone stack + +Upgrade the packages, restart the stack so PostgreSQL loads the new libraries, then re-run the setup wizard with the options you installed with: + +```bash +# Debian / Ubuntu +sudo apt update && sudo apt install --only-upgrade documentdb documentdb-18 documentdb-common \ + documentdb-postgresql-tools documentdb-gateway postgresql-18-documentdb +# RHEL-compatible 9 +sudo dnf upgrade 'documentdb*' postgresql18-documentdb + +sudo systemctl restart documentdb-local@18.target +sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin +``` + +On a configured instance the wizard is a day-2 re-run: it keeps the gateway port and TLS settings, skips the existing admin user, and runs `ALTER EXTENSION ... UPDATE` for each DocumentDB extension. Use `--target-postgres-instance` instead of `--use-new-postgres-instance` if that is how you installed. For PostgreSQL 17, use `17` throughout. + +### Extension and gateway on your own PostgreSQL + +Upgrade the packages, restart PostgreSQL, then update the extensions in every database where you created them, in this order, because `ALTER EXTENSION` doesn't update dependencies. On Ubuntu with a cluster named `main`: + +```bash +sudo apt update && sudo apt install --only-upgrade postgresql-18-documentdb \ + documentdb-postgresql-tools documentdb-gateway +sudo systemctl restart postgresql@18-main +sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -v ON_ERROR_STOP=1 \ + -c "ALTER EXTENSION documentdb_core UPDATE;" \ + -c "ALTER EXTENSION documentdb UPDATE;" \ + -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;" \ + -c "ALTER EXTENSION documentdb_extended_rum UPDATE;" +sudo systemctl restart documentdb-gateway +``` + +### Check the version + +Connect with `mongosh` and run: + +```javascript +db.hello().internal.documentdb_versions +``` + +It should print `[ '1.0-0', '1.0.0' ]`: the installed extension version, then the loaded library version. If the first value is still `0.116-0` or `0.117-0`, the extensions weren't updated. See [`hello`](../api-reference/commands/diagnostic/hello.md). + +### Containers + +A newer DocumentDB Local image on an existing data volume does not update the extensions ([#773](https://github.com/documentdb/documentdb/issues/773)). Start 1.0 on a new volume and move the data with `mongodump` and `mongorestore`. See [Upgrading the image](../documentdb-local/index.md#upgrading-the-image). -**Pre-GA:** in-place package upgrades from earlier releases are not supported yet. Use a clean host or a new, empty PostgreSQL instance and plan data migration separately. Removing packages preserves PostgreSQL data; do not reset or reuse an adopted instance as an upgrade workaround. +## Retired targets The hosted matrix excludes PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, and RHEL-compatible 8. Since v0.116, older packages for retired targets are not carried forward, including PG16 extensions formerly hosted for Ubuntu 24.04 and EL9. Existing installations keep running, but cannot update or reinstall those packages from documentdb.io. @@ -265,4 +316,4 @@ sudo dnf clean all ## Container image -For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release v0.117 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version. +For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release 1.0 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version. From 7283e83014653a9a08342391c339f496b01751ab Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 16 Oct 2026 13:46:53 -0400 Subject: [PATCH 03/13] Update DocumentDB Local for the 1.0 image 1.0 turns usage telemetry on by default and doesn't upgrade an existing volume (#773). Signed-off-by: Guanzhou Song --- documentdb-local/index.md | 92 ++++++++++++++++++++++++--------------- 1 file changed, 57 insertions(+), 35 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 1c75ba4..3f9df8a 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -7,7 +7,9 @@ description: Learn how to install and run DocumentDB Local using Docker for loca DocumentDB Local provides a lightweight, containerized environment for developing and testing applications locally, including prototyping and integration testing. -The examples below use the PostgreSQL 17 image from release **0.117.0**. Other PostgreSQL major versions and image tags are listed in the [0.117 release](https://github.com/documentdb/documentdb/releases/tag/v0.117-0). To test the 1.0 release candidate, see [Try the 1.0 release candidate](../getting-started/release-candidate.md). +The examples below use the PostgreSQL 17 image from release **1.0.0**. Images for PostgreSQL 15 to 18 are tagged `pg15-1.0.0` to `pg18-1.0.0`, for Linux amd64 and arm64; `latest` points to `pg17-1.0.0`. Use a versioned tag when you need a reproducible setup. The [1.0 release notes](../getting-started/release-notes-1.0.md) list what changed and the known issues. + +> **Usage telemetry is on by default.** The 1.0 image reports its version, platform and CPU architecture to Scarf at startup and hourly. Turn it off with `-e DOCUMENTDB_USAGE_TELEMETRY=false`. See [Usage telemetry](#usage-telemetry). ## Prerequisites @@ -18,40 +20,38 @@ The examples below use the PostgreSQL 17 image from release **0.117.0**. Other P Get the Docker container image using `docker pull`. ```bash -docker pull ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 - +docker pull ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0 ``` ## Running -To run the container, use `docker run`. Afterwards, use `docker ps` to validate that the container is running. +Choose the admin credentials first, in the same terminal (this works in bash and zsh): ```bash -read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME -read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD -printf '\n' +printf 'DocumentDB username: '; read -r DOCUMENTDB_USERNAME +printf 'DocumentDB password: '; stty -echo; read -r DOCUMENTDB_PASSWORD; stty echo; echo export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD +``` -docker run -dt -p 127.0.0.1:10260:10260 --name docdb \ - ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \ - --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \ - --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" +Then start the container with `docker run`, and use `docker ps` to check that it is running: +```bash +docker run -dt -p 127.0.0.1:10260:10260 --name docdb \ + -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.0 docker ps ``` ```output -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -5aff734a3591 ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 "/bin/bash -c '/home…" 5 seconds ago Up 4 seconds 127.0.0.1:10260->10260/tcp docdb +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +5aff734a3591 ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0 "/bin/bash -c '/home…" 5 seconds ago Up 4 seconds (health: starting) 127.0.0.1:10260->10260/tcp docdb ``` -> The prompts export the credentials for the later client examples, and the guards -> prevent an empty value from falling through to the image's public defaults. If you -> open a new shell, set both variables again. The loopback binding makes the gateway -> reachable only from this host. To allow remote clients, change it to -> `-p 10260:10260` only after restricting the port with a firewall and configuring a -> certificate that remote clients can validate. +> The exported variables are reused by the client examples below; if you open a new shell, set them again. The guards stop an empty value from falling through to the image's public default credentials, which the container still accepts but warns about loudly. The credentials are passed as environment variables because `--username` and `--password` arguments stay visible in the container's process list. +> +> The loopback binding makes the gateway reachable only from this host. To allow remote clients, change it to `-p 10260:10260` only after restricting the port with a firewall and configuring a certificate that remote clients can validate. > > This container writes its database to `/data`, which the image declares as a Docker volume. The command above mounts nothing there, so each `docker run` gets a fresh anonymous volume: the data does not survive re-creating the container, and the old volume is left behind on the host until you prune it. Mount a named volume - `-v documentdb-data:/data` - to persist it. See `--data-path` in the table below. @@ -101,7 +101,7 @@ The following table summarizes the available Docker commands for configuring the |---|---|---|---|---|---| | Print the settings to stdout from the container | `--help`, `-h` | N/A | N/A | N/A | Display information on available configuration | | Specify the username for DocumentDB. | `--username [value]` | Overrides `USERNAME` environment variable | STRING | `default_user` | Username for DocumentDB. It may not be an internal DocumentDB role name, and it may not begin with `documentdb`, `citus`, `pg`, or `internal_role` (case-insensitive). The container rejects a reserved name and exits before starting anything. | -| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. | +| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. When the username or password is left at its default, the container prints a warning at startup; `DOCUMENTDB_ALLOW_DEFAULT_PASSWORD=true` silences it. Prefer the environment variable: a `--password` argument stays visible in the container's process list. A changed password on an existing data volume is ignored; the volume keeps the admin user it was initialized with. | | The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published. For local use, bind only to loopback - for example, `-p 127.0.0.1:10260:10260`. To use host port `27017` without changing the gateway port, publish `-p 127.0.0.1:27017:10260`; add `--documentdb-port 27017` only when changing the container-side port too. | | Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. | | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. The cluster this image initializes has a single superuser role, `documentdb`, so leave this at the default: any other value fails with `role "" does not exist` after PostgreSQL has already initialized, and the container exits. | @@ -113,13 +113,16 @@ The following table summarizes the available Docker commands for configuring the | Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | PEM-format private key. Must be set together with `--cert-path` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` | | Set the TLS mode for client connections. | `--tlsMode [value]` | Overrides `TLS_MODE` environment variable | `disabled`, `allowTLS`, `requireTLS` | `allowTLS` | With `allowTLS` the gateway accepts both plain and TLS connections; `disabled` behaves the same way. `requireTLS` rejects plain connections, so every client must connect with `tls=true`. | | Enable initialization with built-in sample data. | `--init-data [value]` | Overrides `INIT_DATA` environment variable | `true`, `false` | `false` | Loads the `StoreData` dataset once per fresh data volume. Use a new, empty volume to seed again; see [Built-in sample data](#built-in-sample-data). | -| 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. | +| 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. A syntax or runtime error stops the container with an error. The run isn't repeated on restart, so fix the scripts and start from a fresh volume. | | 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. | +| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A (takes no value) | N/A | **Deprecated and ignored**, apart from a warning at startup; it will be removed in a later release. `documentdb_extended_rum` is always enabled on a volume this image initializes. To use the plain `rum` access method instead, set `documentdb.alternate_index_handler_name = 'rum'` in the data volume's `postgresql.conf` and restart the container. | | 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). | +| Turn usage telemetry on or off. | `--usage-telemetry [value]` | Overrides `DOCUMENTDB_USAGE_TELEMETRY` environment variable | `true`, `false` (also `1`/`0`, `yes`/`no`, `on`/`off`, case-insensitive) | `true` | Reports the image version, platform and CPU architecture at startup and hourly. An unrecognized value is treated as `false` with a warning, so an opt-out can never stop the container from starting. See [Usage telemetry](#usage-telemetry). | +| Turn usage telemetry off. | `--disable-usage-telemetry` | N/A | N/A (takes no value) | N/A | Same as `--usage-telemetry false`. | +| Set TOAST compression. | `--toast-compression [value]` | Overrides `DOCUMENTDB_TOAST_COMPRESSION` environment variable | `lz4`, `pglz`, `default` | `lz4` | Compression for large values PostgreSQL stores out of line (TOAST). `lz4` decompresses large documents faster, `pglz` is PostgreSQL's built-in method, and `default` leaves the server's own setting alone. Affects newly written values only. Ignored, with a warning, when `--start-pg false`. | -> `--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. +> `--skip-init-data`, `--disable-usage-telemetry` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-usage-telemetry false` - is rejected as an unknown option and the container exits. A complete `docker run` showing where each kind of option goes - Docker options before the image name, container arguments after it. This is the command from the **Running** section above with a persistent volume and sample data added, so remove that container first with `docker rm -f docdb`: @@ -128,25 +131,35 @@ docker run -dt \ -p 127.0.0.1:10260:10260 \ -v documentdb-data:/data \ --name docdb \ - ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \ - --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \ - --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \ + -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.0 \ --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. +The 1.0 image sends usage data by default. The native packages send nothing. -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. +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. Scarf does see the source IP address of each request, so the privacy statement says the data shouldn't be assumed to be anonymous. 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. +To turn it off, add any of these before the image name: -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`. +```bash +-e DOCUMENTDB_USAGE_TELEMETRY=false +-e NO_ANALYTICS=1 +-e DO_NOT_TRACK=1 +``` + +or `--disable-usage-telemetry` (or `--usage-telemetry false`) after it. `NO_ANALYTICS` and `DO_NOT_TRACK` win over any setting that turns it on. To send the reports to your own collector instead, set `DOCUMENTDB_USAGE_TELEMETRY_ENDPOINT`. + +In CI, turn it off explicitly. The image skips telemetry when `CI`, `GITHUB_ACTIONS` or `TF_BUILD` is set inside the container, but `docker run` doesn't pass the host's variables 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-0/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. +The built-in sample data is the `StoreData` dataset. Loading it is opt-in: add `--init-data true` to the container arguments, as in the example above. | Collection | Documents | |---|---:| @@ -160,8 +173,17 @@ db.getSiblingDB("StoreData").stores.countDocuments({}) // 41505 db.getSiblingDB("StoreData").ratings.countDocuments({}) // 2 ``` -Seeding remains one-shot per data volume. Previously seeded volumes are **not automatically migrated** to StoreData; use a new, empty volume when you want the new sample dataset. A direct loader rerun tolerates duplicate keys rather than duplicating documents. See the [versioned sample-data guide](https://github.com/documentdb/documentdb/tree/v0.117-0/documentdb-local/sample-data) for manual loader instructions. +Seeding is one-shot per data volume; use a new, empty volume to seed again. A direct loader rerun tolerates duplicate keys rather than duplicating documents. See the [versioned sample-data guide](https://github.com/documentdb/documentdb/tree/v1.0-0/documentdb-local/sample-data) for manual loader instructions. + +## Container lifecycle + +- **Health check.** The image has a Docker health check; the first check runs about 30 seconds after start. `docker inspect -f '{{.State.Health.Status}}' docdb` reports `healthy` once DocumentDB accepts connections. +- **Stale `postmaster.pid`.** After `docker kill`, `docker rm -f`, an out-of-memory kill or a host crash, the next start removes the stale file, but only when the volume's lock shows a 1.0 container wrote it. Otherwise it refuses to start, because an older container may still be using the volume. Once nothing else uses it, re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it (`docker start` can't add the variable). Don't share a volume between hosts. 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`), so a restart policy can bring it back. + +## Upgrading the image +A newer image on an existing data volume doesn't update the DocumentDB extensions in it ([#773](https://github.com/documentdb/documentdb/issues/773)), so the volume keeps the old schema under the new binaries. Upgrading a volume in place is not supported in 1.0. To move data from a 0.117 container to 1.0, export it with `mongodump`, start a 1.0 container on a new volume, and load it with `mongorestore`. The PostgreSQL major version of the image must also match the one that initialized the volume. ## Feature support @@ -196,9 +218,9 @@ docker run -dt \ -v documentdb-data:/data \ -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \ --name docdb \ - ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \ - --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \ - --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" + -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.0 ``` Point it inside the data directory rather than at a volume of its own: the entrypoint takes ownership of the data directory on every start, whereas a separate volume is created root-owned and the gateway - which runs as an unprivileged user - cannot write its key there. The trade-off is that the same step runs `chmod -R 750` over that directory, so from the second start onwards the private key is group-readable rather than owner-only, and it is included in any backup of the data volume. From 2e5d80ee966c423867bc2c58080ef0807018f73c Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 16 Oct 2026 13:46:53 -0400 Subject: [PATCH 04/13] Note the 1.0 image's usage telemetry in the quick starts The quick starts pull :latest, which moves to 1.0. The prompts also switch to printf + read because zsh's read -p means something else. Signed-off-by: Guanzhou Song --- getting-started/index.md | 6 +++--- getting-started/mongo-shell-quickstart.md | 7 ++++--- getting-started/nodejs-setup.md | 7 ++++--- getting-started/python-setup.md | 7 ++++--- getting-started/vscode-quickstart.md | 9 ++++++--- 5 files changed, 21 insertions(+), 15 deletions(-) diff --git a/getting-started/index.md b/getting-started/index.md index a497e8c..c40a091 100644 --- a/getting-started/index.md +++ b/getting-started/index.md @@ -11,12 +11,12 @@ DocumentDB is an open-source document database platform built on PostgreSQL. It DocumentDB provides a NoSQL datastore implemented using PostgreSQL, giving developers complete visibility into the architecture and implementation of the engine. It's designed to offer: -- Full compatibility with the MongoDB wire protocol through the `pg_documentdb_gw` gateway +- MongoDB wire protocol compatibility through the `pg_documentdb_gw` gateway, so MongoDB drivers and tools connect unmodified - Public document CRUD and management APIs through the `pg_documentdb` extension - Native BSON document support via the `pg_documentdb_core` PostgreSQL extension - Advanced indexing capabilities including single field, multi-key, compound, text, geospatial, and vector indexes - Vector search functionality powered by the `pgvector` PostgreSQL extension -- Enterprise-grade security with SCRAM authentication +- SCRAM-SHA-256 authentication and TLS on the gateway - Full PostgreSQL compatibility for advanced SQL operations ## Key Features @@ -24,7 +24,7 @@ DocumentDB provides a NoSQL datastore implemented using PostgreSQL, giving devel - **PostgreSQL Foundation**: Built on the powerful PostgreSQL engine, allowing you to leverage both document and relational capabilities - **Open Source**: Released under the MIT license with no restrictions on usage, modification, or distribution - **Document Database Standard**: First implementation towards creating an open standard for document databases, similar to ANSI SQL for relational databases -- **Cloud Ready**: Supports multi-cloud deployments across major cloud providers with native integration in Azure Cosmos DB +- **Runs anywhere**: Linux packages, a container image for local development, and a Kubernetes operator for replicated deployments - **Developer Friendly**: Rich ecosystem of tools and extensions, including VS Code integration and MongoDB compatibility ## Architecture Components diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md index 24dff2a..675b21a 100644 --- a/getting-started/mongo-shell-quickstart.md +++ b/getting-started/mongo-shell-quickstart.md @@ -24,9 +24,8 @@ docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest # Tag the image for convenience docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb -read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME -read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD -printf '\n' +printf 'DocumentDB username: '; read -r DOCUMENTDB_USERNAME +printf 'DocumentDB password: '; stty -echo; read -r DOCUMENTDB_PASSWORD; stty echo; echo export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD # Run the container with your chosen username and password @@ -37,6 +36,8 @@ docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb \ > **Note:** The prompts export the credentials for the `mongosh` command below. The guards reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. If you open a new shell, set both environment variables again. > +> **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry). +> > **Network note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate. > > **Port note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port. diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md index 2e7bd14..068eff6 100644 --- a/getting-started/nodejs-setup.md +++ b/getting-started/nodejs-setup.md @@ -26,9 +26,8 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance # Tag the image for convenience docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb - read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME - read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD - printf '\n' + printf 'DocumentDB username: '; read -r DOCUMENTDB_USERNAME + printf 'DocumentDB password: '; stty -echo; read -r DOCUMENTDB_PASSWORD; stty echo; echo export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD # Run the container with your chosen username and password @@ -44,6 +43,8 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance > > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done` > +> **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry). +> > **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate. > > **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port. diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md index d8b8b1b..104a923 100644 --- a/getting-started/python-setup.md +++ b/getting-started/python-setup.md @@ -37,9 +37,8 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py # Tag the image for convenience docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb - read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME - read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD - printf '\n' + printf 'DocumentDB username: '; read -r DOCUMENTDB_USERNAME + printf 'DocumentDB password: '; stty -echo; read -r DOCUMENTDB_PASSWORD; stty echo; echo export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD # Run the container with your chosen username and password @@ -54,6 +53,8 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py > > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done` > + > **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry). + > > **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate. > > **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port. diff --git a/getting-started/vscode-quickstart.md b/getting-started/vscode-quickstart.md index 454cde9..7f7cc86 100644 --- a/getting-started/vscode-quickstart.md +++ b/getting-started/vscode-quickstart.md @@ -44,6 +44,8 @@ This is the fastest way to get a database running. The wizard handles the contai The defaults give you an available port (starting at `10260`), generated credentials, the `latest` official image, and optional sample data. Expand the advanced options to set the port, the image tag, or the credentials yourself, or to skip the sample data. + > **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. Extension 1.0.0 and later turn it off for containers it starts when VS Code telemetry is off. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry). + 4. Wait for setup to finish. The extension pulls the image if needed, creates a container named `vscode-documentdb-local` with a persistent volume, starts it, and waits until the database accepts connections. 5. Select **Open Connection** to reveal the saved connection in the Connections view, then expand it to browse databases and collections. @@ -65,9 +67,8 @@ Use this if you already run DocumentDB Local outside VS Code, or you want to man ```bash docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb - read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME - read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD - printf '\n' + printf 'DocumentDB username: '; read -r DOCUMENTDB_USERNAME + printf 'DocumentDB password: '; stty -echo; read -r DOCUMENTDB_PASSWORD; stty echo; echo export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"; then docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest || echo "No existing documentdb image to remove" @@ -97,6 +98,8 @@ Use this if you already run DocumentDB Local outside VS Code, or you want to man > > **Note:** Both versions prompt for credentials and reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. Enter the same values when the extension asks for the local connection credentials. > + > **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry). + > > **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate. > > **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and enter `27017` in the extension. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port. From 42aaba0887e7b3a061e8722ea7b124c1cbbc6eaa Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 16 Oct 2026 13:46:53 -0400 Subject: [PATCH 05/13] Re-audit the PostgreSQL API pages and hello against 1.0 Signed-off-by: Guanzhou Song --- api-reference/commands/diagnostic/hello.md | 10 +++---- postgres-api/configuration.md | 34 +++++++++++++-------- postgres-api/functions.md | 35 +++++++++++----------- postgres-api/index.md | 19 ++++++++++-- 4 files changed, 61 insertions(+), 37 deletions(-) diff --git a/api-reference/commands/diagnostic/hello.md b/api-reference/commands/diagnostic/hello.md index c261eb1..c1482aa 100644 --- a/api-reference/commands/diagnostic/hello.md +++ b/api-reference/commands/diagnostic/hello.md @@ -9,7 +9,7 @@ category: diagnostic The `hello` command returns a document describing the role of the DocumentDB server, along with connection limits, supported authentication mechanisms, and the version of the DocumentDB engine you are connected to. It's the recommended way to discover the DocumentDB version from a MongoDB client, since the `internal.documentdb_versions` field reports the underlying engine version rather than only the emulated MongoDB wire-protocol version. -The versions in `internal.documentdb_versions` come from the backend DocumentDB PostgreSQL extension, not from the gateway. The array reports two values: the installed SQL extension version (from the `pg_extension` catalog, in `major-minor` form such as `0.113-0`) followed by the loaded binary version (from `documentdb_api.binary_version()`, in dotted form such as `0.113.0`). In PostgreSQL, the installed extension version *is* the schema version — it tracks which SQL upgrade scripts have been applied — so the first value reflects the schema currently installed in the database. These two values normally describe the same release and differ only in formatting, but they can diverge during an upgrade — for example, when the shared library has been updated but `ALTER EXTENSION documentdb UPDATE` hasn't yet been run. A mismatch such as `["0.112-0", "0.113.0"]` indicates the SQL schema is behind the loaded binary. +The versions in `internal.documentdb_versions` come from the backend DocumentDB PostgreSQL extension, not from the gateway. The array reports two values: the installed SQL extension version (from the `pg_extension` catalog, such as `1.0-0`) followed by the loaded binary version (from `documentdb_api.binary_version()`, in dotted form such as `1.0.0`). In PostgreSQL, the installed extension version *is* the schema version — it tracks which SQL upgrade scripts have been applied — so the first value reflects the schema currently installed in the database. These two values normally describe the same release and differ only in formatting, but they can diverge during an upgrade — for example, after the 1.0 packages are installed over 0.117 but before `ALTER EXTENSION documentdb UPDATE` has been run. A mismatch such as `["0.117-0", "1.0.0"]` indicates the SQL schema is behind the loaded binary. ## Syntax @@ -42,7 +42,7 @@ The response includes the following fields. Fields marked as DocumentDB-specific | **`readOnly`** | `true` when the connection is read-only. | | **`connectionId`** | Identifier of the current connection. | | **`saslSupportedMechs`** | Authentication mechanisms the server supports, for example `SCRAM-SHA-256`. | -| **`internal.documentdb_versions`** | (DocumentDB-specific) Versions reported by the backend DocumentDB PostgreSQL extension: the installed SQL extension version — which in PostgreSQL is the schema version (`major-minor`, for example `0.113-0`) — followed by the loaded binary version (dotted, for example `0.113.0`). These normally match and diverge only during an upgrade. | +| **`internal.documentdb_versions`** | (DocumentDB-specific) Versions reported by the backend DocumentDB PostgreSQL extension: the installed SQL extension version — which in PostgreSQL is the schema version (for example `1.0-0`) — followed by the loaded binary version (dotted, for example `1.0.0`). These normally match and diverge only during an upgrade. | | **`ok`** | `1` when the command succeeds. | ## Examples @@ -75,8 +75,8 @@ The server returns a document similar to the following: ], "internal": { "documentdb_versions": [ - "0.113-0", - "0.113.0" + "1.0-0", + "1.0.0" ], "kind": "" }, @@ -95,7 +95,7 @@ db.runCommand({ hello: 1 }).internal.documentdb_versions The command returns an array with the installed SQL extension version followed by the loaded binary version: ```json -[ "0.113-0", "0.113.0" ] +[ "1.0-0", "1.0.0" ] ``` The first value is the installed SQL extension version — the schema version, from the `pg_extension` catalog — and the second is the compiled binary version. They normally describe the same release and differ only in formatting. diff --git a/postgres-api/configuration.md b/postgres-api/configuration.md index afac91a..7574ac9 100644 --- a/postgres-api/configuration.md +++ b/postgres-api/configuration.md @@ -1,11 +1,11 @@ --- title: Configuration -description: Server GUCs and gateway environment variables for configuring DocumentDB, including the RUM library default introduced in v0.117-0. +description: Server GUCs and gateway environment variables for configuring DocumentDB 1.0, including the required extended RUM index library, collation, and role management flags. --- # Configuration -DocumentDB is configured at two layers: the PostgreSQL extension (via GUCs in `postgresql.conf`) and the gateway process (via environment variables or a JSON config file). This page covers the most commonly adjusted settings, including the RUM library default introduced in **v0.117-0**. +DocumentDB is configured at two layers: the PostgreSQL extension (via GUCs in `postgresql.conf`) and the gateway process (via environment variables or a JSON config file). This page covers the most commonly adjusted settings in DocumentDB 1.0. ## Extension GUCs @@ -15,28 +15,38 @@ DocumentDB is configured at two layers: the PostgreSQL extension (via GUCs in `p | GUC | Default | Description | | --- | --- | --- | -| `documentdb.enableSchemaValidation` | `on` (since v0.114-0) | Enforces collection `$jsonSchema` validators on write operations. When `off`, a collection's validator is stored but not enforced. | +| `documentdb.enableSchemaValidation` | `on` | Enforces collection `$jsonSchema` validators on write operations. When `off`, a collection's validator is stored but not enforced. | -Collections with a `validator` are enforced on `insert`, `update`, `findAndModify`, and aggregation output stages (`$merge`, `$out`) when the collection's `validationLevel` is not `off` and its `validationAction` is `error`. (A `validationAction` of `warn` is not rejected on the write path, and a write that sets `bypassDocumentValidation` skips enforcement — see `documentdb.enableBypassDocumentValidation`.) Prior to v0.114-0 enforcement was opt-in; it is now enabled by default. +Collections with a `validator` are enforced on `insert`, `update`, `findAndModify`, and aggregation output stages (`$merge`, `$out`) when the collection's `validationLevel` is not `off` and its `validationAction` is `error`. (A `validationAction` of `warn` is not rejected on the write path, and a write that sets `bypassDocumentValidation` skips enforcement — see `documentdb.enableBypassDocumentValidation`.) ### RUM index library | GUC | Default | Description | | --- | --- | --- | -| `documentdb.rum_library_load_option` | `require_documentdb_extended_rum` (since v0.117-0) | Requires the DocumentDB extended RUM library on every supported PostgreSQL major version, not only PG18. Set this in `postgresql.conf` and restart PostgreSQL for a change to take effect. | +| `documentdb.rum_library_load_option` | `require_documentdb_extended_rum` | Requires the DocumentDB extended RUM library (`pg_documentdb_extended_rum`) on every supported PostgreSQL major version. Set this in `postgresql.conf` and restart PostgreSQL for a change to take effect. | The package setup wizard and container startup handle the required extension setup. For a manually configured PostgreSQL instance, create both `documentdb` and `documentdb_extended_rum`; `CREATE EXTENSION documentdb CASCADE` does not create `documentdb_extended_rum` automatically. Follow the [package setup guidance](https://documentdb.io/docs/getting-started/packages/) before creating indexes. -Setting the option to `none` opts out of the library-load requirement. +Setting the option to `none` opts out of the requirement and loads the upstream `rum` library instead; `prefer_documentdb_extended_rum` tries the extended library and falls back to `rum` if it cannot be loaded. ### Non-blocking unique index builds | GUC | Default | Description | | --- | --- | --- | -| `documentdb.enableNonBlockingUniqueIndexBuild` | `on` (since v0.114-0) | Builds unique ordered indexes without holding a long write lock, using `CREATE INDEX CONCURRENTLY` with post-processing to register the exclusion constraint and validate existing rows. | +| `documentdb.enableNonBlockingUniqueIndexBuild` | `on` | Builds unique ordered indexes without holding a long write lock, using `CREATE INDEX CONCURRENTLY` with post-processing to register the exclusion constraint and validate existing rows. | When enabled, creating a unique ordered index on an existing collection no longer blocks concurrent writes for the duration of the build. +### Collation + +| GUC | Default | Description | +| --- | --- | --- | +| `documentdb_core.enableCollation` | `off` | Accepts the `collation` option on queries. It is defined by `pg_documentdb_core`, hence the `documentdb_core.` prefix, and can be set per session. | + +While `off`, `find`, `aggregate`, and `count` reject a `collation` option with "collation is not supported in the find command yet." (or `aggregate` / `count` in place of `find`). `distinct` rejects `collation` whether or not the flag is on. Setting `documentdb.skipFailOnCollation` (default `off`) makes these commands ignore the option instead, so they compare strings by binary value. + +With the flag on, a few aggregation stages still reject a collation, including `$bucket`, `$bucketAuto`, `$densify`, `$fill`, `$geoNear`, `$merge`, `$setWindowFields`, and `$sortByCount`. + ### Off-by-default feature flags These flags gate functionality that is otherwise silently unavailable — in each case the command still succeeds, so the symptom is a missing effect rather than an error. @@ -53,14 +63,14 @@ Unlike the flags above, these two produce an error rather than a missing effect, | GUC | Default | Description | | --- | --- | --- | -| `documentdb.enableRoleCrud` | `off` (since v0.108-0) | Enables role CRUD through the data plane. While `off`, `create_role`, `drop_role`, and `roles_info` each raise before doing any work, for example "The CreateRole command is currently unsupported." Note that `update_role` is not implemented in any case. | -| `documentdb.enableRolesAdminDBCheck` | `on` (since v0.109-0) | Requires the wire-protocol role commands to be issued against the `admin` database, raising "CreateRole must be called from 'admin' database." otherwise. The user management commands are governed separately by `documentdb.enableUsersAdminDBCheck`, which is `off` by default. | +| `documentdb.enableRoleCrud` | `off` | Enables custom roles through the data plane. When `on`, `createRole` creates the role and records it in the `documentdb_api_catalog.roles` table, and `dropRole` drops only roles recorded there. While `off`, `create_role`, `drop_role`, and `roles_info` each raise before doing any work, for example "The CreateRole command is currently unsupported." `update_role` is not implemented either way and always raises "UpdateRole command is not supported in preview." | +| `documentdb.enableRolesAdminDBCheck` | `on` | Requires the wire-protocol role commands to be issued against the `admin` database, raising "CreateRole must be called from 'admin' database." otherwise. The user management commands are governed separately by `documentdb.enableUsersAdminDBCheck`, which is `off` by default. | ## Gateway configuration -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.)* +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. -> **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. +> **Note:** 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 | | --- | --- | @@ -76,7 +86,7 @@ For systemd-managed installs these are typically set through the unit's `Environ ### Connectivity check -The gateway binary provides a `check` subcommand (added in v0.114-0) that acts as a post-install connectivity probe: +The gateway binary provides a `check` subcommand that acts as a post-install connectivity probe: ```bash documentdb-gateway check [--config ] diff --git a/postgres-api/functions.md b/postgres-api/functions.md index 1402de4..c6eb4c3 100644 --- a/postgres-api/functions.md +++ b/postgres-api/functions.md @@ -1,6 +1,6 @@ --- title: Functions -description: Reference for the PostgreSQL functions exposed by the pg_documentdb extension in v0.114-0, including CRUD, schema, index, diagnostics, user and role management. +description: Reference for the PostgreSQL functions exposed by the pg_documentdb extension in DocumentDB 1.0, including CRUD, schema, index, diagnostics, user and role management. --- # Functions @@ -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.** It has not yet been revised for the current release (v0.117-0); behavior added upstream after the v0.114-0 tag is not documented here. +> **This page describes DocumentDB 1.0** (extension version `1.0-0`). > **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. @@ -25,7 +25,7 @@ Functions for creating, reading, updating, and deleting documents. | `documentdb_api.find_and_modify(p_database_name text, p_message bson, p_transaction_id text DEFAULT NULL, OUT p_result bson, OUT p_success boolean)` | Executes a MongoDB `findAndModify` command. | | `documentdb_api.insert_one(p_database_name text, p_collection_name text, p_document bson, p_transaction_id text DEFAULT NULL)` | Convenience wrapper that inserts a single document by database and collection name and returns the `insert` response. | | `documentdb_api_internal.insert_one(p_collection_id bigint, p_shard_key_value bigint, p_document bson, p_transaction_id text)` | **Deprecated and non-functional.** The implementation is a stub that always raises `insert_one is deprecated and should not be called`. Use the public `documentdb_api.insert_one` above. | -| `CALL documentdb_api.bulkWrite(p_command bson, p_ops bsonsequence DEFAULT NULL, p_ns_info bsonsequence DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | **Command surface only — not implemented in v0.114-0.** The `PROCEDURE` exists (its SQL definition landed in v0.111-0) but every call raises `bulkWrite is not yet implemented`, and it also rejects being called inside a transaction. | +| `CALL documentdb_api.bulkWrite(p_command bson, p_ops bsonsequence DEFAULT NULL, p_ns_info bsonsequence DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | **Not implemented in 1.0.** The `PROCEDURE` exists but every call raises `bulkWrite is not yet implemented`, and it also rejects being called inside a transaction. | | `documentdb_api.find_cursor_first_page(database text, commandSpec bson, cursorId int8 DEFAULT 0, OUT cursorPage bson, OUT continuation bson, OUT persistConnection bool, OUT cursorId int8)` | Opens a cursor for a `find` command and returns its first page. Omit `cursorId` to have the server generate one. | | `documentdb_api.aggregate_cursor_first_page(database text, commandSpec bson, cursorId int8 DEFAULT 0, OUT cursorPage bson, OUT continuation bson, OUT persistConnection bool, OUT cursorId int8)` | Opens a cursor for an `aggregate` command and returns its first page. Omit `cursorId` to have the server generate one. | | `documentdb_api.list_collections_cursor_first_page(database text, commandSpec bson, cursorId int8 DEFAULT 0, OUT cursorPage bson, OUT continuation bson, OUT persistConnection bool, OUT cursorId int8)` | Returns the `listCollections` result. Despite the name this is always a single batch — see the note below. | @@ -43,7 +43,7 @@ Functions for creating, reading, updating, and deleting documents. ### Write procedures -`insert` and `update` are also exposed as `PROCEDURE`s. `delete` has no procedure form in v0.114-0. +`insert`, `update`, and `delete` are also exposed as `PROCEDURE`s. `delete` has a `_txn_proc` form but no `_bulk` form. | Procedure | Description | | --- | --- | @@ -51,10 +51,11 @@ Functions for creating, reading, updating, and deleting documents. | `CALL documentdb_api.update_bulk(p_database_name text, p_update bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | `update` equivalent of `insert_bulk`. | | `CALL documentdb_api.insert_txn_proc(p_database_name text, p_insert bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | Inserts documents without opening a subtransaction per statement. | | `CALL documentdb_api.update_txn_proc(p_database_name text, p_update bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | `update` equivalent of `insert_txn_proc`. | +| `CALL documentdb_api.delete_txn_proc(p_database_name text, p_delete bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | `delete` equivalent of `insert_txn_proc`. | -> **None of these procedures may be called inside an explicit transaction block.** Each one raises `the insert procedure cannot be used in transactions. Please use the insert function instead` (`ERRCODE_DOCUMENTDB_OPERATIONNOTSUPPORTEDINTRANSACTION`) when it detects an open transaction. They differ from each other only in commit granularity, not in transaction support: `_bulk` commits per sub-batch, `_txn_proc` skips the per-statement subtransaction. Inside a transaction, use the plain `insert`/`update` functions. +> **None of these procedures may be called inside an explicit transaction block.** Each one raises an error such as `the insert procedure cannot be used in transactions. Please use the insert function instead` (`ERRCODE_DOCUMENTDB_OPERATIONNOTSUPPORTEDINTRANSACTION`) when it detects an open transaction. They differ from each other only in commit granularity, not in transaction support: `_bulk` commits per sub-batch, `_txn_proc` skips the per-statement subtransaction. Inside a transaction, use the plain `insert`/`update`/`delete` functions. -> **The gateway does not use these by default.** Both are gated by gateway settings that default to `false` — `enableWriteProcedures` selects the `_txn_proc` variants and `enableWriteProceduresWithBatchCommit` selects the `_bulk` variants. Out of the box every wire-protocol write goes through `documentdb_api.insert` / `documentdb_api.update`. +> **The gateway does not use these by default.** They are gated by gateway settings that default to `false` — `enableWriteProcedures` selects the `_txn_proc` variants and `enableWriteProceduresWithBatchCommit` selects the `_bulk` variants (insert and update only) — and even when enabled the gateway uses them only for writes outside a transaction. Out of the box every wire-protocol write goes through `documentdb_api.insert` / `documentdb_api.update` / `documentdb_api.delete`. ## Collection and Database Management @@ -68,13 +69,13 @@ Functions for managing collections, views, databases, and sharding. | `documentdb_api.rename_collection(p_database_name text, p_collection_name text, p_target_name text, p_drop_target bool DEFAULT false)` | Renames a collection using explicit arguments. | | `documentdb_api.rename_collection(p_commandspec bson)` | Overload taking a wire-protocol `renameCollection` BSON spec. This is the form the gateway calls. | | `documentdb_api.drop_database(p_database_name text, p_write_concern bson DEFAULT NULL)` | Drops a database and all of its collections. | -| `documentdb_api.list_databases(p_list_databases_spec bson)` | Returns information about all databases (added in v0.102-0). | +| `documentdb_api.list_databases(p_list_databases_spec bson)` | Returns information about all databases. | | `documentdb_api.shard_collection(p_database_name text, p_collection_name text, p_shard_key bson, p_is_reshard bool DEFAULT true)` | Shards or reshards a collection on the supplied key. This is the form the gateway calls. **Pass `p_is_reshard => false` when sharding for the first time** — see the notes below. | | `documentdb_api.shard_collection(p_shard_key_spec bson)` | Single-argument overload taking the whole request as BSON. | | `documentdb_api.reshard_collection(p_shard_key_spec bson)` | Re-shards an already-sharded collection. | | `documentdb_api.unshard_collection(p_shard_key_spec bson)` | Removes the shard key from a sharded collection, returning it to a single unsharded table. | | `documentdb_api.coll_mod(p_database_name text, p_collection_name text, p_spec bson)` | Executes a MongoDB `collMod` command. Changes collection options — `viewOn`, `pipeline`, `validator`, `expireAfterSeconds`, `changeStreamPreAndPostImages` — on an existing collection. | -| `documentdb_api.compact(p_spec bson)` | Compacts a collection's data and indexes (added in v0.104-0). Requires a GUC that is off by default — see the note below. | +| `documentdb_api.compact(p_spec bson)` | Executes a MongoDB `compact` command. `mode` is `standard` (default, a plain `VACUUM`), `full` (`VACUUM FULL`), or `updateStats` (`ANALYZE`). `full` requires a GUC that is off by default — see the note below. | > **Shard keys must be hashed.** Every value in the shard key document has to be the string `"hashed"`; anything else raises `only shard keys that use hashed are supported` (or `Shard key value provided is invalid` for a different string). A first-time shard therefore looks like `SELECT documentdb_api.shard_collection('mydb', 'users', '{ "value": "hashed" }'::documentdb_core.bson, false);`. @@ -82,14 +83,14 @@ Functions for managing collections, views, databases, and sharding. > **Sharding operations rewrite the whole collection.** `shard_collection`, `reshard_collection`, and `unshard_collection` each build a shadow table and re-insert every document, so plan for roughly double the collection's disk footprint for the duration and expect a runtime proportional to collection size. None of them warn about this. -> **`compact` requires `documentdb.enableCompactVacuumFull`, which defaults to `off`.** With the GUC off, `compact` returns `{ "ok": 1, "bytesFreed": 0 }` and reclaims nothing — no error, no warning. Turn the GUC on to actually run the (blocking) `VACUUM FULL`. `compact` also required a separate `documentdb.enableCompact` GUC when it was introduced in v0.104-0; that flag was removed in v0.109-0. +> **`compact` with `mode: "full"` requires `documentdb.enableCompactVacuumFull`, which defaults to `off`.** With the GUC off, a `full` compact returns `{ "ok": 1, "bytesFreed": 0 }` and reclaims nothing — no error, no warning. Turn the GUC on to run the blocking `VACUUM FULL`. The `standard` and `updateStats` modes always run. `bytesFreed` is the measured drop in the collection's on-disk size across the vacuum, so a `standard` compact usually reports `0`: a plain `VACUUM` makes space reusable but rarely shrinks the files. (Until `ALTER EXTENSION documentdb UPDATE` brings the schema to `1.0-0`, `bytesFreed` falls back to the older bloat estimate.) `dryRun: true` returns that estimate as `estimatedBytesFreed` without vacuuming. ## Index Management | Function | Description | | --- | --- | | `documentdb_api_internal.create_indexes_non_concurrently(p_database_name text, p_arg bson, p_skip_check_collection_create boolean DEFAULT false)` | Creates indexes in the foreground, blocking writes for the duration. With the default `p_skip_check_collection_create => false` this raises on any collection whose data table was not created in the current transaction, so a direct call on an existing collection needs `p_skip_check_collection_create => true`. The background path below calls it internally when it creates the collection itself. | -| `documentdb_api.create_indexes_background(p_database_name text, p_index_spec bson, OUT retval bson, OUT ok boolean, OUT requests bson)` | Validates an index spec and **queues** the build, then returns immediately — it does not wait for the index to be built. Present since the initial release; background builds became the working default in v0.104-0, when the drain job started being scheduled automatically. | +| `documentdb_api.create_indexes_background(p_database_name text, p_index_spec bson, OUT retval bson, OUT ok boolean, OUT requests bson)` | Validates an index spec and **queues** the build, then returns immediately — it does not wait for the index to be built. | | `documentdb_api_internal.check_build_index_status(p_arg bson, OUT retval bson, OUT ok boolean, OUT complete boolean)` | Reports on builds queued by `create_indexes_background`. Takes the `requests` document returned by that call. | | `CALL documentdb_api.drop_indexes(p_database_name text, p_arg bson, INOUT retval bson DEFAULT NULL)` | Drops indexes via the wire-protocol `dropIndexes` command. Implemented as a `PROCEDURE`. | @@ -141,9 +142,9 @@ Functions backing diagnostic and administrative wire protocol commands. | `documentdb_api.coll_stats(p_database_name text, p_collection_name text, p_scale float8 DEFAULT 1)` | Returns storage and index statistics for a collection (`collStats`). | | `documentdb_api.db_stats(p_database_name text, p_scale float8 DEFAULT 1, p_freestorage bool DEFAULT false)` | Returns storage statistics for a database (`dbStats`). | | `documentdb_api.validate(database text, validateSpec bson, OUT document bson)` | Validates a collection's indexes (`validate`). | -| `documentdb_api.connection_status(p_spec bson)` | Returns authentication and role information for the current connection (`connectionStatus`, added in v0.105-0). | -| `documentdb_api.kill_op(p_command_spec bson)` | Cancels a running operation by op id (`killOp`, added in v0.109-0). | -| `documentdb_api.current_op_command(p_spec bson, OUT document bson)` | Backs the `currentOp` wire-protocol command (added in v0.102-0). The `$currentOp` aggregation stage uses the internal `documentdb_api_internal.current_op_aggregation(p_spec bson, OUT document bson)` set-returning helper, which has existed since v0.101-0. | +| `documentdb_api.connection_status(p_spec bson)` | Returns authentication and role information for the current connection (`connectionStatus`). | +| `documentdb_api.kill_op(p_command_spec bson)` | Cancels a running operation by op id (`killOp`). | +| `documentdb_api.current_op_command(p_spec bson, OUT document bson)` | Backs the `currentOp` wire-protocol command. The `$currentOp` aggregation stage uses the internal `documentdb_api_internal.current_op_aggregation(p_spec bson, OUT document bson)` set-returning helper. | ## User Management @@ -158,14 +159,14 @@ Functions for creating, updating, and managing database users. Backed by the wir ## Role Management -All four role functions were added in v0.106-0, together with wire-protocol support for `createRole`. Support for the `dropRole` and `rolesInfo` commands followed in v0.108-0. `updateRole` is routed by the gateway to `documentdb_api.update_role`. +Functions for custom roles. Backed by the wire protocol `createRole`, `dropRole`, `rolesInfo`, and `updateRole` commands. -All of them are gated behind `documentdb.enableRoleCrud`, added in v0.108-0 and off by default, so on a stock build `create_role`, `drop_role`, and `roles_info` raise "The CreateRole command is currently unsupported." and its equivalents before doing any work. The wire-protocol commands are additionally required to run against the `admin` database (`documentdb.enableRolesAdminDBCheck`, on by default since v0.109-0); the user management functions above are not. +`create_role`, `drop_role`, and `roles_info` are gated behind `documentdb.enableRoleCrud`, which is off by default, so on a stock build they raise "The CreateRole command is currently unsupported." and its equivalents before doing any work. With it on, `create_role` creates the role, grants its parent roles and collection privileges (`find`, `insert`, `update`, `remove`), and records it in the `documentdb_api_catalog.roles` table. The wire-protocol commands are additionally required to run against the `admin` database (`documentdb.enableRolesAdminDBCheck`, on by default); the user management functions above are not. | Function | Description | | --- | --- | -| `documentdb_api.create_role(p_spec bson)` | Creates a new role. | -| `documentdb_api.drop_role(p_spec bson)` | Drops an existing role. | +| `documentdb_api.create_role(p_spec bson)` | Creates a custom role. | +| `documentdb_api.drop_role(p_spec bson)` | Drops a custom role. Built-in roles raise "Cannot drop built-in role", and a role not recorded in `documentdb_api_catalog.roles` raises "The specified role '...' does not exist." | | `documentdb_api.update_role(p_spec bson)` | Not implemented. The function body is a bare `ereport(ERROR)`, so every call raises "UpdateRole command is not supported in preview." regardless of the spec or of `enableRoleCrud`. | | `documentdb_api.roles_info(p_spec bson)` | Returns information about one or more roles. | diff --git a/postgres-api/index.md b/postgres-api/index.md index 758e488..842cc15 100644 --- a/postgres-api/index.md +++ b/postgres-api/index.md @@ -1,11 +1,11 @@ --- title: Components -description: Learn about pg_documentdb_core, pg_documentdb, and pg_documentdb_gw — the two PostgreSQL extensions and the gateway that enable BSON support, document operations, and MongoDB wire protocol compatibility in Postgres. +description: Learn about pg_documentdb_core, pg_documentdb, pg_documentdb_extended_rum, and pg_documentdb_gw — the three PostgreSQL extensions and the gateway that enable BSON support, document operations, indexing, and MongoDB wire protocol compatibility in Postgres. --- # Components -The DocumentDB implementation consists of two PostgreSQL extensions and a gateway that work together to provide MongoDB-compatible document database functionality on top of PostgreSQL. +The DocumentDB implementation consists of three PostgreSQL extensions and a gateway that work together to provide MongoDB-compatible document database functionality on top of PostgreSQL. ## pg_documentdb_core @@ -39,6 +39,19 @@ The DocumentDB implementation consists of two PostgreSQL extensions and a gatewa To use `pg_documentdb`, you need to have `pg_documentdb_core` installed and configured in your PostgreSQL environment. Once set up, you can leverage the APIs provided by `pg_documentdb` to perform document operations from any PostgreSQL client. For the full list of callable functions, see [Functions](https://documentdb.io/docs/postgres-api/functions/). +## pg_documentdb_extended_rum + +`pg_documentdb_extended_rum` (SQL extension name `documentdb_extended_rum`) is DocumentDB's fork of the PostgreSQL RUM index access method, which backs DocumentDB's document indexes. It keeps RUM's on-disk format and extends the query path for document workloads. + +It is required in 1.0: `documentdb.rum_library_load_option` defaults to `require_documentdb_extended_rum`, so `pg_documentdb` loads its index handler from the extended RUM library. The library loads only from `shared_preload_libraries`, and `CREATE EXTENSION documentdb CASCADE` does not create the extension, so a manually configured server needs both steps before indexes are built: + +```sql +-- postgresql.conf: add pg_documentdb_extended_rum to shared_preload_libraries, then restart +CREATE EXTENSION documentdb_extended_rum; +``` + +The package setup wizard and the `documentdb-local` image do this for you. See [Configuration](https://documentdb.io/docs/postgres-api/configuration/) for the load option. + ## pg_documentdb_gw `pg_documentdb_gw` is the gateway protocol translation layer that converts the user's MongoDB wire protocol commands into PostgreSQL queries against the `pg_documentdb` API. It is what allows MongoDB-compatible drivers and tools (`mongosh`, PyMongo, the official MongoDB Node.js driver, the VS Code extension, and others) to talk to a DocumentDB instance unmodified. @@ -53,4 +66,4 @@ To use `pg_documentdb`, you need to have `pg_documentdb_core` installed and conf - **Cursor and Session Management:** Translates `getMore`, `killCursors`, `killSessions`, and `killOp` commands to the corresponding backend operations. -- **Deployment Options:** Can be run as a standalone process (the default in the `documentdb-local` container) or, since v0.108-0, as a PostgreSQL background worker via the `pg_documentdb_gw_host` extension. +- **Deployment Options:** Can be run as a standalone process (the default in the `documentdb-local` container) or as a PostgreSQL background worker via the `pg_documentdb_gw_host` extension. From d38503e8c8f260d373aa0b520a687776e72fec9c Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Fri, 16 Oct 2026 13:46:53 -0400 Subject: [PATCH 06/13] Correct API reference pages that contradict the 1.0 engine Signed-off-by: Guanzhou Song --- .../commands/aggregation/aggregate.md | 2 + api-reference/commands/aggregation/count.md | 2 + .../commands/aggregation/distinct.md | 2 +- .../commands/query-and-write/delete.md | 2 +- .../commands/query-and-write/find.md | 2 + .../commands/query-and-write/findandmodify.md | 2 + .../commands/query-and-write/update.md | 2 + .../operators/aggregation/$changestream.md | 150 ++---------------- .../operators/aggregation/$collstats.md | 4 +- .../operators/array-update/$positional-all.md | 6 +- .../operators/evaluation-query/$jsonschema.md | 35 ++-- 11 files changed, 43 insertions(+), 166 deletions(-) diff --git a/api-reference/commands/aggregation/aggregate.md b/api-reference/commands/aggregation/aggregate.md index 0856ead..6f5900e 100644 --- a/api-reference/commands/aggregation/aggregate.md +++ b/api-reference/commands/aggregation/aggregate.md @@ -18,6 +18,8 @@ db.collection.aggregate(pipeline, options) - **pipeline**: An array of aggregation stages that process and transform the data. - **options**: Optional. Specifies more options for the aggregation, such as `explain`, `allowDiskUse`, and `cursor`. +Collation is off by default: an `aggregate` that sets `collation` fails with `collation is not supported in the aggregate command yet.` unless the server enables `documentdb_core.enableCollation`. + ## Examples ### Example 1: Calculate total sales by category diff --git a/api-reference/commands/aggregation/count.md b/api-reference/commands/aggregation/count.md index 2c11dc9..a8a6dbb 100644 --- a/api-reference/commands/aggregation/count.md +++ b/api-reference/commands/aggregation/count.md @@ -20,6 +20,8 @@ db.collection.count(query, options) - `query`: A document specifying the selection criteria using query operators. - `options`: Optional. A document specifying options, such as `limit` and `skip`. +Collation is off by default: a `count` that sets `collation` fails with `collation is not supported in the count command yet.` unless the server enables `documentdb_core.enableCollation`. + ## Examples Here are some examples to demonstrate the usage of the `count` command: diff --git a/api-reference/commands/aggregation/distinct.md b/api-reference/commands/aggregation/distinct.md index ea417e0..770e983 100644 --- a/api-reference/commands/aggregation/distinct.md +++ b/api-reference/commands/aggregation/distinct.md @@ -19,7 +19,7 @@ db.collection.distinct(field, query, options) - `field`: The field that receives the returned distinct values. - `query`: Optional. A query that specifies the documents from which to retrieve the distinct values. -- `options`: Optional. Other options for the command. +- `options`: Optional. Other options for the command. `collation` isn't supported and fails with `collation is not supported in the distinct command yet.` ## Examples diff --git a/api-reference/commands/query-and-write/delete.md b/api-reference/commands/query-and-write/delete.md index 936d13f..0330f05 100644 --- a/api-reference/commands/query-and-write/delete.md +++ b/api-reference/commands/query-and-write/delete.md @@ -30,7 +30,7 @@ db.collection.deleteMany( | Parameter | Description | | --- | --- | | **<`filter`>** | A document that specifies the criteria for deletion. Only the documents that match the filter are deleted| -| **`options`** | Optional. A document that specifies options for the delete operation. Common options include writeConcern and collation| +| **`options`** | Optional. A document that specifies options for the delete operation. Common options include writeConcern and collation. Collation is off by default: a delete that sets it fails with `BSON field 'delete.deletes.collation' is not yet supported` unless the server enables `documentdb_core.enableCollation`.| ## Example(s) diff --git a/api-reference/commands/query-and-write/find.md b/api-reference/commands/query-and-write/find.md index f8de849..ac2922f 100644 --- a/api-reference/commands/query-and-write/find.md +++ b/api-reference/commands/query-and-write/find.md @@ -25,6 +25,8 @@ db.collection.find(query, projection, options) | **`projection`** | (Optional) A document that specifies the fields in the matching documents to be returned in the result set| | **`options`** | (Optional) A document that specifies options for query behavior and results| +Collation is off by default: a `find` that sets `collation` fails with `collation is not supported in the find command yet.` unless the server enables `documentdb_core.enableCollation`. + ## Example(s) Consider this sample document from the stores collection in the StoreData database. diff --git a/api-reference/commands/query-and-write/findandmodify.md b/api-reference/commands/query-and-write/findandmodify.md index 286c847..829f3c4 100644 --- a/api-reference/commands/query-and-write/findandmodify.md +++ b/api-reference/commands/query-and-write/findandmodify.md @@ -35,6 +35,8 @@ db.collection.findAndModify({ - **fields**: Limits the fields to return for the matching document. - **upsert**: If `true`, creates a new document if no document matches the query. +`collation` isn't supported and fails with `findAndModify.collation is not implemented yet`. + ## Examples ### Example 1: Update total sales diff --git a/api-reference/commands/query-and-write/update.md b/api-reference/commands/query-and-write/update.md index 7552267..cc22441 100644 --- a/api-reference/commands/query-and-write/update.md +++ b/api-reference/commands/query-and-write/update.md @@ -9,6 +9,8 @@ category: query-and-write The `update` command is used to modify existing documents within a collection. The `update` command can be used to update one or multiple documents based on filtering criteria. Values of fields can be changed, new fields and values can be added and existing fields can be removed. +The `collation` option isn't supported and fails with `BSON field 'update.updates.collation' is not yet supported`. + ## Example(s) Consider this sample document from the stores collection in the StoreData database. diff --git a/api-reference/operators/aggregation/$changestream.md b/api-reference/operators/aggregation/$changestream.md index ba10015..6888e7d 100644 --- a/api-reference/operators/aggregation/$changestream.md +++ b/api-reference/operators/aggregation/$changestream.md @@ -1,13 +1,16 @@ --- title: $changeStream -description: The $changeStream stage opens a change stream cursor to track data changes in real-time. +description: The $changeStream stage opens a change stream cursor in MongoDB. DocumentDB does not support it. type: operators category: aggregation --- # $changeStream -The `$changeStream` aggregation stage opens a change stream cursor that tracks data changes in real-time. This stage enables applications to react to insert, update, delete, and other operations as they occur in the collection. +> [!IMPORTANT] +> DocumentDB does not support `$changeStream`. Any pipeline that uses it, including `db.collection.watch()`, fails with `Stage $changeStream is not supported yet in native pipeline` (`CommandNotSupported`, code 115). + +In MongoDB, the `$changeStream` aggregation stage opens a cursor that reports inserts, updates, deletes, and other changes as they happen. The syntax below is listed for reference only. ## Syntax @@ -37,123 +40,9 @@ The `$changeStream` aggregation stage opens a change stream cursor that tracks d | **`startAtOperationTime`** | Optional. timestamp for starting change stream from a specific time. | | **`showExpandedEvents`** | Optional. Boolean. Include another change stream events. Default is false. | -## Examples - -Consider this sample document from the stores collection. - -```json -{ - "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4", - "name": "First Up Consultants | Beverage Shop - Satterfieldmouth", - "location": { - "lat": -89.2384, - "lon": -46.4012 - }, - "staff": { - "totalStaff": { - "fullTime": 8, - "partTime": 20 - } - }, - "sales": { - "totalSales": 75670, - "salesByCategory": [ - { - "categoryName": "Wine Accessories", - "totalSales": 34440 - }, - { - "categoryName": "Bitters", - "totalSales": 39496 - }, - { - "categoryName": "Rum", - "totalSales": 1734 - } - ] - }, - "promotionEvents": [ - { - "eventName": "Unbeatable Bargain Bash", - "promotionalDates": { - "startDate": { - "Year": 2024, - "Month": 6, - "Day": 23 - }, - "endDate": { - "Year": 2024, - "Month": 7, - "Day": 2 - } - }, - "discounts": [ - { - "categoryName": "Whiskey", - "discountPercentage": 7 - }, - { - "categoryName": "Bitters", - "discountPercentage": 15 - }, - { - "categoryName": "Brandy", - "discountPercentage": 8 - }, - { - "categoryName": "Sports Drinks", - "discountPercentage": 22 - }, - { - "categoryName": "Vodka", - "discountPercentage": 19 - } - ] - }, - { - "eventName": "Steal of a Deal Days", - "promotionalDates": { - "startDate": { - "Year": 2024, - "Month": 9, - "Day": 21 - }, - "endDate": { - "Year": 2024, - "Month": 9, - "Day": 29 - } - }, - "discounts": [ - { - "categoryName": "Organic Wine", - "discountPercentage": 19 - }, - { - "categoryName": "White Wine", - "discountPercentage": 20 - }, - { - "categoryName": "Sparkling Wine", - "discountPercentage": 19 - }, - { - "categoryName": "Whiskey", - "discountPercentage": 17 - }, - { - "categoryName": "Vodka", - "discountPercentage": 23 - } - ] - } - ] -} -``` - -### Example 1: Monitor all changes in stores collection +## Example -This operation sets up a change stream to monitor all changes in the stores collection. +This pipeline is rejected: ```javascript db.stores.aggregate([ @@ -165,27 +54,6 @@ db.stores.aggregate([ ]) ``` -When a store document is updated, the change stream returns the change event with the full document. - -```json -{ - "_id": { "_data": "AeARBpQ/AAAA" }, - "operationType": "update", - "fullDocument": { - "_id": "905d1939-e03a-413e-a9c4-221f74055aac", - "name": "Trey Research | Home Office Depot - Lake Freeda", - "sales": { - "revenue": 42500 - }, - "company": "Trey Research", - "lastUpdated": "ISODate('2024-06-16T10:30:00.000Z')" - }, - "ns": { - "db": "StoreData", - "coll": "stores" - }, - "documentKey": { - "_id": "905d1939-e03a-413e-a9c4-221f74055aac" - } -} +``` +Stage $changeStream is not supported yet in native pipeline ``` diff --git a/api-reference/operators/aggregation/$collstats.md b/api-reference/operators/aggregation/$collstats.md index 8920caa..e7d9775 100644 --- a/api-reference/operators/aggregation/$collstats.md +++ b/api-reference/operators/aggregation/$collstats.md @@ -14,7 +14,6 @@ The $collStats stage in the aggregation pipeline is used to return statistics ab ```javascript { $collStats: { - latencyStats: { histograms: }, storageStats: { scale: }, count: {} } @@ -25,10 +24,11 @@ The $collStats stage in the aggregation pipeline is used to return statistics ab | Parameter | Description | | --- | --- | -| **`latencyStats`** | Optional. Specifies whether to include latency statistics. The `histograms` field is a boolean that indicates whether to include histograms of latency data. | | **`storageStats`** | Optional. Specifies whether to include storage statistics. The `scale` field is a number that indicates the scale factor for the storage statistics. | | **`count`** | Optional. Includes the count of documents in the collection. | +`latencyStats` and `queryExecStats` aren't supported; either one fails with `collStats with