Skip to content

docs: explain adaptive commits and durable ack tiers - #559

Merged
javier merged 16 commits into
mainfrom
nw_adaptive_commit_docs
Nov 10, 2026
Merged

docs: explain adaptive commits and durable ack tiers#559
javier merged 16 commits into
mainfrom
nw_adaptive_commit_docs

Conversation

@nwoolmer

@nwoolmer nwoolmer commented Sep 18, 2026 •
edited by eugenels
Loading

Copy link
Copy Markdown
Contributor

Summary

Documents adaptive commit mode and the tiered QWP durable acknowledgements, as merged in questdb/questdb#7411,
questdb/questdb-enterprise#1147, questdb/java-questdb-client#98 and questdb/c-questdb-client#208.

  • New page, Concepts > Core Concepts > Durability and commit modes (/docs/concepts/durability/): what each
    commit mode survives, how adaptive mode works (WAL and sequencer record flushed on commit, save points,
    recovery), enabling it, the group-commit window, durable acknowledgements and how a client waits for them,
    guarantees and limits, costs, changing the mode and downgrading, monitoring, troubleshooting, and QuestDB
    Enterprise behaviour.
  • Cairo settings: the adaptive value of cairo.commit.mode and the six adaptive keys, one short entry each, in
    alphabetical order, linking to the new page.
  • Durable acknowledgements: the local, replicated and local,replicated tiers on the connect string, Java,
    C/C++ and Rust pages, the store-and-forward pages (including the decision flowchart) and the QWP ingress
    protocol (tier negotiation, STATUS_LOCAL_DURABLE_ACK, the seqTxn offset for tables re-created during a
    connection). The Python page is unchanged: the Python client bundles C client 7.2.1, which accepts only on.
  • wal_tables(): the four durability columns. Prometheus: three new metrics, and the corrected names of
    questdb_wal_apply_seq_txn and questdb_wal_apply_writer_txn.
  • Behaviour changes that ship with the release: a conversion to non-WAL applies the WAL first and is refused while
    it cannot (SET TYPE); RESUME WAL in adaptive mode; a QuestDB Enterprise primary refuses to start when its log
    of a table ends before the object store (disaster recovery). The upgrade page gets an "Upgrading to 4.2.0"
    section and the downgrade rule, the monitoring page what to alert on, and the Kubernetes operator page limits
    its retry promise to replicated acknowledgements.
  • The storage engine, WAL, delivery semantics and store-and-forward pages no longer imply that an acknowledged
    commit survives a power loss in every commit mode.
  • Changelog entry for November 2026.

Since the first draft, the pages follow the merged code: the server refuses local outside adaptive mode, a
QuestDB Enterprise primary in adaptive mode grants local,replicated, cairo.adaptive.recovery.roll.forward.enabled
does not exist, and the browser subprotocol paragraph is gone (a separate feature).

Renamed headings, with no links to the old anchors in the docs (outside links land at the top of the page):

  • Delivery semantics: "Related Enterprise features" is now "Related features", because local does not need
    Enterprise.
  • Store-and-forward concepts: "request_durable_ack=on — WAL-durable trim" is now "Durable-ack trim".

Dependencies

Describes QuestDB 10.2.0 and QuestDB Enterprise 4.2.0, the Java client after 1.3.11, and the C, C++ and Rust clients
after 7.2.1. Merge with those releases; replace the client versions with their release numbers.

@github-actions

github-actions Bot commented Sep 18, 2026 •
edited
Loading

Copy link
Copy Markdown

🚀 Build success!

Latest successful preview: https://preview-559--questdb-documentation.netlify.app/docs/

Commit SHA: 4fc9fee

📦 Build generates a preview & updates the link on each commit.

