Skip to main content

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) or by using the CLI.
To learn more, see Autoscaling.
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

  • 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 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.
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.
  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.
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:
.upsun/config.yaml
If your application’s performance is still not what you expect, you can configure additional replicas as described above.
Last modified on July 15, 2026