Skip to main content

Manage read replicas

Beta

Lakebase Postgres (Autoscaling Beta) is the next version of Lakebase, available for evaluation only. For production workloads, use Lakebase Public Preview. See choosing between versions to understand which version is right for you.

This guide walks you through creating and managing read replicas for your database projects. Read replicas segregate read-only work from your production database operations, with applications ranging from horizontal scaling to analytics workloads. For detailed information about read replica architecture and use cases, see Read replicas.

The steps for creating, configuring, and connecting to a read replica are the same regardless of your use case. You can create one or more read replicas for any branch in your database project and configure the compute size allocated to each. Autoscaling and scale-to-zero features are also supported, providing you with control over read replica compute usage.

Prerequisites​

Create a read replica​

To create a read replica:

  1. In the Lakebase App, navigate to your database project, branch, and the Computes tab.
  2. Click Add Read Replica.
  3. Enter a name for your read replica, configure the compute settings (autoscaling range and scale-to-zero behavior), and click Add.

Add read replica drawer

note

The compute size configuration determines the processing power of your database. Learn more: Manage computes

Your read replica is provisioned in a few seconds and appears on the Computes tab for the branch.

Region support​

Lakebase supports creating read replicas in the same region as your database project. Cross-region read replicas are not supported.

Connect to a read replica​

Connecting to a read replica follows the same process as connecting to your primary read-write compute, except you select a read replica compute when obtaining your connection information.

To get connection information for a read replica:

  1. In the Lakebase App, click Connect on your database project dashboard.
  2. Select the branch, database, role, and the read replica compute from the Compute dropdown, then copy the provided connection string.

You can connect using either an OAuth Postgres role, just as you would with your primary read-write compute.

important

Write operations are not permitted on read replica connections. Attempting to execute write operations will result in an error.

For complete information about authentication methods and connection options, see Connect to your database project.

View read replicas​

To view read replicas for a branch, navigate to your database project in the Lakebase App, select a branch from the Branches page, and view the Computes tab where all read replica computes are listed.

Edit a read replica​

You can edit a read replica to change the compute size or scale-to-zero configuration.

To edit a read replica:

  1. Navigate to your branch's Computes tab in the Lakebase App.
  2. Find the read replica, click Edit, update the compute settings, and click Save.

Learn more: Manage computes

Delete a read replica​

Deleting a read replica is a permanent action. However, you can quickly create a new read replica if you need one.

To delete a read replica:

  1. Navigate to your branch's Computes tab in the Lakebase App.
  2. Find the read replica, click Edit, Delete, and confirm the deletion.

Read replica compute setting synchronization​

For Lakebase read replicas, certain Postgres settings should not have lower values than your primary read-write compute. For this reason, the following settings on read replica computes are synchronized with the settings on the primary read-write compute when the read replica compute is started:

  • max_connections
  • max_prepared_transactions
  • max_locks_per_transaction
  • max_wal_senders
  • max_worker_processes

No user action is required. The settings are synchronized automatically when you create a read replica. However, if you change the compute size configuration on the primary read-write compute, you need to restart your read replica computes to ensure that settings remain synchronized. See Troubleshoot replication delay for more information.

Troubleshoot replication delay​

If your read replicas are falling behind, follow these steps to diagnose and resolve the issue:

Verify configuration alignment​

If replication lag is detected, ensure that the configurations for the primary and read replica computes are aligned. Specifically, confirm that the following parameters match between your primary compute and read replica compute:

  • max_connections
  • max_prepared_transactions
  • max_locks_per_transaction
  • max_wal_senders
  • max_worker_processes

You can run the following query on both your primary read-write compute and read replica compute using the Lakebase SQL editor or a SQL client like psql:

SQL
SELECT name, setting
FROM pg_settings
WHERE name IN (
  'max_connections',
  'max_prepared_transactions',
  'max_locks_per_transaction',
  'max_wal_senders',
  'max_worker_processes'
);

Compare the results from both computes to identify any misaligned settings.

Restart read replica computes​

If the configurations are not aligned, restart your read replica computes to automatically update their settings. Navigate to your branch's Computes tab, find the read replica, and click Edit, then Restart.

note

When increasing the size of your primary read-write compute, always restart associated read replicas to ensure their configurations remain aligned.

Next steps​

Last updated on