feat: 2pc crash recovery docs

Author: levkk

docs/configuration/pgdog.toml/general.md

@@ -431,19 +431,19 @@ Default: **`false`** (disabled)
 
 ### `two_phase_commit`
 
-Enable [two-phase commit](../../features/sharding/2pc.md) for write, cross-shard transactions.
+Enable [two-phase commit](../../features/sharding/2pc/index.md) for write, cross-shard transactions.
 
 Default: **`false`** (disabled)
 
 ### `two_phase_commit_auto`
 
-Enable automatic conversion of single-statement write transactions to use [two-phase commit](../../features/sharding/2pc.md).
+Enable automatic conversion of single-statement write transactions to use [two-phase commit](../../features/sharding/2pc/index.md).
 
 Default: **`true`** (enabled)
 
 ### `two_phase_commit_wal_dir`
 
-Directory where the [two-phase commit](../../features/sharding/2pc.md) write-ahead log is stored.
+Directory where the [two-phase commit](../../features/sharding/2pc/index.md) write-ahead log is stored.
 
 !!! note "Requires restart"
     This setting cannot be changed at runtime.

docs/configuration/pgdog.toml/rewrite.md

@@ -31,7 +31,7 @@ The `rewrite` section controls PgDog's automatic SQL rewrites for sharded databa
 | `primary_key` | Behavior when an `INSERT` is missing a `BIGINT` primary key: `error` rejects the statement,<br>`rewrite` auto-injects `pgdog.unique_id()` for missing keys,<br>`ignore` allows the INSERT without modification. | `"ignore"` |
 
 !!! note "Two-phase commit"
-    Consider enabling [two-phase commit](../../features/sharding/2pc.md) when either feature is set to `rewrite`. Without it, rewrites are committed shard-by-shard and can leave partial changes if a transaction fails.
+    Consider enabling [two-phase commit](../../features/sharding/2pc/index.md) when either feature is set to `rewrite`. Without it, rewrites are committed shard-by-shard and can leave partial changes if a transaction fails.
 
 ## Runtime overrides
 

docs/features/sharding/2pc/crash-recovery.md

@@ -1,16 +1,20 @@
+---
+icon: material/backup-restore
+---
+
 # Crash recovery
 
 !!! note "New feature"
     This feature is new and experimental. Please make sure to test it before
     deploying to production and let us know if you run into any issues.
 
-[Two-phase commit](index.md) requires different state to be stored on each shard during the commit phase. If PgDog were to crash during this step, the state in which each transaction is on each shard would be impossible to determine.
+[Two-phase commit](index.md) requires different state to be stored on each shard during the commit phase. If PgDog were to crash during this step, it would be impossible to determine the state of each transaction on each shard.
 
-To avoid this, PgDog can write the commit state of each transaction into its own write-ahead log (WAL). When its restarted, PgDog reads from the log and restores the 2pc state to what it was, allowing it to finish any in-flight transactions.
+To avoid this, PgDog can write the commit state of each two-phase transaction into its own write-ahead log (WAL). When it's restarted, PgDog reads from the log and restores the 2PC state to what it was, allowing it to finish any in-flight transactions.
 
 ## How it works
 
-The WAL requires PgDog to run on a machine with a durable storage medium. If you're using our [Helm chart](../../installation.md#kubernetes), you can enable this with configuration:
+The WAL requires PgDog to run on a machine with a durable storage medium. If you're using our [Helm chart](../../../installation.md#kubernetes), you can enable this directly in the chart:
 
 ```yaml title="values.yaml"
 statefulSet:
@@ -19,7 +23,7 @@ statefulSet:
     enabled: true
 ```
 
-The `walPvc` flag will provision a Persistent Volume Claim (PVC) and attach the volume to each replica in the deployment. It will also configure the necessary [`pgdog.toml`](../../configuration/pgdog.toml/general.md) settings:
+The `walPvc` flag will provision a Persistent Volume Claim (PVC) and attach its own volume to each replica in the deployment. It will also configure the necessary [`pgdog.toml`](../../../configuration/pgdog.toml/general.md) settings:
 
 === "pgdog.toml"
     ```toml
@@ -28,42 +32,42 @@ The `walPvc` flag will provision a Persistent Volume Claim (PVC) and attach the
     ```
 === "Helm chart"
     ```yaml
-    # These are configured automatically.
+    # This is configured automatically.
     twoPhaseCommitWalDir: "/var/lib/pgdog/wal"
     ```
 
 Our WAL has no Kubernetes dependency, so you can use it if you're deploying PgDog anywhere else, as long as you have a durable disk, e.g., EBS volume, SSD, etc.
 
 ### Configuration
 
