From 9123290f7375a04cf5e92cd51f04481780fdeae7 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Sat, 1 Nov 2025 17:51:34 +0100 Subject: [PATCH 01/14] reads failover to primary --- .../howto/pg-reads-failover-to-primary.md | 435 ++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 436 insertions(+) create mode 100644 docs/products/postgresql/howto/pg-reads-failover-to-primary.md diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md new file mode 100644 index 000000000..83319db3d --- /dev/null +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -0,0 +1,435 @@ +--- +title: Aiven for PostgreSQL® reads failover to the primary +sidebar_label: Reads failover to primary +limited: true +--- + +Aiven for PostgreSQL customers with Business and Premium plans utilize standby nodes for HA failover. Customers frequently direct read queries to these standby nodes as an alternative to a dedicated read-replica to optimize their costs. However, if a standby node fails, the corresponding replica connection URI becomes unreachable. The service remains in this state until a new replica is automatically provisioned and restored from a backup, a process that can lead to significant downtime for applications that rely on the replica. + +In order to solve this problem, this feature provides a mechanism to automatically and temporarily redirect read-only traffic from an unavailable secondary (read replica) node to the healthy primary node. + +This feature addresses the problem by providing a mechanism to **automatically and temporarily redirect read-only traffic from an unavailable standby node to the healthy primary node**. + +The diagram below illustrates the **complete HA Replica DNS lifecycle**, including feature enablement, failover, recovery, and disablement: + +```mermaid +sequenceDiagram + +autonumber + +participant Customer + +participant Acorn + +participant DB as 🗄️ Aiven DB + +participant Executor as ⚙️ Executor + +participant Primary as 🟢 Primary Node + +participant Standby1 as 🟡 Standby Node 1 + +participant Standby2 as 🟡 Standby Node 2 + +participant DNSProvider as 🌐 DNS Provider + + + +%% --- Phase 1: Feature Activation --- + +rect rgba(230,245,255,0.8) + +Note over Customer,DB: 🟦 Customer enables HA Replica DNS + +Customer->>Acorn: Enable HA Replica DNS + +Acorn->>DB: service_update(enable_ha_replica_dns = true) + +DB-->>DB: Insert ha_replica DNS record + +DB-->>Executor: Schedule build_dns_records task + +Executor-->>DNSProvider: Build ha_replica DNS → replica + +Executor-->>Primary: Send enable_ha_replica_dns value + +Note over Primary: Starts monitoring standby health + +Customer-->>Acorn: Request service info + +Acorn-->>Customer: Return ha_replica.avns.net URI + +end + + + +%% --- Phase 2: Failover Trigger --- + +rect rgba(255,245,230,0.8) + +Note over Primary,Standby2: 🩺 Primary monitors standbys + +Primary->>Standby1: SELECT 1; + +Standby1--x Primary: Timeout ❌ + +Primary->>Standby2: SELECT 1; + +Standby2--x Primary: Timeout ❌ + +Note over Primary: All standbys unavailable > HA_REPLICA_FAILOVER_UNAVAILABLE_TIMEOUT + +Primary-->>DB: Update ha_replica_dns_target = "primary" + +DB-->>Executor: Schedule build_dns_records task + +Executor-->>DNSProvider: Update ha_replica DNS → primary + +Note over DNSProvider: ha_replica.avns.net now points to primary + +end + + + +%% --- Phase 3: Standby Recovery --- + +rect rgba(240,255,240,0.8) + +Note over Primary,Standby2: 🟢 Standbys are healthy again + +Primary->>Standby1: SELECT 1 OK ✅ + +Primary->>Standby2: SELECT 1 OK ✅ + +Primary-->>DB: Update ha_replica_dns_target = "replica" + +DB-->>Executor: Schedule build_dns_records task + +Executor-->>DNSProvider: Update ha_replica DNS → replicas + +Note over DNSProvider: ha_replica.avns.net now points to standby nodes + +Note over Primary: Normal monitoring continues, clients route read-only traffic to replicas + +end + + + +%% --- Phase 4: Feature Disable --- + +rect rgba(255,230,230,0.8) + +Note over Customer,DB: 🔴 Customer disables HA Replica DNS + +Customer->>Acorn: Disable HA Replica DNS + +Acorn->>DB: service_update(enable_ha_replica_dns = false) + +DB-->>Executor: Schedule build_dns_records task + +Executor-->>DNSProvider: Suspend ha_replica DNS (no target) + +Note over Primary: 🛑 Primary stops monitoring standby health + +Note over Customer: HA Replica URI no longer available, read-only traffic uses standard replicas + +end +``` + +## 1. Enabling the HA Replica DNS + +By default, the **HA Replica DNS** feature is disabled for all services. Customers must explicitly enable it via the service’s user configuration (`enable_ha_replica_dns = true`). + +When enabled, **Aiven DB** creates new **CNAME DNS records** for the service under the `ha_replica` usage. Based on the value of `ha_replica_dns_target` in the service state, the records will point to the corresponding URI. If the key has no value, the DNS defaults to `replica`. + +After creating the DNS records, **Aiven DB** schedules a `build_dns_records` work item. Executor later processes the item, calling the DNS Provider to add the record. At this point, the DNS is available. + +Once the feature is enabled, the primary node starts monitoring standby health. The primary will report if the new DNS needs to be rebuilt via `ha_replica_dns_target`. Meanwhile, the customer can see the new HA Replica connection URI when requesting the service information. + +--- + +### Enabling HA Replica DNS Flow + +The diagram below illustrates the **initial flow** when the HA Replica DNS feature is enabled: + +```mermaid + +sequenceDiagram + +autonumber + +participant Customer + +participant Acorn + +participant DB as Aiven DB + +participant Executor + +participant Primary as Primary Node + + + + +rect rgba(230,230,255,0.8) + +Note over Customer,DB: 🟦 Enable HA Replica DNS Feature + +Customer->>Acorn: Enable HA Replica DNS + +Acorn->>DB: service_update(enable_ha_replica_dns = true) + +end + + + +rect rgba(230,255,230,0.8) + +Note over DB,Executor: 🟩 Database inserts DNS Records and triggers rebuild + +DB-->>DB: Insert ha_replica DNS record + +DB-->>Executor: Schedule build_dns_records task + +Executor-->>Executor: Calls DNS Provider and updates DNS + +end + + + +rect rgba(255,245,230,0.8) + +Note over Executor,Primary: 🟨 Activation and monitoring + +Executor-->>Primary: Send enable_ha_replica_dns value + +Note over Primary: Starts monitoring standby health + +end + + + +rect rgba(255,230,230,0.8) + +Note over Customer,Acorn: 🟥 Exposure + +Customer-->>Acorn: Get service info + +Acorn-->>DB: Fetch DNS components + +Acorn-->>Customer: Return ha_replica.avns.net URI + +end +``` + +## 2. Failover + +As mentioned earlier, the primary node continuously monitors the standby nodes to ensure they are available for read operations. If it detects that **all standby nodes are unreachable** for longer than `ha_replica_failover_unavailable_timeout` (default 30 seconds), it updates `ha_replica_dns_target` to `'primary'`. + +Once this change is reflected in the service state, **Aiven DB** recognizes that the HA Replica DNS records must be updated to point to the primary URI instead of the standbys. It schedules a `build_dns_records` work item, which **Executor** later processes. When processing the work item, Executor communicates with the DNS Provider to rebuild the records, ensuring that the HA Replica DNS now resolves to the primary node. + +During this period, new client connections that rely on the HA Replica DNS will connect to the primary, maintaining availability even though the standbys are down. Existing connections to the replicas may fail, but the system ensures that all new read-only traffic is routed to a healthy node. + +### Failover HA Replica DNS Flow + +The diagram below illustrates the **failover flow** when all standby nodes become unavailable: + +```mermaid +sequenceDiagram + +autonumber + +participant Primary as 🟢 Primary Node + +participant Standby1 as 🟡 Standby Node 1 + +participant Standby2 as 🟡 Standby Node 2 + +participant Database as 🗄️ Aiven DB + +participant Executor as ⚙️ Executor + +participant DNSProvider as 🌐 DNS Provider + + + +%% --- PHASE 1: HEALTH CHECK --- + +rect rgb(235, 245, 255) + +Note over Primary,Standby2: 🩺 **Phase 1 — Standby Health Monitoring** + +Primary->>Standby1: SELECT 1; + +Standby1--x Primary: Connection timeout ❌ + +Primary->>Standby2: SELECT 1; + +Standby2--x Primary: Connection timeout ❌ + +Note over Primary: All standbys unreachable for
HA_REPLICA_FAILOVER_UNAVAILABLE_TIMEOUT + +end + + + +%% --- PHASE 2: FAILOVER TRIGGER --- + +rect rgb(255, 245, 230) + +Note over Primary,Database: 🚨 **Phase 2 — Failover Trigger** + +Primary-->>Database: Update service_state["ha_replica_dns_target"] = "primary" + +Database-->>Executor: Schedule build_dns_records work_item + +end + + + +%% --- PHASE 3: DNS REBUILD --- + +rect rgb(240, 255, 240) + +Note over Executor,DNSProvider: 🔄 **Phase 3 — DNS Rebuild** + +Executor-->>DNSProvider: Rebuild DNS records (ha_replica → primary) + +Note over DNSProvider: ha_replica.avns.net now resolves to
the primary node's IP + +end + + + +%% --- PHASE 4: CONTINUATION --- + +rect rgb(245, 245, 245) + +Note over Primary,Database: 🕒 **Phase 4 — Monitoring Continues** + +Note over Primary: Standby checks keep running + +end +``` + +## 3. Recovery + +Once the standby nodes recover and are reachable again, the HA Replica DNS can be reverted to point back to the replicas. The primary node continuously monitors the standby nodes’ health, and when it detects that all standbys are healthy, it updates `ha_replica_dns_target` to `'replica'`. + +This triggers the same process as before: **Aiven DB** schedules a `build_dns_records` work item, and Executor updates the HA Replica DNS. As a result, the HA Replica URI now resolves to the standby nodes again, allowing new read-only connections to be routed to the replicas. The primary node continues monitoring all standbys to ensure the HA Replica DNS always points to healthy nodes. + +### Recovery HA Replica DNS Flow + +The diagram below illustrates the **recovery flow** when all standby nodes become available: + +```mermaid +sequenceDiagram + autonumber + participant Primary as 🟢 Primary Node + participant Standby1 as 🟡 Standby Node 1 + participant Standby2 as 🟡 Standby Node 2 + participant Database as 🗄️ Aiven DB + participant Executor as ⚙️ Executor + participant DNSProvider as 🌐 DNS Provider + + %% --- Phase 1: Health Monitoring --- + rect rgba(235,245,255,0.8) + Note over Primary,Standby2: 🩺 Primary continues periodic standby health checks + Primary->>Standby1: SELECT 1; + Standby1-->>Primary: OK ✅ + Primary->>Standby2: SELECT 1; + Standby2-->>Primary: OK ✅ + Note over Primary: All standbys are now healthy + end + + %% --- Phase 2: Restore HA Replica DNS Target --- + rect rgba(255,245,230,0.8) + Note over Primary,Database: 🔄 Primary updates ha_replica_dns_target to 'replica' + Primary-->>Database: Update ha_replica_dns_target = "replica" + Database-->>Executor: Schedule build_dns_records work item + end + + %% --- Phase 3: DNS Rebuild --- + rect rgba(240,255,240,0.8) + Note over Executor,DNSProvider: ⚙️ Executor rebuilds HA Replica DNS + Executor-->>DNSProvider: Update ha_replica DNS to point back to replicas + Note over DNSProvider: ha_replica.avns.net now resolves to standby nodes + end + + %% --- Phase 4: Normal Operation --- + rect rgba(245,245,245,0.8) + Note over Primary,Database: 🕒 Monitoring continues as normal + Note over Primary: Clients now route read-only traffic to healthy replicas + end + +``` + +## 4. Disabling the HA Replica DNS + +When the HA Replica DNS feature is disabled for a service, the flow mirrors the enablement process with a few key differences. **Aiven DB** updates the service state to reflect that `enable_ha_replica_dns` is now `false`. The existing HA Replica DNS records are **suspended**, meaning they no longer point to any node. + +At the same time, the primary node stops monitoring the standby nodes for HA Replica failover. From this point onward, the HA Replica URI is no longer available to clients, and read-only traffic must rely on the standard replica URIs. + +--- + +### Disabling HA Replica DNS Flow + +```mermaid +sequenceDiagram + +autonumber + +participant Customer + +participant Acorn + +participant DB as 🗄️ Aiven DB + +participant Executor as ⚙️ Executor + +participant Primary as 🟢 Primary Node + +participant DNSProvider as 🌐 DNS Provider + + + +%% --- Phase 1: Disable Request --- + +rect rgba(255,230,230,0.8) + +Note over Customer,DB: 🔴 Customer disables HA Replica DNS + +Customer->>Acorn: Disable HA Replica DNS + +Acorn->>DB: service_update(enable_ha_replica_dns = false) + +end + + + +%% --- Phase 2: Suspend DNS --- + +rect rgba(240,240,240,0.8) + +Note over DB,Executor: ⏸️ Suspend HA Replica DNS records + +DB-->>Executor: Schedule build_dns_records task + +Executor-->>DNSProvider: Update ha_replica DNS → no target + +Note over DNSProvider: ha_replica.avns.net temporarily resolves to nothing + +end + + + +%% --- Phase 3: Stop Monitoring --- + +rect rgba(245,245,245,0.8) + +Note over Primary: 🛑 Primary stops monitoring standby health + +Note over Customer: HA Replica URI is no longer available. + +end +``` diff --git a/sidebars.ts b/sidebars.ts index 9b544140d..ee7632b8b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1808,6 +1808,7 @@ const sidebars: SidebarsConfig = { 'products/postgresql/howto/use-pgvector', 'products/postgresql/howto/pg-object-size', 'products/postgresql/howto/readonly-user', + 'products/postgresql/howto/pg-reads-failover-to-primary', { type: 'category', label: 'PGAudit', From 9469c38b881db03e4967a8b7ee6b30a4baf03187 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Mon, 3 Nov 2025 11:19:28 +0100 Subject: [PATCH 02/14] updates --- .../howto/pg-reads-failover-to-primary.md | 444 ++---------------- 1 file changed, 42 insertions(+), 402 deletions(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 83319db3d..7cd641d7c 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -4,432 +4,72 @@ sidebar_label: Reads failover to primary limited: true --- -Aiven for PostgreSQL customers with Business and Premium plans utilize standby nodes for HA failover. Customers frequently direct read queries to these standby nodes as an alternative to a dedicated read-replica to optimize their costs. However, if a standby node fails, the corresponding replica connection URI becomes unreachable. The service remains in this state until a new replica is automatically provisioned and restored from a backup, a process that can lead to significant downtime for applications that rely on the replica. +## Overview -In order to solve this problem, this feature provides a mechanism to automatically and temporarily redirect read-only traffic from an unavailable secondary (read replica) node to the healthy primary node. +When you route read-only queries to standby nodes, a standby failure can make your replica URI temporarily unreachable until a new standby is provisioned and catches up. Reads failover to the primary automatically and temporarily redirects read-only traffic to the healthy primary node when all standbys are unavailable, helping you avoid downtime. -This feature addresses the problem by providing a mechanism to **automatically and temporarily redirect read-only traffic from an unavailable standby node to the healthy primary node**. +## Benefits -The diagram below illustrates the **complete HA Replica DNS lifecycle**, including feature enablement, failover, recovery, and disablement: +- Improves availability for read workloads during standby outages +- Reduces operational effort; no app-side routing changes required +- Uses a single, stable connection endpoint for read traffic -```mermaid -sequenceDiagram +## How it works (high level) -autonumber +- When enabled, your service exposes a dedicated HA Replica DNS endpoint for read-only traffic. +- Under normal conditions, this endpoint resolves to standby nodes. +- If all standbys become unavailable, the endpoint automatically switches to the primary. +- When standbys recover, the endpoint switches back to replicas. -participant Customer +## Enable the feature -participant Acorn +You can enable reads failover to the primary from the Console, CLI, or API. -participant DB as 🗄️ Aiven DB +### Console -participant Executor as ⚙️ Executor +1. In the Aiven Console, open your PostgreSQL® service. +1. Go to Service settings. +1. Enable Reads failover to primary (HA Replica DNS). +1. Save changes. -participant Primary as 🟢 Primary Node +### CLI -participant Standby1 as 🟡 Standby Node 1 - -participant Standby2 as 🟡 Standby Node 2 - -participant DNSProvider as 🌐 DNS Provider - - - -%% --- Phase 1: Feature Activation --- - -rect rgba(230,245,255,0.8) - -Note over Customer,DB: 🟦 Customer enables HA Replica DNS - -Customer->>Acorn: Enable HA Replica DNS - -Acorn->>DB: service_update(enable_ha_replica_dns = true) - -DB-->>DB: Insert ha_replica DNS record - -DB-->>Executor: Schedule build_dns_records task - -Executor-->>DNSProvider: Build ha_replica DNS → replica - -Executor-->>Primary: Send enable_ha_replica_dns value - -Note over Primary: Starts monitoring standby health - -Customer-->>Acorn: Request service info - -Acorn-->>Customer: Return ha_replica.avns.net URI - -end - - - -%% --- Phase 2: Failover Trigger --- - -rect rgba(255,245,230,0.8) - -Note over Primary,Standby2: 🩺 Primary monitors standbys - -Primary->>Standby1: SELECT 1; - -Standby1--x Primary: Timeout ❌ - -Primary->>Standby2: SELECT 1; - -Standby2--x Primary: Timeout ❌ - -Note over Primary: All standbys unavailable > HA_REPLICA_FAILOVER_UNAVAILABLE_TIMEOUT - -Primary-->>DB: Update ha_replica_dns_target = "primary" - -DB-->>Executor: Schedule build_dns_records task - -Executor-->>DNSProvider: Update ha_replica DNS → primary - -Note over DNSProvider: ha_replica.avns.net now points to primary - -end - - - -%% --- Phase 3: Standby Recovery --- - -rect rgba(240,255,240,0.8) - -Note over Primary,Standby2: 🟢 Standbys are healthy again - -Primary->>Standby1: SELECT 1 OK ✅ - -Primary->>Standby2: SELECT 1 OK ✅ - -Primary-->>DB: Update ha_replica_dns_target = "replica" - -DB-->>Executor: Schedule build_dns_records task - -Executor-->>DNSProvider: Update ha_replica DNS → replicas - -Note over DNSProvider: ha_replica.avns.net now points to standby nodes - -Note over Primary: Normal monitoring continues, clients route read-only traffic to replicas - -end - - - -%% --- Phase 4: Feature Disable --- - -rect rgba(255,230,230,0.8) - -Note over Customer,DB: 🔴 Customer disables HA Replica DNS - -Customer->>Acorn: Disable HA Replica DNS - -Acorn->>DB: service_update(enable_ha_replica_dns = false) - -DB-->>Executor: Schedule build_dns_records task - -Executor-->>DNSProvider: Suspend ha_replica DNS (no target) - -Note over Primary: 🛑 Primary stops monitoring standby health - -Note over Customer: HA Replica URI no longer available, read-only traffic uses standard replicas - -end +```bash +aiven service update -c enable_ha_replica_dns=true ``` -## 1. Enabling the HA Replica DNS - -By default, the **HA Replica DNS** feature is disabled for all services. Customers must explicitly enable it via the service’s user configuration (`enable_ha_replica_dns = true`). - -When enabled, **Aiven DB** creates new **CNAME DNS records** for the service under the `ha_replica` usage. Based on the value of `ha_replica_dns_target` in the service state, the records will point to the corresponding URI. If the key has no value, the DNS defaults to `replica`. - -After creating the DNS records, **Aiven DB** schedules a `build_dns_records` work item. Executor later processes the item, calling the DNS Provider to add the record. At this point, the DNS is available. - -Once the feature is enabled, the primary node starts monitoring standby health. The primary will report if the new DNS needs to be rebuilt via `ha_replica_dns_target`. Meanwhile, the customer can see the new HA Replica connection URI when requesting the service information. - ---- - -### Enabling HA Replica DNS Flow - -The diagram below illustrates the **initial flow** when the HA Replica DNS feature is enabled: - -```mermaid - -sequenceDiagram - -autonumber - -participant Customer - -participant Acorn - -participant DB as Aiven DB - -participant Executor +### API -participant Primary as Primary Node +Set the `enable_ha_replica_dns` configuration to `true` using the service update endpoint. See the [API reference](/docs/tools/api) for details. +## Use the HA Replica DNS endpoint +- After enabling, retrieve the replica connection URI from the Console, CLI, or API. This URI will automatically redirect to the primary when replicas are unavailable and switch back once replicas are healthy. +- Point your read-only clients to this URI to benefit from automatic failover without changing application logic. +## Considerations -rect rgba(230,230,255,0.8) +- During a failover to primary, read-only traffic is served by the primary. Ensure your application can tolerate reads from the primary if it assumes read-after-write or specific consistency behavior. +- Existing connections to replicas may fail during an outage. New connections using the HA Replica DNS continue to succeed. +- This feature does not create additional replicas; it only redirects read traffic when replicas are unavailable. -Note over Customer,DB: 🟦 Enable HA Replica DNS Feature +## Disable the feature -Customer->>Acorn: Enable HA Replica DNS +You can disable reads failover to the primary at any time. -Acorn->>DB: service_update(enable_ha_replica_dns = true) +### Console (disable) -end +1. In the Aiven Console, open your PostgreSQL® service. +1. Go to Service settings. +1. Disable Reads failover to primary (HA Replica DNS). +1. Save changes. +### CLI (disable) - -rect rgba(230,255,230,0.8) - -Note over DB,Executor: 🟩 Database inserts DNS Records and triggers rebuild - -DB-->>DB: Insert ha_replica DNS record - -DB-->>Executor: Schedule build_dns_records task - -Executor-->>Executor: Calls DNS Provider and updates DNS - -end - - - -rect rgba(255,245,230,0.8) - -Note over Executor,Primary: 🟨 Activation and monitoring - -Executor-->>Primary: Send enable_ha_replica_dns value - -Note over Primary: Starts monitoring standby health - -end - - - -rect rgba(255,230,230,0.8) - -Note over Customer,Acorn: 🟥 Exposure - -Customer-->>Acorn: Get service info - -Acorn-->>DB: Fetch DNS components - -Acorn-->>Customer: Return ha_replica.avns.net URI - -end +```bash +aiven service update -c enable_ha_replica_dns=false ``` -## 2. Failover - -As mentioned earlier, the primary node continuously monitors the standby nodes to ensure they are available for read operations. If it detects that **all standby nodes are unreachable** for longer than `ha_replica_failover_unavailable_timeout` (default 30 seconds), it updates `ha_replica_dns_target` to `'primary'`. - -Once this change is reflected in the service state, **Aiven DB** recognizes that the HA Replica DNS records must be updated to point to the primary URI instead of the standbys. It schedules a `build_dns_records` work item, which **Executor** later processes. When processing the work item, Executor communicates with the DNS Provider to rebuild the records, ensuring that the HA Replica DNS now resolves to the primary node. - -During this period, new client connections that rely on the HA Replica DNS will connect to the primary, maintaining availability even though the standbys are down. Existing connections to the replicas may fail, but the system ensures that all new read-only traffic is routed to a healthy node. +### API (disable) -### Failover HA Replica DNS Flow - -The diagram below illustrates the **failover flow** when all standby nodes become unavailable: - -```mermaid -sequenceDiagram - -autonumber - -participant Primary as 🟢 Primary Node - -participant Standby1 as 🟡 Standby Node 1 - -participant Standby2 as 🟡 Standby Node 2 - -participant Database as 🗄️ Aiven DB - -participant Executor as ⚙️ Executor - -participant DNSProvider as 🌐 DNS Provider - - - -%% --- PHASE 1: HEALTH CHECK --- - -rect rgb(235, 245, 255) - -Note over Primary,Standby2: 🩺 **Phase 1 — Standby Health Monitoring** - -Primary->>Standby1: SELECT 1; - -Standby1--x Primary: Connection timeout ❌ - -Primary->>Standby2: SELECT 1; - -Standby2--x Primary: Connection timeout ❌ - -Note over Primary: All standbys unreachable for
HA_REPLICA_FAILOVER_UNAVAILABLE_TIMEOUT - -end - - - -%% --- PHASE 2: FAILOVER TRIGGER --- - -rect rgb(255, 245, 230) - -Note over Primary,Database: 🚨 **Phase 2 — Failover Trigger** - -Primary-->>Database: Update service_state["ha_replica_dns_target"] = "primary" - -Database-->>Executor: Schedule build_dns_records work_item - -end - - - -%% --- PHASE 3: DNS REBUILD --- - -rect rgb(240, 255, 240) - -Note over Executor,DNSProvider: 🔄 **Phase 3 — DNS Rebuild** - -Executor-->>DNSProvider: Rebuild DNS records (ha_replica → primary) - -Note over DNSProvider: ha_replica.avns.net now resolves to
the primary node's IP - -end - - - -%% --- PHASE 4: CONTINUATION --- - -rect rgb(245, 245, 245) - -Note over Primary,Database: 🕒 **Phase 4 — Monitoring Continues** - -Note over Primary: Standby checks keep running - -end -``` - -## 3. Recovery - -Once the standby nodes recover and are reachable again, the HA Replica DNS can be reverted to point back to the replicas. The primary node continuously monitors the standby nodes’ health, and when it detects that all standbys are healthy, it updates `ha_replica_dns_target` to `'replica'`. - -This triggers the same process as before: **Aiven DB** schedules a `build_dns_records` work item, and Executor updates the HA Replica DNS. As a result, the HA Replica URI now resolves to the standby nodes again, allowing new read-only connections to be routed to the replicas. The primary node continues monitoring all standbys to ensure the HA Replica DNS always points to healthy nodes. - -### Recovery HA Replica DNS Flow - -The diagram below illustrates the **recovery flow** when all standby nodes become available: - -```mermaid -sequenceDiagram - autonumber - participant Primary as 🟢 Primary Node - participant Standby1 as 🟡 Standby Node 1 - participant Standby2 as 🟡 Standby Node 2 - participant Database as 🗄️ Aiven DB - participant Executor as ⚙️ Executor - participant DNSProvider as 🌐 DNS Provider - - %% --- Phase 1: Health Monitoring --- - rect rgba(235,245,255,0.8) - Note over Primary,Standby2: 🩺 Primary continues periodic standby health checks - Primary->>Standby1: SELECT 1; - Standby1-->>Primary: OK ✅ - Primary->>Standby2: SELECT 1; - Standby2-->>Primary: OK ✅ - Note over Primary: All standbys are now healthy - end - - %% --- Phase 2: Restore HA Replica DNS Target --- - rect rgba(255,245,230,0.8) - Note over Primary,Database: 🔄 Primary updates ha_replica_dns_target to 'replica' - Primary-->>Database: Update ha_replica_dns_target = "replica" - Database-->>Executor: Schedule build_dns_records work item - end - - %% --- Phase 3: DNS Rebuild --- - rect rgba(240,255,240,0.8) - Note over Executor,DNSProvider: ⚙️ Executor rebuilds HA Replica DNS - Executor-->>DNSProvider: Update ha_replica DNS to point back to replicas - Note over DNSProvider: ha_replica.avns.net now resolves to standby nodes - end - - %% --- Phase 4: Normal Operation --- - rect rgba(245,245,245,0.8) - Note over Primary,Database: 🕒 Monitoring continues as normal - Note over Primary: Clients now route read-only traffic to healthy replicas - end - -``` - -## 4. Disabling the HA Replica DNS - -When the HA Replica DNS feature is disabled for a service, the flow mirrors the enablement process with a few key differences. **Aiven DB** updates the service state to reflect that `enable_ha_replica_dns` is now `false`. The existing HA Replica DNS records are **suspended**, meaning they no longer point to any node. - -At the same time, the primary node stops monitoring the standby nodes for HA Replica failover. From this point onward, the HA Replica URI is no longer available to clients, and read-only traffic must rely on the standard replica URIs. - ---- - -### Disabling HA Replica DNS Flow - -```mermaid -sequenceDiagram - -autonumber - -participant Customer - -participant Acorn - -participant DB as 🗄️ Aiven DB - -participant Executor as ⚙️ Executor - -participant Primary as 🟢 Primary Node - -participant DNSProvider as 🌐 DNS Provider - - - -%% --- Phase 1: Disable Request --- - -rect rgba(255,230,230,0.8) - -Note over Customer,DB: 🔴 Customer disables HA Replica DNS - -Customer->>Acorn: Disable HA Replica DNS - -Acorn->>DB: service_update(enable_ha_replica_dns = false) - -end - - - -%% --- Phase 2: Suspend DNS --- - -rect rgba(240,240,240,0.8) - -Note over DB,Executor: ⏸️ Suspend HA Replica DNS records - -DB-->>Executor: Schedule build_dns_records task - -Executor-->>DNSProvider: Update ha_replica DNS → no target - -Note over DNSProvider: ha_replica.avns.net temporarily resolves to nothing - -end - - - -%% --- Phase 3: Stop Monitoring --- - -rect rgba(245,245,245,0.8) - -Note over Primary: 🛑 Primary stops monitoring standby health - -Note over Customer: HA Replica URI is no longer available. - -end -``` +Set `enable_ha_replica_dns` to `false` with the service update endpoint. From 6d4e96f4a039b682c2275622b97c06bdb40fae00 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Mon, 3 Nov 2025 14:19:18 +0100 Subject: [PATCH 03/14] ready --- .../howto/pg-reads-failover-to-primary.md | 217 +++++++++++++++--- 1 file changed, 184 insertions(+), 33 deletions(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 7cd641d7c..c420b2021 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -4,72 +4,223 @@ sidebar_label: Reads failover to primary limited: true --- -## Overview +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ConsoleIcon from "@site/src/components/ConsoleIcons"; +import ConsoleLabel from "@site/src/components/ConsoleIcons"; -When you route read-only queries to standby nodes, a standby failure can make your replica URI temporarily unreachable until a new standby is provisioned and catches up. Reads failover to the primary automatically and temporarily redirects read-only traffic to the healthy primary node when all standbys are unavailable, helping you avoid downtime. +Enable automatic failover for your Aiven for PostgreSQL® read workloads to ensure uninterrupted access when standby nodes are unavailable. + +When you route read-only queries to standby nodes, a standby failure can make your replica +URI temporarily unreachable until a new standby is provisioned and catches up. Reads +failover to the primary automatically and temporarily redirects read-only traffic to the +healthy primary node when all standbys are unavailable, helping you avoid downtime. ## Benefits -- Improves availability for read workloads during standby outages -- Reduces operational effort; no app-side routing changes required -- Uses a single, stable connection endpoint for read traffic +- Improves availability for read workloads during standby outages. +- Reduces operational effort; no app-side routing changes required. +- Uses a single, stable connection endpoint for read traffic. -## How it works (high level) +## How it works -- When enabled, your service exposes a dedicated HA Replica DNS endpoint for read-only traffic. +- This feature doesn't create additional replicas; it redirects read traffic when + replicas are unavailable. When enabled, your service exposes a dedicated HA replica + DNS endpoint for read-only traffic. - Under normal conditions, this endpoint resolves to standby nodes. - If all standbys become unavailable, the endpoint automatically switches to the primary. - When standbys recover, the endpoint switches back to replicas. ## Enable the feature -You can enable reads failover to the primary from the Console, CLI, or API. +You can manage reads failover to the primary from the Aiven Console, CLI, API, or using +Aiven Provider for Terraform. + +### Prerequisites + +- Aiven for PostgreSQL service using +- Tool for managing the feature: + - [Aiven Console](https://console.aiven.io/) + - [Aiven CLI](/docs/tools/cli) + - [Aiven API](/docs/tools/api) + - [Aiven Provider for Terraform](/docs/tools/terraform) + - [Aiven Operator for Kubernetes®](/docs/tools/kubernetes) +- During a failover to primary, read-only traffic is served by the primary. Ensure your + application can tolerate reads from the primary if it assumes read-after-write or + specific consistency behavior. -### Console +### Use your preferred tool -1. In the Aiven Console, open your PostgreSQL® service. -1. Go to Service settings. -1. Enable Reads failover to primary (HA Replica DNS). -1. Save changes. + + -### CLI +1. In the [Aiven Console](https://console.aiven.io/), open your Aiven for PostgreSQL® + service. +1. Go to service > **Advance configuration**. +1. Click **Configure** > **Add configuration option**. +1. Use the search bar to find `pg.enable_ha_replica_dns`, and set it to **Enabled**. +1. Click **Save configuration**. + + + + +Run ```bash -aiven service update -c enable_ha_replica_dns=true +aiven service update SERVICE_NAME -c enable_ha_replica_dns=true ``` -### API + + + +Call the +[ServiceUpdate endpoint](https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate) +to set the `enable_ha_replica_dns` configuration to `true`: + +```bash {8} +curl --request PUT \ +--url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \ +--header 'Authorization: Bearer BEARER_TOKEN' \ +--header 'content-type: application json' \ +--data + '{ + "user_config": { + "enable_ha_replica_dns": true + } + }' +``` -Set the `enable_ha_replica_dns` configuration to `true` using the service update endpoint. See the [API reference](/docs/tools/api) for details. + + -## Use the HA Replica DNS endpoint +Add or update your Terraform resource for the Aiven for PostgreSQL service: + +```hcl {8} +resource "aiven_pg" "example" { + project = "PROJECT_NAME" + cloud_name = "CLOUD_REGION" + plan = "PLAN_NAME" + service_name = "SERVICE_NAME" + + user_config = { + enable_ha_replica_dns = true + # ...other config options + } +} +``` + + + + +Add or update your Aiven Service custom resource manifest: + +```yaml {10} +apiVersion: aiven.io/v1alpha1 +kind: PostgreSQL +metadata: + name: SERVICE_NAME +spec: + project: PROJECT_NAME + cloudName: CLOUD_REGION + plan: PLAN_NAME + userConfig: + enable_ha_replica_dns: true + # ...other config options +``` -- After enabling, retrieve the replica connection URI from the Console, CLI, or API. This URI will automatically redirect to the primary when replicas are unavailable and switch back once replicas are healthy. -- Point your read-only clients to this URI to benefit from automatic failover without changing application logic. + + -## Considerations +## Use the HA-replica-DNS endpoint -- During a failover to primary, read-only traffic is served by the primary. Ensure your application can tolerate reads from the primary if it assumes read-after-write or specific consistency behavior. -- Existing connections to replicas may fail during an outage. New connections using the HA Replica DNS continue to succeed. -- This feature does not create additional replicas; it only redirects read traffic when replicas are unavailable. +1. After enabling, retrieve the replica connection URI from the console, CLI, or API. + This URI will automatically redirect to the primary when replicas are unavailable and + switch back once replicas are healthy. +1. Point your read-only clients to this URI to benefit from automatic failover without + changing application logic. + +Existing connections to replicas may fail during an outage. New connections using the HA replica DNS continue to succeed. ## Disable the feature You can disable reads failover to the primary at any time. -### Console (disable) + + + +1. In the [Aiven Console](https://console.aiven.io/), open your Aiven for PostgreSQL® + service. +1. Go to service > **Advance configuration**. +1. Click **Configure** > **Add configuration option**. +1. Use the search bar to find `pg.enable_ha_replica_dns`, and set it to **Disabled**. +1. Click **Save configuration**. -1. In the Aiven Console, open your PostgreSQL® service. -1. Go to Service settings. -1. Disable Reads failover to primary (HA Replica DNS). -1. Save changes. + + -### CLI (disable) +Run ```bash -aiven service update -c enable_ha_replica_dns=false +aiven service update SERVICE_NAME -c enable_ha_replica_dns=false +``` + + + + +Call the +[ServiceUpdate endpoint](https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate) +to set the `enable_ha_replica_dns` configuration to `true`: + +```bash {8} +curl --request PUT \ +--url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \ +--header 'Authorization: Bearer BEARER_TOKEN' \ +--header 'content-type: application json' \ +--data + '{ + "user_config": { + "enable_ha_replica_dns": false + } + }' +``` + + + + +Add or update your Terraform resource for the Aiven for PostgreSQL service: + +```hcl {8} +resource "aiven_pg" "example" { + project = "PROJECT_NAME" + cloud_name = "CLOUD_REGION" + plan = "PLAN_NAME" + service_name = "SERVICE_NAME" + + user_config = { + enable_ha_replica_dns = false + # ...other config options + } +} ``` -### API (disable) + + + +Add or update your Aiven Service custom resource manifest: + +```yaml {10} +apiVersion: aiven.io/v1alpha1 +kind: PostgreSQL +metadata: + name: SERVICE_NAME +spec: + project: PROJECT_NAME + cloudName: CLOUD_REGION + plan: PLAN_NAME + userConfig: + enable_ha_replica_dns: false + # ...other config options +``` -Set `enable_ha_replica_dns` to `false` with the service update endpoint. + + From cfc3711708837131e6382d0809865fa0fa61b8f7 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Tue, 4 Nov 2025 11:59:37 +0100 Subject: [PATCH 04/14] feedback --- .../postgresql/howto/pg-reads-failover-to-primary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index c420b2021..a970b39c9 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -38,7 +38,7 @@ Aiven Provider for Terraform. ### Prerequisites -- Aiven for PostgreSQL service using +- Aiven for PostgreSQL service on a [Business or Premium plan](https://aiven.io/pricing?product=pg) (see how to [change your plan](/docs/platform/howto/scale-services)) - Tool for managing the feature: - [Aiven Console](https://console.aiven.io/) - [Aiven CLI](/docs/tools/cli) @@ -58,7 +58,7 @@ Aiven Provider for Terraform. service. 1. Go to service > **Advance configuration**. 1. Click **Configure** > **Add configuration option**. -1. Use the search bar to find `pg.enable_ha_replica_dns`, and set it to **Enabled**. +1. Use the search bar to find `enable_ha_replica_dns`, and set it to **Enabled**. 1. Click **Save configuration**. @@ -152,7 +152,7 @@ You can disable reads failover to the primary at any time. service. 1. Go to service > **Advance configuration**. 1. Click **Configure** > **Add configuration option**. -1. Use the search bar to find `pg.enable_ha_replica_dns`, and set it to **Disabled**. +1. Use the search bar to find `enable_ha_replica_dns`, and set it to **Disabled**. 1. Click **Save configuration**. From e36b8c04777f91e875944273fd812c0f2b91a780 Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:06:47 +0100 Subject: [PATCH 05/14] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- .../postgresql/howto/pg-reads-failover-to-primary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index a970b39c9..a82d0f961 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -56,7 +56,7 @@ Aiven Provider for Terraform. 1. In the [Aiven Console](https://console.aiven.io/), open your Aiven for PostgreSQL® service. -1. Go to service > **Advance configuration**. +1. Go to service > **Advanced configuration**. 1. Click **Configure** > **Add configuration option**. 1. Use the search bar to find `enable_ha_replica_dns`, and set it to **Enabled**. 1. Click **Save configuration**. @@ -150,7 +150,7 @@ You can disable reads failover to the primary at any time. 1. In the [Aiven Console](https://console.aiven.io/), open your Aiven for PostgreSQL® service. -1. Go to service > **Advance configuration**. +1. Go to service > **Advanced configuration**. 1. Click **Configure** > **Add configuration option**. 1. Use the search bar to find `enable_ha_replica_dns`, and set it to **Disabled**. 1. Click **Save configuration**. @@ -169,7 +169,7 @@ aiven service update SERVICE_NAME -c enable_ha_replica_dns=false Call the [ServiceUpdate endpoint](https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate) -to set the `enable_ha_replica_dns` configuration to `true`: +to set the `enable_ha_replica_dns` configuration to `false`: ```bash {8} curl --request PUT \ From d9c9a14d93f90aa7f7822f4593ec032409e1738f Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:13:40 +0100 Subject: [PATCH 06/14] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/postgresql/howto/pg-reads-failover-to-primary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index a82d0f961..71b28a953 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -81,7 +81,7 @@ to set the `enable_ha_replica_dns` configuration to `true`: curl --request PUT \ --url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \ --header 'Authorization: Bearer BEARER_TOKEN' \ ---header 'content-type: application json' \ +--header 'content-type: application/json' \ --data '{ "user_config": { From df08856d4fbad60fce8f3d361cf235065a33eff0 Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:15:42 +0100 Subject: [PATCH 07/14] Update pg-reads-failover-to-primary.md Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/postgresql/howto/pg-reads-failover-to-primary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 71b28a953..4a82fb3f9 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -175,7 +175,7 @@ to set the `enable_ha_replica_dns` configuration to `false`: curl --request PUT \ --url https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME \ --header 'Authorization: Bearer BEARER_TOKEN' \ ---header 'content-type: application json' \ +--header 'content-type: application/json' \ --data '{ "user_config": { From 01b718d8cf1189dc8aa1474487e4d48f55e11b3e Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:27:33 +0100 Subject: [PATCH 08/14] Update docs/products/postgresql/howto/pg-reads-failover-to-primary.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/postgresql/howto/pg-reads-failover-to-primary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 4a82fb3f9..5a40af04b 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -7,7 +7,7 @@ limited: true import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import ConsoleIcon from "@site/src/components/ConsoleIcons"; -import ConsoleLabel from "@site/src/components/ConsoleIcons"; +import ConsoleLabel from "@site/src/components/ConsoleLabel"; Enable automatic failover for your Aiven for PostgreSQL® read workloads to ensure uninterrupted access when standby nodes are unavailable. From eb7395e6a5a205068eeb095ab59534d685185656 Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:39:15 +0100 Subject: [PATCH 09/14] Remove unused ConsoleIcon import from documentation Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/postgresql/howto/pg-reads-failover-to-primary.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 5a40af04b..e33259ce3 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -6,7 +6,6 @@ limited: true import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import ConsoleIcon from "@site/src/components/ConsoleIcons"; import ConsoleLabel from "@site/src/components/ConsoleLabel"; Enable automatic failover for your Aiven for PostgreSQL® read workloads to ensure uninterrupted access when standby nodes are unavailable. From 0685ac8dd288768ac99645ce7c4d50d48dfd17f2 Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:48:55 +0100 Subject: [PATCH 10/14] Update docs/products/postgresql/howto/pg-reads-failover-to-primary.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- .../postgresql/howto/pg-reads-failover-to-primary.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index e33259ce3..98cadb771 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -44,9 +44,10 @@ Aiven Provider for Terraform. - [Aiven API](/docs/tools/api) - [Aiven Provider for Terraform](/docs/tools/terraform) - [Aiven Operator for Kubernetes®](/docs/tools/kubernetes) -- During a failover to primary, read-only traffic is served by the primary. Ensure your - application can tolerate reads from the primary if it assumes read-after-write or - specific consistency behavior. +- During a failover to primary, read-only traffic is served by the primary. This means: + - If your application expects eventual consistency from replicas, it will temporarily receive strong consistency from the primary. + - If your application relies on read-after-write consistency, failover to the primary will maintain this guarantee, but switching back to replicas may reintroduce replication lag. + - Ensure your application can tolerate these changes in consistency behavior during failover events. ### Use your preferred tool From 29eae3fca3d49723782616b31468bd1e36eb7eab Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 12:53:46 +0100 Subject: [PATCH 11/14] Update pg-reads-failover-to-primary.md Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/postgresql/howto/pg-reads-failover-to-primary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 98cadb771..482e0c96c 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -6,7 +6,7 @@ limited: true import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import ConsoleLabel from "@site/src/components/ConsoleLabel"; +import ConsoleLabel from "@site/src/components/ConsoleIcons"; Enable automatic failover for your Aiven for PostgreSQL® read workloads to ensure uninterrupted access when standby nodes are unavailable. From 0c9d0562f87ec6e8db3c0e76cce937f3d76c60e3 Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:18:54 +0100 Subject: [PATCH 12/14] Update docs/products/postgresql/howto/pg-reads-failover-to-primary.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- .../postgresql/howto/pg-reads-failover-to-primary.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index 482e0c96c..a232895e1 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -139,8 +139,11 @@ spec: 1. Point your read-only clients to this URI to benefit from automatic failover without changing application logic. -Existing connections to replicas may fail during an outage. New connections using the HA replica DNS continue to succeed. +:::warning +**Important:** Existing connections to replicas may fail during an outage. New connections using the HA replica DNS continue to succeed. +To ensure application reliability, implement connection retry logic so your clients can reconnect automatically if a replica connection is interrupted. +::: ## Disable the feature You can disable reads failover to the primary at any time. From f793df7ba9efcce17224202bbb990e412cedaeba Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:20:40 +0100 Subject: [PATCH 13/14] Revise failover warning in PostgreSQL docs Updated warning section for clarity and formatting. Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- .../postgresql/howto/pg-reads-failover-to-primary.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index a232895e1..a9da9de16 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -139,11 +139,12 @@ spec: 1. Point your read-only clients to this URI to benefit from automatic failover without changing application logic. -:::warning -**Important:** Existing connections to replicas may fail during an outage. New connections using the HA replica DNS continue to succeed. - -To ensure application reliability, implement connection retry logic so your clients can reconnect automatically if a replica connection is interrupted. +:::important +Existing connections to replicas may fail during an outage. New connections using the HA +replica DNS continue to succeed.To ensure application reliability, implement connection +retry logic so your clients can reconnect automatically if a replica connection is interrupted. ::: + ## Disable the feature You can disable reads failover to the primary at any time. From 173a1808676496c50263a1750f50c041c211bd9c Mon Sep 17 00:00:00 2001 From: dorota <114921900+wojcik-dorota@users.noreply.github.com> Date: Tue, 4 Nov 2025 13:26:10 +0100 Subject: [PATCH 14/14] Update docs/products/postgresql/howto/pg-reads-failover-to-primary.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: dorota <114921900+wojcik-dorota@users.noreply.github.com> --- docs/products/postgresql/howto/pg-reads-failover-to-primary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md index a9da9de16..77f0f0272 100644 --- a/docs/products/postgresql/howto/pg-reads-failover-to-primary.md +++ b/docs/products/postgresql/howto/pg-reads-failover-to-primary.md @@ -141,7 +141,7 @@ spec: :::important Existing connections to replicas may fail during an outage. New connections using the HA -replica DNS continue to succeed.To ensure application reliability, implement connection +replica DNS continue to succeed. To ensure application reliability, implement connection retry logic so your clients can reconnect automatically if a replica connection is interrupted. :::