> ## 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. # MariaDB read-only replication > Configure and access read-only MariaDB replicas to ease the load on a primary database. > [!NOTE] > > Horizontal autoscaling for replicas > You can configure horizontal autoscaling for `mariadb-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 (e.g. `database-readonly`). > * 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 MariaDB 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. ### Read-only vs. external replicas Read-only replicas are used primarily to improve application performance by distributing database read requests from read-heavy applications. Other common use cases for read-only replicas include: * Cross-region backup: Replicating data to different geographical regions * Data warehousing: Extracting data from production to analytics projects [External replicas](https://developer.upsun.com/docs/add-services/mysql/mysql-replication.md) reside on remote servers and have different use cases, including disaster recovery. ### Replica scope and sharing services MariaDB 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 MariaDB 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 MariaDB version](https://developer.upsun.com/docs/add-services/mysql#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: mariadb:\ configuration: schemas: \- main endpoints: main: default\_schema: main privileges: main: admin replicator: privileges: main: replication db-replica1: type: mariadb-replica:\ configuration: schemas: \- main endpoints: main: default\_schema: main privileges: main: admin relationships: primary: db:replicator # Do not change the name 'primary'. The service expects to receive this name. db-replica2: type: mariadb-replica:\ configuration: schemas: \- main endpoints: main: default\_schema: main privileges: main: admin 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 MariaDB version**. > Mismatched versions between `mariadb` and `mariadb-replica` prevent replication from working. ### How it works Using the sample code fragment above: 1. The primary service (`db`) defines an additional `replicator` endpoint, granting the `replication` privilege. This enables a replica to connect and continuously replicate data from the primary database. ```yaml theme={null} replicator: privileges: main: replication ``` 2. The replica services (`db-replica1` and `db-replica2`) use the `mariadb-replica` image type and connect back to the primary database service through the primary relationship. This establishes a replication link from `db` (the source) to `db-replica` (the target). ```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. Define a new relationship in 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 database: service: db endpoint: main database-readonly: 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.