Skip to content

v1.2-0 (November 12, 2026)

Latest
Latest

Choose a tag to compare

View all tags
@guanzhousongmicrosoft guanzhousongmicrosoft released this 12 Nov 19:05
· 93 commits to main since this release
v1.2-0
965b6e7

DocumentDB 1.2 follows 1.0. There was no 1.1 release; its changes are part of 1.2.

Get started

Install script

On a clean Ubuntu 24.04 or RHEL 9-compatible host (amd64 or arm64), the installer sets up the newest DocumentDB release, currently 1.2.0, on PostgreSQL 18:

curl -fsSLo documentdb-install.sh https://github.com/documentdb/documentdb/releases/download/v1.2-0/install.sh &&
sudo sh documentdb-install.sh

To choose a release:

Command Installs Later apt upgrade / dnf upgrade
sudo sh documentdb-install.sh The newest release, from the latest package channel Follows each new release
sudo sh documentdb-install.sh --stable The stable channel, which can stay on the previous release for a while (1.0.0 for now) Follows stable
sudo sh documentdb-install.sh --version 1.0.0 Exactly that release (1.0.0 or later), from its GitHub release files None: no DocumentDB repository is configured

install.sh was replaced after publication to add these options, and SHA256SUMS lists the new file.

Packages

Packages 1.2.0 (SQL extension 1.2-0) for PostgreSQL 17/18 on Ubuntu 24.04 and RHEL 9-compatible systems, amd64 and arm64. Download and verify this release's files:

gh release download v1.2-0 -R documentdb/documentdb -D documentdb-1.2 &&
  (cd documentdb-1.2 && sha256sum -c SHA256SUMS)

See the package guide.

Containers

Images for PostgreSQL 15-18 at ghcr.io/documentdb/documentdb/documentdb-local, tagged pg15-1.2.0 through pg18-1.2.0; latest and 1.2 are pg17-1.2.0.

docker run -dt -p 10260:10260 --name documentdb \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.2.0 \
  --username <YOUR_USERNAME> --password <YOUR_PASSWORD>

Connect with mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true. The image no longer starts without a password. It sends usage telemetry by default; see PRIVACY.md to turn it off.

Upgrading from 1.0

Back up the data directory or volume first. Going back to 1.0 on updated data is not supported: 1.0 starts, then fails on some queries.

  • Image: start the 1.2 image for the same PostgreSQL major on the 1.0 data volume, and pass a password (--password or -e PASSWORD); existing users keep the password they had. It updates the extensions itself and logs Updating the DocumentDB extensions on this data volume.
  • Packages: install the 1.2 packages. For a PostgreSQL instance that documentdb-setup created, run sudo documentdb-setup --pg-version <major> --yes, adding any --data-dir or --pg-port the install was set up with. It restarts PostgreSQL once and updates the extensions. For an adopted instance, run sudo documentdb-setup --target-postgres-instance <major>/<cluster> --yes, restart PostgreSQL as it tells you, then run the command it prints.

See Upgrading in the package guide.

Collation is off by default

