Aiven for PostgreSQL® reads failover to the primary Limited availability

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.

How it works

• 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 manage reads failover to the primary from the Aiven Console, CLI, API, or using Aiven Provider for Terraform.

Prerequisites

• Aiven for PostgreSQL service on a Business or Premium plan (see how to change your plan)
• Tool for managing the feature:
  • Aiven Console
  • Aiven CLI
  • Aiven API
  • Aiven Provider for Terraform
  • Aiven Operator for Kubernetes®
• 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

Console

1. In the Aiven Console, open your Aiven for PostgreSQL® service.
2. Go to service Service settings > Advanced configuration.
3. Click Configure > Add configuration option.
4. Use the search bar to find enable_ha_replica_dns, and set it to Enabled.
5. Click Save configuration.

CLI

Run

aiven service update SERVICE_NAME -c enable_ha_replica_dns=true

API

Call the ServiceUpdate endpoint 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' \
--data
  '{
    "user_config": {
      "enable_ha_replica_dns": true
      }
  }'

Terraform

Add or update your Terraform resource for the Aiven for PostgreSQL service:

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
  }
}

Kubernetes

Add or update your Aiven Service custom resource manifest:

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

Use the HA-replica-DNS endpoint

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.
2. Point your read-only clients to this URI to benefit from automatic failover without changing application logic.

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.

Console

1. In the Aiven Console, open your Aiven for PostgreSQL® service.
2. Go to service Service settings > Advanced configuration.
3. Click Configure > Add configuration option.
4. Use the search bar to find enable_ha_replica_dns, and set it to Disabled.
5. Click Save configuration.

CLI

Run

aiven service update SERVICE_NAME -c enable_ha_replica_dns=false

API

Call the ServiceUpdate endpoint 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' \
--data
  '{
    "user_config": {
      "enable_ha_replica_dns": false
      }
  }'

Terraform

Add or update your Terraform resource for the Aiven for PostgreSQL service:

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
  }
}

Kubernetes

Add or update your Aiven Service custom resource manifest:

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