-The WAL has a couple settings that allows you to tweak its performance:
+The WAL has a couple of settings that allow you to tweak its performance:
 
 | Setting | Description |
 |-|-|
-| `two_phase_commit_fsync_interval` | Wait this long (in ms, **0** by default) before calling `fsync` on a group of WAL records written to the log. |
-| `two_phase_commit_checkpoint_interval` | How often the checkpointer runs (in ms, **15 seconds** by default) to remove unnecessary WAL segments. |
+| `two_phase_commit_wal_fsync_interval` | Wait this long (in ms, **0** by default) before calling `fsync` on a group of WAL records written to the log. |
+| `two_phase_commit_wal_checkpoint_interval` | How often the checkpointer runs (in ms, **15 seconds** by default) to remove unnecessary WAL segments. |
 | `two_phase_commit_wal_segment_size` | The size of each WAL segment, in bytes. The default, **16MB**, is usually good enough. |
 
-The default settings there are usually optimal for most deployments. The fsync interval lever allows you to optimize WAL disk performance in highly concurrenct scenarios, e.g., thousands of clients
-executing 2pc transactions concurrently.
+The default settings are usually optimal for most deployments. The fsync interval allows you to optimize WAL disk performance in highly concurrent scenarios, e.g., thousands of clients
+executing 2PC transactions concurrently.
 
 ## Architecture
 
-PgDog's write-ahead log architecture is loosly based on Postgres, with some minor differences. Like Postgres, PgDog implements it using three independent components:
+PgDog's write-ahead log architecture is loosely based on Postgres, with some differences. Like Postgres, PgDog implements it using three independent components:
 
 | Component | Description |
 |-|-|