The collation entries in the list below (findAndModify command collation, distinct, per-update collation, explicit simple) need documentdb_core.enableCollation = on. Without it these commands return code 115, including {locale: "simple"} (#823).

ALTER SYSTEM SET documentdb_core.enableCollation = on;
SELECT pg_reload_conf();

Collated indexes also need documentdb.enableCollationWithNonUniqueOrderedIndexes. Collated unique indexes need that plus documentdb.enable_collated_unique_indexes and documentdb.enable_composite_unique_optional_key.

For more information and detailed instructions please consult this gist

Changes since 1.0

  • Refuse to start the documentdb-local image without a password, also on an existing data volume. Set PASSWORD or pass --password. DOCUMENTDB_ALLOW_DEFAULT_PASSWORD=true keeps the public default password for local evaluation, with a warning, and --create-user false starts without one when no data is loaded. [Breaking/Security]
  • Reject TLS_MODE in the documentdb-local image when it is set but empty, instead of treating it as allowTLS. TLS_MODE, LOG_LEVEL and DOCUMENTDB_TOAST_COMPRESSION also reject a comma-separated list; TLS_MODE=allowTLS,requireTLS used to start without enforcing TLS. [Breaking/Security]
  • Keep the documentdb-local --password value out of the container's process list. [Bugfix/Security]
  • Update the DocumentDB extensions when the documentdb-local image starts on a data volume from an older release, before the gateway starts. A failed update is rolled back and stops the container; a volume from a newer release is left as is, with a warning. See packaging/README.md. [Feature]
  • Restart the package-owned PostgreSQL in a documentdb-setup re-run when it still runs the DocumentDB libraries a package upgrade replaced, before updating the extensions. For an adopted instance, setup prints the restart and re-run commands and stops. See packaging/README.md. [Bugfix]
  • Allow a documentdb-setup re-run of an existing install without --admin-user: it asks for no password and keeps every admin user and password. Name the install with --pg-version N (plus a non-default --data-dir) or --target-postgres-instance N/C. [Feature]
  • Make the documentdb-local --log-level (LOG_LEVEL) setting set the gateway's log level; it had no effect. quiet still logs errors, and DOCUMENTDB_LOG_LEVEL or RUST_LOG, when set, take precedence. [Bugfix]
  • Stop PostgreSQL cleanly when the documentdb-local image exits after a failed start, for example when the admin user cannot be created, so the next start needs no crash recovery. [Bugfix]
  • Count the documentdb-local post-start readiness wait against DOCUMENTDB_PG_READY_TIMEOUT in wall-clock time, so slow pg_isready probes no longer stretch it past the limit. [Bugfix]
  • Correct the documentdb-local --enable-telemetry help and documentdb-local/PRIVACY.md: the flag has no effect in this release. The gateway's operational metrics are set by TelemetryOptions in its configuration file and ship turned off. [Bugfix]
  • Fix the PowerShell block of the documentdb-local compose example on Windows PowerShell 5.1, where it started the stack with a predictable password, and make it stop at the first error. [Bugfix/Security]
  • Declare port 10260, the gateway's default, with EXPOSE in the documentdb-local image. [Feature]
  • Use PostgreSQL date_bin for $dateTrunc with unit: "day", preserving exact calendar days, reference-aligned bins, and timezone boundaries. Reject strides and results outside PostgreSQL's supported range. Controlled by the default-on documentdb.enable_date_trunc_day_with_pg_bin setting; turn it off to restore legacy interval-based behavior. [Bugfix]
  • Reject dropUser and updateUser user names of 64 bytes or more before PostgreSQL truncates them, so an overlong name can no longer drop or modify an existing user whose name is its 63-byte prefix (#734). [Bugfix]
  • Skip parallel scan plans for dynamic cursor queries without collection planner statistics by default, controlled by documentdb.enable_skip_parallel_plans_without_stats. [Bugfix]
  • Reject dynamic streaming paths early for $unionWith and SQL set operations so persistent cursors retain selective scan alternatives. [Bugfix]
  • Compress eligible remote single-document inserts on the shard before storing them. [Bugfix]
  • Apply the configured inline document compression threshold to multi-document updates. [Bugfix]
  • Enforce null/missing conflicts in descending unique indexes by starting conflict probes at the correct bound, including compound keys and collated indexes. Controlled by the default-on documentdb.enable_unique_null_missing_semantics setting. [Bugfix]
  • Estimate direct equality, range, and regular-expression children and pushed index bounds for $elemMatch from per-path statistics instead of using a fixed fallback. Controlled by the default-on documentdb.enable_elem_match_selectivity_from_stats setting, with compound-index selection regression coverage. [Bugfix/Perf] (#405)
  • Reject collation-aware values that require truncation on both writes and indexed reads by default through the documentdb.fail_on_collated_index_term_truncation feature flag. [Bugfix] (work item 5643482)
  • Estimate the inner side of a $lookup join from collected statistics instead of a fixed fallback selectivity, so an index on the foreignField is costed correctly. Controlled by the default-on documentdb.enable_lookup_join_selectivity_from_stats setting. [Perf]
  • Support timestamptz values in bson_build_document, writing them as BSON dates with millisecond precision. [Feature]
  • Allow scalar leading-key distinct pushdown on multikey reduced-correlated indexes when documentdb.enable_distinct_multi_key_sort_pushdown is enabled. [Perf]
  • Support explicit command collation for findAndModify. [Feature]
  • Allow _id support-function predicates to prove eligible partial RUM index filters when documentdb.enable_support_function_id_pushdown is enabled, with the default-on documentdb.enable_support_object_id_function_pfe_pushdown setting independently controlling partial-index implication. [Bugfix/Perf]
  • Remove gateway SQLCommenter injection and its build feature while preserving gateway spans and incoming trace context. [Refactor]
  • Add a default-on documentdb.enable_full_scan_cost_and_selectivity setting to control full-scan planner estimates and synthetic execution cost. [Perf]
  • Allow collMod to rename an index when its key pattern and current name both match the catalog entry. [Feature]
  • Preserve admin.system.users system-catalog permission checks while filtering memberships to catalog-backed custom roles. [Bugfix]
  • Return custom-role metadata from admin.system.roles in rolesInfo and from admin.system.users in usersInfo and connectionStatus. Admin- and root-role users can list or inspect every catalog role, while other users can list or inspect roles they inherit directly or transitively; built-in roles remain excluded. [Bugfix]
  • Extend subquery pushdown of $match on computed fields to queries using persisted cursors (previously only applied when dynamic cursors were enabled). Guarded by enable_subquery_pushdown_for_match_on_persisted_cursors feature flag, disabled by default while pending stabilization. [Perf]
  • Prevent backend crashes and incorrect results when a correlated $lookup rescans a $densify stage using full bounds, including scans stopped early by a downstream $limit. Release copied partition keys, projection trees, and date intervals between scans to reduce peak query memory. [Bugfix]
  • Allow unfiltered $sample queries to be pushed down to a Sample Scan when a dynamic cursor marker is present. Guarded by the enable_sample_scan_pushdown_for_dynamic_cursor feature flag. [Bugfix/Perf]
  • Treat an explicit simple collation as no collation, emitting no collation tag so it uses binary comparison on every query and index path. [Bugfix]
  • Preserve sorting and grouping results when a null equality lies between compound-index sort keys. [Bugfix]
  • Prevent low-fill-factor rightmost RUM leaf splits from overflowing the right page when large index terms leave too little space under the requested split target. [Bugfix]
  • Retire the enableSkipDottedFieldIndexTerms feature flag and always skip index terms for non-array fields with dotted names. [Refactor]
  • Reclassify isNativeAuthEnabled as a long-term system configuration without changing its behavior or runtime name. [Refactor]
  • Retire the enable_ordered_operator_scans feature flag and retain ordered operator scans unconditionally. [Refactor]
  • Enable order-by pushdown for $group over multi-key composite ordered indexes by default when per-path metadata proves the grouped and ordered columns are scalar. [Perf]
  • Generate single bound for $nin and use an HTAB for index recheck for ordered indexes. [Perf]
  • Enable the field-pruning $project injection before $unwind (the enableProjectPushUpBeforeUnwindWithGroup feature flag) by default now that it has stabilized. [Perf]
  • Support collation with distinct command [Feature]
  • Apply per-update collation when selecting documents and evaluating comparison-sensitive update effects, including single-document, multi-document, and upsert paths. [Feature]
  • Reclaim orphaned empty RUM posting-tree leaves during vacuum cleanup when bulk deletion is skipped because the heap has no new dead tuples, and keep planner statistics consistent with entry-page and posting-page pruning. Guarded by the default-off documentdb_rum.enable_vacuum_cleanup_posting_tree_pruning setting. [Bugfix/Perf]
  • Reduce lock-manager pressure for dynamic cursor queries on heavily indexed collections by releasing planner-acquired AccessShareLocks for indexes not referenced by the final streamable plan immediately after planning. Guarded by the default-off documentdb.enable_dynamic_cursor_early_index_lock_release setting. [Perf]
Assets 27
Loading