Database Replication

ServerPlane supports streaming replication for MariaDB and PostgreSQL databases. Replication creates a real-time, read-only copy of your database on a separate server.

Why Use Replication?

How It Works

MariaDB Replication

ServerPlane uses binary log (binlog) replication, the standard MariaDB replication method:

1. The primary server enables binary logging and records all write operations
2. A replication user is created on the primary with access restricted to the replica's IP
3. The current database is exported (dumped) and transferred to the replica
4. The replica imports the dump and connects to the primary's binary log stream
5. All subsequent writes on the primary are automatically replayed on the replica in real time

PostgreSQL Replication

ServerPlane uses streaming replication with pg_basebackup:

1. The primary server is configured with wal_level = replica to enable Write-Ahead Log (WAL) streaming
2. A replication role is created on the primary
3. pg_basebackup copies the entire database cluster from the primary to the replica
4. The replica starts as a hot standby, continuously receiving and replaying WAL records from the primary

What ServerPlane Configures Automatically

You do not need to SSH into servers or edit configuration files. When you set up replication, ServerPlane handles:

• Binary logging / WAL configuration on the primary
• Replication user creation with credentials restricted to the replica's IP
• Firewall rules (UFW) to allow the replica to connect on the database port (3306 for MariaDB, 5432 for PostgreSQL)
• Initial data transfer from primary to replica
• Starting and verifying the replication stream
• Ongoing lag monitoring (checked every minute)

Setting Up Replication

1. Navigate to Databases and open the database you want to replicate
2. Click the Replication tab (available for MariaDB and PostgreSQL databases only)
3. Select a Replica Server from the dropdown — this must be a different server in the same team
4. Click Setup Replication

The setup process takes a few minutes depending on database size. You can monitor the status in the Replication tab:

The Replica Is Read-Only

The most important thing to understand about replication:

The replica database is read-only. All writes must go to the primary.

If your application tries to write to the replica, the query will fail. This is enforced at the database level.

How to Use the Replica for Reads

To benefit from replication, your application needs to send read queries to the replica and write queries to the primary. This is called read/write splitting.

Laravel:

Laravel has built-in support for read/write database connections. In your config/database.php:

'pgsql' => [
    'read' => [
        'host' => ['REPLICA_IP_ADDRESS'],
    ],
    'write' => [
        'host' => ['PRIMARY_IP_ADDRESS'],
    ],
    'driver' => 'pgsql',
    'database' => 'your_database',
    'username' => 'your_user',
    'password' => 'your_password',
    // ...
],

Laravel will automatically route SELECT queries to the read connection and INSERT, UPDATE, DELETE queries to the write connection.

WordPress:

Use the HyperDB plugin, which supports read/write splitting:

// In db-config.php
$wpdb->add_database([
    'host' => 'REPLICA_IP_ADDRESS',
    'user' => 'db_user',
    'password' => 'db_password',
    'name' => 'db_name',
    'read' => 1,
    'write' => 0,
]);

Django:

Use Django's database routers to route reads to the replica:

# settings.py
DATABASES = {
    'default': {
        'HOST': 'PRIMARY_IP_ADDRESS',
        # ...
    },
    'replica': {
        'HOST': 'REPLICA_IP_ADDRESS',
        # ...
    },
}

Node.js:

Most ORMs (Sequelize, Knex, Prisma) support read replicas. For example, with Sequelize:

const sequelize = new Sequelize('database', 'user', 'password', {
  replication: {
    read: [{ host: 'REPLICA_IP_ADDRESS' }],
    write: { host: 'PRIMARY_IP_ADDRESS' },
  },
});

If you do not configure read/write splitting, the replica still serves as a hot standby for failover and a safe backup source.

Monitoring Replication Lag

Replication lag is the delay between a write on the primary and when it appears on the replica. ServerPlane checks lag every minute and displays it in the Replication tab.

Promoting a Replica

If your primary server fails, you can promote the replica to a standalone database:

1. Go to the Replication tab of the database
2. Click Promote next to the replica

This breaks the replication link permanently. The replica becomes an independent, writable database. You will need to update your application's database host to point to the promoted server's IP address.

Promotion is a one-way operation. To re-establish replication after promotion, you must set up a new replica from scratch.

Tearing Down Replication

To remove a replica:

1. Go to the Replication tab
2. Click Teardown next to the replica you want to remove

This stops the replication stream, removes the replication user from the primary, closes the firewall rules, and deletes the replication configuration. The replica server's database engine is not uninstalled — only the replication link is removed.

Replication and Load Balancing

If you are using load balancing for your application, all backend servers connect to the same primary database. As you add more backends, the database receives more connections and query load.

Database replication can help in this scenario:

• Offload reads: Configure your application to send read queries to the replica, reducing pressure on the primary
• Failover safety: If the primary database server has issues, you have a replica ready to promote
• Monitoring: Keep an eye on replication lag — if it increases after adding backends, the primary may need more resources

See the Load Balancing guide for more on preparing your application for multi-server deployments.