-| [WAL writer](#wal-writer) | Background thread responsible for writing records to WAL segments (files). |
-| [Checkpointer](#checkpointer) | Background thread responsible for removing old WAL segments no longer necessary for recovery. |
-| [Recovery](#recovery) | Foreground thread that runs on PgDog startup and replays the WAL to restore its in-memory state to a consistent point. |
+| [WAL writer](#wal-writer) | Background task responsible for writing records to WAL segments (files). |
+| [Checkpointer](#checkpointer) | Background task responsible for removing old WAL segments no longer necessary for recovery. |
+| [Recovery](#recovery) | Foreground task that runs on PgDog startup and replays the WAL to restore its in-memory state to a consistent point. |
 
 ### WAL writer
 
 The WAL writer is a background task (we are using Tokio under the hood), which is responsible for writing data into the write-ahead log. It receives records from clients via a synchronization primitive (a queue) and writes them to disk, in batches.
 
 Once written, the WAL writer sends a signal back to each client notifying them that their transaction state is safe on disk, and they can proceed. The clients then execute the transaction control statements against the Postgres shards themselves (e.g., `PREPARE TRANSACTION`, `COMMIT PREPARED`).
 
-If PgDog were to crash at any time, the state of each transaction can be restored from disk and the transaction control statements replayed against the Postgres shards, either rolling back or comitting a two-phase transaction.
+If PgDog were to crash at any time, the state of each transaction can be restored from disk and the transaction control statements replayed against the Postgres shards, either rolling back or committing a two-phase transaction.
 
 #### WAL segments
 
@@ -83,30 +87,30 @@ By default, PgDog's segment size is **16MB**, just like Postgres. This ensures t
 
 ##### Segment size
 
-The segments are rotated by a background task asynchronously. This is one key difference between PgDog's implementation and Postgres: the segment size isn't guaranteed. While the rotation takes place, in-flight transactions state is written to the previous segment. This removes the need for us to _lock_ the WAL during a write, i.e., implementing our own version of `WALWriteLock`.
+The segments are rotated asynchronously by a background task. This is one key difference between PgDog's implementation and Postgres: the segment size isn't guaranteed. While the rotation takes place, in-flight transaction state is written to the previous segment. This removes the need for us to _lock_ the WAL during a write, i.e., implementing our own version of `WALWriteLock`.
 
 #### Partial records
 
 All of our WAL segments contain complete records. This makes [recovery](#recovery) easier, but also contributes to the variable [segment size](#segment-size).
 
 ### Checkpointer
 
-The checkpointer is a background task that runs on a loop and removes any WAL segments that are no longer needed for [recovery](#recovery). These segments contain 2pc stages for transactions that have been already been fully committed to Postgres.
+The checkpointer is a background task that runs in a loop and removes any WAL segments that are no longer needed for [recovery](#recovery). These segments contain 2PC stages for transactions that have already been fully committed to Postgres.
 
-Unlike the Postgres checkpointer which needs to update data files to do its job, PgDog's checkpointer only needs to delete unused WAL segments. This makes it very fast. It runs on a regular interval, configurable in [`pgdog.toml`](../../configuration/pgdog.toml/general.md):
+Unlike the Postgres checkpointer which needs to update data files to do its job, PgDog's checkpointer only needs to delete unused WAL segments. This makes it very fast. It runs on a regular interval, configurable in [`pgdog.toml`](../../../configuration/pgdog.toml/general.md):
 
 === "pgdog.toml"
     ```toml
     [general]
-    two_phase_commit_checkpoint_interval = 15_000
+    two_phase_commit_wal_checkpoint_interval = 15_000
     ```
 === "Helm chart"
     ```yaml
-    twoPhaseCommitCheckpointInterval: 15_000
+    twoPhaseCommitWalCheckpointInterval: 15_000
     ```
 
 ### Recovery
 
-The recovery process's job is to read all available WAL segments and replay their data into the in-memory state of the [2pc](index.md#error-handling) transaction manager. Once the replay is complete, the manager state should be restored to what it was prior to the crash.
+The recovery process's job is to read all available WAL segments and replay their data into the in-memory state of the [2PC](index.md#error-handling) transaction manager. Once the replay is complete, the manager state should be restored to what it was prior to the crash.
 
-The recovery process runs on PgDog startup and will block it until its complete. Clients will not be able to connect until recovery is complete. Just like the [checkpointer](#checkpointer), it only needs to read WAL segments into memory and doesn't perform any writes to disk, so it's very quick.
+The recovery process runs on PgDog startup and will block it until it's complete. Clients will not be able to connect until recovery is complete. Just like the [checkpointer](#checkpointer), it only needs to read WAL segments into memory and doesn't perform any writes to disk, so it's very quick.

docs/features/sharding/2pc/index.md

@@ -31,7 +31,7 @@ Alternatively, if you're running on managed Postgres (e.g., AWS RDS), this param
 !!! note
      Changes to this parameter require a server restart to take effect.
 
-Once prepared transactions are enabled in Postgres, two-phase commit can be enabled in [`pgdog.toml`](../../configuration/pgdog.toml/general.md):
+Once prepared transactions are enabled in Postgres, two-phase commit can be enabled in [`pgdog.toml`](../../../configuration/pgdog.toml/general.md):
 
 === "pgdog.toml"
     ```toml
@@ -93,7 +93,7 @@ This feature allows for easier migrations to sharded databases, without requirin
 
 While it's often desirable to ensure cross-shard writes are atomic, rewriting single-statement transactions to use 4 statements has some performance overhead. For this reason, this feature is **disabled** by default.
 
-If your writes are idempotent and can be safely retried, or your application doesn't have consistency requirements, you don't need to use this. Otherwise, you can enable it in [`pgdog.toml`](../../configuration/pgdog.toml/general.md):
+If your writes are idempotent and can be safely retried, or your application doesn't have consistency requirements, you don't need to use this. Otherwise, you can enable it in [`pgdog.toml`](../../../configuration/pgdog.toml/general.md):
 
 === "pgdog.toml"
     ```toml
@@ -112,6 +112,7 @@ Two-phase commit is used for writes only. Read transactions are finished using n
 ## Read more
 
 {{ next_steps_links([
-    ("Omnisharded tables", "omnishards.md", "Tables replicated to every shard for fast local joins."),
-    ("Cross-shard queries", "cross-shard-queries/index.md", "Run queries that span multiple shards transparently."),
+    ("Crash recovery", "crash-recovery.md", "Recover in-flight two-phase transactions if PgDog crashes."),
+    ("Omnisharded tables", "../omnishards.md", "Tables replicated to every shard for fast local joins."),
+    ("Cross-shard queries", "../cross-shard-queries/index.md", "Run queries that span multiple shards transparently."),
 ]) }}

docs/features/sharding/cross-shard-queries/copy.md

@@ -51,6 +51,6 @@ If the query fetches rows from more than one shard, PgDog will also ignore any `
 ## Read more
 
 {{ next_steps_links([
-    ("Two-phase commit", "../2pc.md", "Atomic transactions spanning multiple shards."),
+    ("Two-phase commit", "../2pc/index.md", "Atomic transactions spanning multiple shards."),
     ("Omnisharded tables", "../omnishards.md", "Tables replicated to every shard for fast local joins."),
 ]) }}

docs/features/sharding/cross-shard-queries/ddl.md

@@ -8,7 +8,7 @@ icon: material/table-cog
 
 ## Atomicity
 
-DDL statements should be atomic across all shards. This is to protect against a single shard failing to create a table or index, which could result in an inconsistent schema. PgDog can use [two-phase commit](../2pc.md) to ensure this is the case, however that means that all DDL statements must be executed inside a transaction, for example:
+DDL statements should be atomic across all shards. This is to protect against a single shard failing to create a table or index, which could result in an inconsistent schema. PgDog can use [two-phase commit](../2pc/index.md) to ensure this is the case, however that means that all DDL statements must be executed inside a transaction, for example:
 
 ```postgresql
 BEGIN;

docs/features/sharding/cross-shard-queries/insert.md

@@ -31,7 +31,7 @@ This is a common pattern for tables that don't have a sharding key, or tables th
 
 ### Omnisharded consistency
 
-Unless [two-phase commit](../2pc.md) is enabled, inserts into omnisharded tables are not guaranteed to be atomic. It is possible for the statement to succeed on some of the shards and not others.
+Unless [two-phase commit](../2pc/index.md) is enabled, inserts into omnisharded tables are not guaranteed to be atomic. It is possible for the statement to succeed on some of the shards and not others.
 
 If you don't want to or can't enable two-phase commit on your database shards, consider sending cross-shard inserts inside a transaction or writing idempotent statements, for example:
 
@@ -47,7 +47,7 @@ COMMIT;
 This gives you a much higher chance of writing rows on all shards, since you will know if your statement violated a constraint (e.g., unique index or `NOT NULL` check) before committing the transaction.
 
 !!! warning "Two-phase commit"
-    Enabling [two-phase commit](../2pc.md) is highly recommended. It's been tested and works well in production.
+    Enabling [two-phase commit](../2pc/index.md) is highly recommended. It's been tested and works well in production.
 
 ### Primary keys in omnisharded tables
 
@@ -167,7 +167,7 @@ RETURNING id;
 The `id` column will be generated by the database (and not PgDog), globally unique, and matched to the shard it's generated on, as guaranteed by the [sharded sequence](../sequences.md) implementation.
 
 !!! warning "Sharded tables only"
-    Make sure to **never** use sharded sequences with **omnisharded** tables. They are not guaranteed to generate the same value on all shards, even with [two-phase commit](../2pc.md), and could cause primary key drift across shards.
+    Make sure to **never** use sharded sequences with **omnisharded** tables. They are not guaranteed to generate the same value on all shards, even with [two-phase commit](../2pc/index.md), and could cause primary key drift across shards.
 
 ## Composite primary keys
 
@@ -238,4 +238,4 @@ Requiring transactions ensures that if one of the `INSERT` statements fails, e.g
 
 !!! warning "Two-phase commit"
 
-    Much like [omnisharded](#omnisharded-tables) table inserts, it's best to enable [two-phase commit](../2pc.md) before attempting cross-shard multi-tuple inserts. This feature increases the likelihood that cross-shard transactions are atomic.
+    Much like [omnisharded](#omnisharded-tables) table inserts, it's best to enable [two-phase commit](../2pc/index.md) before attempting cross-shard multi-tuple inserts. This feature increases the likelihood that cross-shard transactions are atomic.

docs/features/sharding/cross-shard-queries/update.md

@@ -14,7 +14,7 @@ UPDATE users SET is_admin = true WHERE email LIKE '%@pgdog.dev';
 
 ## Consistency
 
-Much like cross-shard [`INSERT`](insert.md) statements, any updates to multiple rows on multiple databases outside a [two-phase](../2pc.md) transaction are not guaranteed to be atomic. It's always best to send updates inside a transaction, like so:
+Much like cross-shard [`INSERT`](insert.md) statements, any updates to multiple rows on multiple databases outside a [two-phase](../2pc/index.md) transaction are not guaranteed to be atomic. It's always best to send updates inside a transaction, like so:
 
 ```postgresql
 BEGIN;

docs/features/sharding/index.md

@@ -34,7 +34,7 @@ PgDog is a query router. It can extract sharding hints directly from the SQL que
 
 ### Data consistency
 
-To make sure data is atomically written in cross-shard transactions, PgDog supports PostgreSQL's prepared transactions and [two-phase commit](2pc.md).
+To make sure data is atomically written in cross-shard transactions, PgDog supports PostgreSQL's prepared transactions and [two-phase commit](2pc/index.md).
 
 ## Managing data
 

docs/features/sharding/omnishards.md

@@ -52,7 +52,7 @@ WHERE users.id = $1;
 
 ### Consistency
 
-Writing data to omnisharded tables is atomic if you enable [two-phase commit](2pc.md).
+Writing data to omnisharded tables is atomic if you enable [two-phase commit](2pc/index.md).
 
 If you can't or choose not to use 2pc, make sure writes to omnisharded tables can be repeated in case of failure. This can be achieved by using unique indexes and `INSERT ... ON CONFLICT ... DO UPDATE` queries.