Working with Neon read replicas

Read replicas are supported with the Neon Pro Plan. This guide will lead you through the process of creating and managing read replicas.

The general methodology of using read replicas to segregate read-only work from your production database operations can be applied to a variety of uses cases, such as:

• Offloading analytics or reporting queries
• Distributing read requests to achieve higher throughput
• Providing read-only data access to specific users or applications who do not need to modify data
• Configuring different CPU and memory resources for each read replica for different users and applications

Regardless of the application, the steps for creating, configuring, and connecting to a read replica are the same. You can create one or more read replicas for any branch in your Neon project and configure the vCPU and memory allocated to each. Neon's Autoscaling and Auto-suspend features are also supported, providing you with control over compute usage.

Prerequisites

• A Neon Pro Plan account.
• A Neon project.

Create a read replica

Creating a read replica involves adding a read-only compute endpoint to a branch. You can add a read-only compute endpoint to any branch in your Neon project by following these steps:

1. In the Neon Console, select Branches.
2. Select the branch where your database resides.
3. Click Add compute.
4. On the Create Compute Endpoint dialog, select Read-only as the Compute type.
5. Specify the Compute size options. You can configure a Fixed Size compute with a specific amount of vCPU and RAM (the default) or enable Autoscaling and configure a minimum and maximum compute size. You can also configure the Suspend compute after a period of inactivity setting, which is the amount of idle time after which your read-only compute is automatically suspended. The default setting is 5 minutes. You can set this value up 7 days.

   note

   The compute size configuration determines the processing power of your database. More vCPU and memory means more processing power but also higher compute costs. For information about compute costs, see Billing metrics.

6. When you have finished making your selections, click Create.

In a few moments, your read-only compute is provisioned and appears in the Computes section of the Branches page. This is your read replica. The following section describes how to connect to your read replica.

Alternatively, you can create read replicas using the Neon API or Neon CLI.

API

CLI

Connect to a read replica

Connecting to a read replica is the same as connecting to any branch, except you connect via a read-only compute endpoint instead of a read-write compute endpoint. The following steps describe how to connect to your read replica with connection details obtained from the Neon Console.

1. On the Neon Dashboard, under Connection Details, select the branch, the database, and the role you want to connect with.

2. Under Compute, select a Read-only compute endpoint.

3. Select a connection string or a code example from the drop-down menu and copy it. This is the information you need to connect to the read replica from you client or application.

   A psql connection string appears similar to the following:

   If you expect a high number of connections, select Pooled connection to add the -pooler flag to the connection string or example.

   When you use a read-only connection string, you are connecting to a read replica. No write operations are permitted on this connection.

Viewing read replicas

To view read replicas for a branch, select Branches in the Neon Console, and select a branch. Under the Computes heading, the Type field identifies your read replicas. Read replicas have a R/O value instead of R/W.

Edit a read replica

You can edit your read replica to change the Compute size or Auto-suspend configuration.

To edit a read-only compute endpoint:

1. In the Neon Console, select Branches.
2. Select a branch.
3. Under Computes, identify the read-only compute endpoint you want to modify, click the compute endpoint kebab menu, and select Edit.
4. Specify your Compute size or Suspend compute after a period of inactivity changes and click Save.

Delete a read replica

Deleting a read replica is a permanent action, but you can quickly create a new read replica if you need one. To delete a read replica:

1. In the Neon Console, select Branches.
2. Select a branch.
3. Under Computes, find the read-only compute endpoint you want to delete. Read replicas have a R/O type.
4. Click the compute endpoint kebab menu, and select Delete.
5. On the confirmation dialog, click Delete.

Manage read replicas using the Neon API

In Neon, a read replica is implemented as a read-only compute endpoint. The following examples demonstrate creating and deleting read-only compute endpoints using the Neon API. The Neon API also supports get, list, edit, start, and suspend API methods. For information about those methods, refer to the Neon API reference.

Prerequisites

A Neon API request requires an API key. For information about obtaining an API key, see Create an API key. In the cURL examples below, $NEON_API_KEY is specified in place of an actual API key. You must replace this value with an actual API key when making a Neon API request.

Create a read replica with the API

The following Neon API method creates a read-only compute endpoint.

The API method appears as follows when specified in a cURL command. A compute endpoint must be associated with a branch. A branch can only have a single read-write endpoint but can have multiple read-only compute endpoints. The type attribute in the following example specifies read_only, which creates a read-only compute endpoint:

For information about obtaining the required project_id and branch_id parameters, refer to Create an endpoint, in the Neon API reference.

Delete a read replica with the API

The following Neon API method deletes the specified compute endpoint. Compute endpoints are identified by their branch_id and endpoint_id, regardless of whether they are read-write or read-only. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command.

For information about obtaining the required project_id and endpoint_id parameters, refer to Delete an endpoint, in the Neon API reference.

Need help?

Join the Neon community forum to ask questions or see what others are doing with Neon. Neon Pro Plan users can open a support ticket from the console. For more detail, see Getting Support.