@eugenels
Merge remote-tracking branch 'origin/main' into nw_adaptive_commit_docs
4320385 
# Conflicts:
#	documentation/connect/clients/c-and-cpp.md
#	documentation/connect/clients/connect-string.md
#	documentation/connect/clients/java.md
@eugenels
docs(metrics): correct the WAL apply transaction metric names
3fccfd0 
The server exports questdb_wal_apply_seq_txn and questdb_wal_apply_writer_txn
(gauges since questdb#6017, counters with a _total suffix before). The page
named them without the apply_ part.
@eugenels
docs: add the durability and commit modes page, rewrite the commit se…
197b371 
…ttings

The adaptive commit mode merged in questdb#7411 and questdb-enterprise#1147.
The concept page says what each commit mode survives, and how adaptive mode
works, from the merged code: save points, the group-commit window, durable
acknowledgements, guarantees and limits, costs, mode changes, downgrade,
monitoring, troubleshooting and Enterprise behaviour.

The Cairo settings page keeps one short entry per key, in alphabetical order,
and links to the concept page. It drops cairo.adaptive.recovery.roll.forward.enabled,
which the merged server does not have. The storage engine, WAL, delivery
semantics and upgrade pages no longer imply that a WAL commit survives a power
loss in every mode.
@eugenels
docs: document the adaptive commit columns of wal_tables() and metrics
f6fd56d 
wal_tables() gained durableEpochSeqTxn, recoveryIncarnation,
localDurableSeqTxn and lastEpochTs; the server exports three new WAL metrics.
@eugenels
docs: describe the durable-ack tiers as the merged server and clients…
446576c 
… grant them

The first draft said a server grants the local tier outside adaptive mode
and that no server grants local,replicated. The merged server refuses local
unless it runs in adaptive mode, and a QuestDB Enterprise primary in adaptive
mode grants local,replicated. QuestDB Enterprise 4.1.0 and earlier accept only
on, so the pages say to keep on for them.

The tier names need Java client releases after 1.3.11 and C, C++ and Rust
client releases after 7.2.1 (java-questdb-client#98, c-questdb-client#208).
The Python client still bundles 7.2.1, so its page goes back to main's text.
The protocol page drops the browser subprotocol paragraph, which described
a separate feature inaccurately, documents the per-connection seqTxn offset
for re-created tables, and points the reference implementation at 28c8483.
@eugenels
docs: document behaviour changes that ship with adaptive commit
613057e 
A conversion to non-WAL now applies the WAL first, in every commit mode, and
is refused while it cannot. In adaptive mode RESUME WAL can take a save point
and answer table busy. A QuestDB Enterprise primary whose log of a table ends
before the object store refuses to start; the disaster recovery page gives the
two ways out.
@eugenels
docs: add the November 2026 changelog entry for adaptive commit
f17fb9d
@eugenels
docs: address the review of the adaptive commit pages
356b0c7 
- Name the release: QuestDB 10.2.0 and QuestDB Enterprise 4.2.0.
- The durability page gets a server.conf example for a group-commit window
  of 0 and a connect string example for the local tier.
- The tier tables on the durability and connect string pages now match.
- Plain wording: "behaves as in nosync" instead of "nosync grade",
  "half-written" instead of "torn", no "iff" or "re-OKs".
- The store-and-forward comparison table gets a row for the local tier.
- The sidebar label names commit modes too.
@eugenels
docs: address the level 2 review of the adaptive commit pages
5b2bbb8 
- "On the disk" now means the WAL files and the sequencer record are flushed;
  the guarantee, the local tier, localDurableSeqTxn and its gauge said "its WAL
  is on the disk", which every acknowledged commit already has.
- The group-commit window is no longer stated as a hard bound, the sync row
  points to its known gaps, and the failed-flush rule names the flushes that
  stop QuestDB in every mode.
- The monitoring query skips tables not written since the start; the recovery
  counter and the negative save point interval are described as the code does.
- The durability page says how code waits for a local confirmation, that
  replayed batches can duplicate rows, how to see the commit mode, when the
  replay is done, and where the table directory is; it gets a See also list.
- The connect string page keeps a short list of tiers and links to the one
  table on the durability page; the protocol, client and store-and-forward
  pages use the same wording, and the flowchart gets the local tier.
- The upgrade page states the downgrade rule and what to check for Enterprise
  4.2.0; the monitoring page lists what to alert on; the Kubernetes operator
  page limits its retry promise to replicated acknowledgements.
javier
javier reviewed Nov 5, 2026
View reviewed changes
Comment thread documentation/query/sql/alter-table-set-type.md Resolved
Comment thread documentation/concepts/durability.md Resolved
Comment thread documentation/concepts/durability.md Resolved
@eugenels
docs(sql): say what replaces converting a lagging table to non-WAL an…
81606b4 
…d back

Since 10.2.0 the conversion to non-WAL applies the whole WAL backlog while
QuestDB starts, or refuses a suspended table, so converting to non-WAL and
back no longer drops a backlog, and a large backlog delays the start.
REBASE WAL is the way to drop the transactions not yet applied while keeping
the applied rows. Raised in review by javier.
@eugenels
docs: say that QWP writes only to WAL tables, whatever the durable-ac…
5eb6f2b 
…k setting

The sentence sat inside the durable-ack paragraph and read like a rule of
durable acknowledgements. QWP refuses a non-WAL table in every commit mode and
with or without durable acks (QwpTudCache: "cannot insert into non-WAL
table", a SCHEMA_MISMATCH response). The protocol page named non-WAL tables
as a case of an OK with no tables, which QWP never sends. Raised in review by
javier.
@eugenels
docs: turn the durability page's "Other messages" table into a list
ce1f915 
The table put long log messages in a narrow first column, which made it hard
to read. Each message now has a short title, the message in a wrapped block,
and what to do, like the start refusals above it. Raised in review by javier.
@eugenels
Merge remote-tracking branch 'origin/main' into nw_adaptive_commit_docs
4fc9fee 
# Conflicts:
#	documentation/changelog.mdx
javier
javier previously approved these changes Nov 6, 2026
View reviewed changes
@javier
docs(durability): clarify what adaptive mode changes, recommend durab…
411785f 
…le acks

Says adaptive mode changes what a commit survives, not when commits happen, and recommends pairing it with local or local,replicated durable acks plus deduplication for QWP clients.
javier
javier previously approved these changes Nov 10, 2026
View reviewed changes
@javier
javier merged commit 7adff33 into main Nov 10, 2026
1 of 3 checks passed
@javier
javier deleted the nw_adaptive_commit_docs branch November 10, 2026 10:49
@javier javier mentioned this pull request Nov 10, 2026
Merged
javier added a commit that referenced this pull request Nov 10, 2026
@javier
docs(changelog): add 10.2.0 release and passthrough materialized views (
5e0de86 
#627)

## Summary

- Adds the 10.2.0 release to November 2026
- Adds passthrough materialized views, which shipped with #468 but had
no entry
- Adds the RESUME WAL behavior in adaptive commit mode from #559
- Shortens the CREATE MATERIALIZED VIEW breaking-change entry to its
summary
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@eugenels eugenels eugenels left review comments
@javier javier javier left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@nwoolmer @javier @eugenels