> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # PostgreSQL read-only replication > Configure and access read-only PostgreSQL replicas to ease the load on a primary database. > [!NOTE] > > Horizontal autoscaling for replicas > You can configure horizontal autoscaling for `postgresql-replica` services. The platform automatically adjusts the number of running replicas based on CPU and/or memory thresholds you define — no redeployment required. > > * Your application is responsible for directing read queries to the replica connection string, available via `PLATFORM_RELATIONSHIPS` under the replica relationship name (for example, `database-readonly` as defined in your app configuration). > * Configure autoscaling in the [Console (on the Configure resources tab)](https://developer.upsun.com/docs/manage-resources/autoscaling.md#enable-autoscaling) or by using the [CLI](https://developer.upsun.com/cli/install.md). > > To learn more, see [Autoscaling](https://developer.upsun.com/docs/manage-resources/autoscaling.md). You can improve the performance of read-heavy applications by defining read-only replicas of your PostgreSQL database and then connecting your applications to those replicas. Examples of read-heavy applications include: * Listing pages or dashboards * Reporting or analytics jobs * Background jobs that frequently query data > [!NOTE] > > #### Note > > * **Replication is asynchronous**: Delays of a few milliseconds might occur between writes on the primary database and reads on the replica database. > * **Replicas are read-only**: This restriction ensures data consistency and integrity. Attempts to modify data will result in an SQL error. ### Replica scope and sharing services PostgreSQL services (which provide access to databases and replicas) defined in a project cannot be accessed by or shared with applications in other projects. ## 1. Configure the primary and replica services The following code fragment defines two PostgreSQL services: a primary and a replica. You can use this fragment as a template by copying it into your `.upsun/config.yaml` file. Be sure to: * Replace `VERSION` with the [supported PostgreSQL version](https://developer.upsun.com/docs/add-services/postgresql#supported-versions) that you need. * **Important:** Use `replicator` as the endpoint name when you define the replica service. This is a special endpoint name that the replica service uses to connect to the database. services: db: type: postgresql:\ configuration: extensions: \- postgis endpoints: replicator: replication: true db-replica1: type: postgresql-replica:\ configuration: endpoints: postgresql: default\_database: main extensions: \- postgis relationships: primary: db:replicator # Do not change the name 'primary'. The service expects to receive this name. db-replica2: type: postgresql-replica:\ configuration: endpoints: postgresql: default\_database: main extensions: \- postgis relationships: primary: db:replicator # Do not change the name 'primary'. The service expects to receive this name. > [!WARNING] > > The primary and replica services must use the **same PostgreSQL version**. Mismatched versions between `postgresql` and `postgresql-replica` prevent replication from working. ### How it works Using the sample code fragment above: 1. After you define the replicator endpoints, the primary service creates a `replicator` user that has permission to replicate the database. You must specify `replicator` as the endpoint name, as described at the start of this topic. ```yaml theme={null} endpoints: replicator: replication: true ``` 2. In the replica services (in this example, `db-replica1` and `db-replica2`), defining the relationship `primary: db:replicator` ensures that the service can connect to the primary database as the `replicator` user. ```yaml theme={null} relationships: primary: db:replicator ``` The `db-replica1` and `db-replica2` replica services continuously stream data from the primary endpoint, maintaining a read-only copy of the primary database content. Write operations are not permitted on the replicas. ## 2. Define the relationship between the application and the replicas Even if your application won't access the replication endpoint, you must expose the endpoint to an application as a relationship so that you can connect to it over SSH. Add a new relationship to your application container, as shown below: ```yaml .upsun/config.yaml theme={null} applications: myapp: #... other properties # Relationships enable an app container's access to a service. relationships: # More information: https://developer.upsun.com/docs/configure-apps/image-properties/relationships db: service: db endpoint: main db-replica1: service: db-replica1 endpoint: replicator ``` If your application's performance is still not what you expect, you can configure additional replicas as described above. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.