docs(databases): describe HA replication honestly as async-only

[abnegate]

Problem (DAT-1942)

nyc3 2026-07-21 Drill C proved syncMode is stored-but-inert: sync/quorum were accepted and echoed while every engine replicated async (commits under syncMode=sync with the replica scaled down completed in milliseconds; no synchronous_standby_names, no semi-sync plugin, no quorum handling). The HA docs page promised exactly that missing durability:

• The sync-modes table: sync = "at least one replica acknowledges", quorum = "a majority acknowledge" — plus "a safe default for production is sync".
• The engine table: MySQL/MariaDB "Semi-synchronous binlog replication".
• Read-your-writes: "Use a stronger sync mode … any reader sees the write as soon as COMMIT returns".
• Every code sample requested 'sync' — which the API now rejects (appwrite-labs/edge#890, appwrite-labs/cloud#4894).

Fix (minimal, claims only)

• Sync-modes section now states replication is asynchronous, async is the only accepted value (sync/quorum rejected until implemented), with the real crash-loss disclosure semantics.
• Engine table rows say asynchronous.
• Read-your-writes third bullet now gives the guidance that is actually wired: reads inside a transaction or SELECT … FOR UPDATE pin to the primary via the pooler (verified in the pooler routing rules, already documented on the pooler page — that page needed no changes).
• Code samples request async; dropped the "sync mode change online" limits row; frontmatter description no longer advertises synchronous/semi-synchronous.

Base is feat-dedicated-db (the branch carrying these docs, PR #3018), matching #3042's stacking.

Refs DAT-1942.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[appwrite]

Appwrite Website

Project ID: 69d7efb00023389e8d27

Sites (1)

Site	Status	Logs	Preview	QR
website 69d7f2670014e24571ca	Ready	View Logs	Preview URL

Website (appwrite/website)

Project ID: 684969cb000a2f6c0a02

Sites (1)

Site	Status	Logs	Preview	QR
website 68496a17000f03d62013	Processing	View Logs	Preview URL

---

Tip

Every Git commit and branch gets its own deployment URL automatically

[greptile-apps]

Greptile Summary

This PR updates the dedicated databases HA page to describe replication as async-only.

• Removes synchronous and semi-synchronous HA claims.
• Changes SDK and curl examples to request async.
• Replaces stronger sync-mode read guidance with primary-pinning guidance.
• Removes the sync-mode limits row.

Confidence Score: 4/5

The docs change is close, but two user-facing HA guidance paths need fixes before merging.

• The HA page now conflicts with the dedicated databases overview about sync and semi-sync support.
• The primary-pinning guidance overstates the documented PostgreSQL pooler behavior for bare SELECT ... FOR UPDATE.
• The async-only examples and durability text otherwise match the stated PR intent.

src/routes/docs/products/databases/dedicated/high-availability/+page.markdoc

Important Files Changed

Filename	Overview
src/routes/docs/products/databases/dedicated/high-availability/+page.markdoc	Updates HA documentation and examples for async-only replication, with follow-up needed for a nearby overview contradiction and PostgreSQL read-pinning wording.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
src/routes/docs/products/databases/dedicated/high-availability/+page.markdoc:4
**Overview Still Promises Sync**

This page now says HA is async-only, but the dedicated databases overview still advertises synchronous and semi-synchronous replicas for the same feature. A reader can enter through that overview, try `sync`, and hit the API rejection described here.

### Issue 2 of 2
src/routes/docs/products/databases/dedicated/high-availability/+page.markdoc:662
**PostgreSQL Reads May Replicate**

The `SELECT ... FOR UPDATE` guidance is broader than the documented pooler behavior. The pooler docs only guarantee that PostgreSQL statements inside a transaction go to the primary, so a bare PostgreSQL `SELECT ... FOR UPDATE` can still be treated as a replica read and miss the read-your-writes guarantee this bullet promises.

_{Reviews (1): Last reviewed commit: "docs(databases): describe HA replication..." | Re-trigger Greptile}

[greptile-apps]

Overview Still Promises Sync

This page now says HA is async-only, but the dedicated databases overview still advertises synchronous and semi-synchronous replicas for the same feature. A reader can enter through that overview, try sync, and hit the API rejection described here.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/routes/docs/products/databases/dedicated/high-availability/+page.markdoc
Line: 4

Comment:
**Overview Still Promises Sync**

This page now says HA is async-only, but the dedicated databases overview still advertises synchronous and semi-synchronous replicas for the same feature. A reader can enter through that overview, try `sync`, and hit the API rejection described here.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

PostgreSQL Reads May Replicate

The SELECT ... FOR UPDATE guidance is broader than the documented pooler behavior. The pooler docs only guarantee that PostgreSQL statements inside a transaction go to the primary, so a bare PostgreSQL SELECT ... FOR UPDATE can still be treated as a replica read and miss the read-your-writes guarantee this bullet promises.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/routes/docs/products/databases/dedicated/high-availability/+page.markdoc
Line: 662

Comment:
**PostgreSQL Reads May Replicate**

The `SELECT ... FOR UPDATE` guidance is broader than the documented pooler behavior. The pooler docs only guarantee that PostgreSQL statements inside a transaction go to the primary, so a bare PostgreSQL `SELECT ... FOR UPDATE` can still be treated as a replica read and miss the read-your-writes guarantee this bullet promises.

How can I resolve this? If you propose a fix, please make it concise.

[abnegate]

Closing per Jake's direction — the honest-async-only docs approach is being dropped in favor of a different direction on syncMode.