Radiator Server Documentation — v10.34.2

RadiatorDB Installation

This guide covers single-node and multi-node RadiatorDB deployments with PostgreSQL.

Use PostgreSQL instances dedicated to RadiatorDB. Do not place RadiatorDB databases on shared PostgreSQL servers or clusters. Dedicated instances provide the required control over security, performance, and replication settings.

Prerequisites

  • A host for Radiator. See Radiator sizing.

  • A dedicated PostgreSQL 18 or later instance. For a small installation, the PostgreSQL instance and Radiator can run on the same host. See RadiatorDB sizing.

  • TCP port 5432 connectivity from each Radiator host to each PostgreSQL host. Multi-node deployments also require this connectivity between PostgreSQL hosts.

  • Firewall rules, network groups, or a VPN that restrict PostgreSQL access to the RadiatorDB deployment hosts.

Step 1: Install Radiator

Install Radiator on the first host following the Basic Installation guide. RadiatorDB functionality requires no additional Radiator packages. You must install PostgreSQL separately as described in Step 2.

Step 2: Install and Configure PostgreSQL

On each database host, install PostgreSQL 18 from the official PostgreSQL packages or repositories. Do not use a PostgreSQL instance that serves other applications.

Create a dedicated PostgreSQL superuser. The command prompts for the password without placing it in shell history:

sudo -u postgres createuser --superuser --pwprompt radiatordb_admin

RadiatorDB uses this account to create databases, schemas, publications, subscriptions, and replication slots. More restrictive privilege configurations require extensive PostgreSQL-specific setup and are not supported.

Configure the following PostgreSQL server settings. For a package installation, set them in postgresql.conf. For a container, pass the same settings as postgres -c name=value startup options. Use the method supported by your PostgreSQL deployment:

listen_addresses = '192.168.1.20'
wal_level = logical
max_connections = 500

Replace 192.168.1.20 with an address of the current PostgreSQL host. PostgreSQL uses listen_addresses to select the local network interfaces that accept connections. wal_level = logical enables the logical replication used by RadiatorDB. The max_connections = 500 value supports the connection pool shown in Step 3 for one Radiator process and one RadiatorDB backend. Recalculate this value for the complete deployment before production use.

PostgreSQL 18 defaults for the other logical replication settings support a basic two-node deployment. For larger deployments, size max_replication_slots, max_wal_senders, max_active_replication_origins, max_logical_replication_workers, and max_worker_processes for the number of nodes and concurrent initial table synchronizations. See the PostgreSQL logical replication settings.

Configure PostgreSQL host-based authentication to allow the radiatordb_admin account from the Radiator host. Package installations commonly use pg_hba.conf. Container and managed deployments can generate equivalent rules. Do not use trust authentication in production. Replace 192.168.1.10 with the actual Radiator host address:

host    all    radiatordb_admin    192.168.1.10/32    scram-sha-256

Use all on a dedicated PostgreSQL instance so RadiatorDB can connect to the postgres maintenance database and create any configured RadiatorDB database. If local policy does not allow all, add one entry for postgres and one entry for every configured RadiatorDB database:

host    postgres      radiatordb_admin    192.168.1.10/32    scram-sha-256
host    radiatordb    radiatordb_admin    192.168.1.10/32    scram-sha-256

Repeat the pg_hba.conf entry for every Radiator host that connects to this PostgreSQL instance. The multi-master setup below describes the additional entries required for peer PostgreSQL hosts.

Restart PostgreSQL to apply these settings:

sudo systemctl restart postgresql

Restrict TCP port 5432 with a firewall, network group, or VPN. Permit only the Radiator and PostgreSQL hosts that participate in this RadiatorDB deployment. pg_hba.conf controls PostgreSQL authentication but does not replace a firewall.

Step 3: Configure RadiatorDB Connection

On the Radiator host, create the file 20_radiatordb.radconf in the Radiator configuration directory (typically /var/lib/radiator/):

[!WARNING] The connection limits below are starting values for one Radiator process and one RadiatorDB backend. Calculate new limits before you add Radiator processes or backends. Each process can open up to the configured max connections to this PostgreSQL node.

backends {
    radiatordb "mydb" {
        server "pg1" {
            host "192.168.1.20";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password env.RADIATORDB_POSTGRES_PASSWORD;
            connections {
                min 16;
                max 256;
                idle_timeout 30m;
            }
        }
    }
}

Replace 192.168.1.20 with the IP address of your PostgreSQL host.

Set RADIATORDB_POSTGRES_PASSWORD to the password for radiatordb_admin before you validate or deploy the configuration. Radiator reports a configuration error when the variable is missing.

For a systemd package, add the variable to /etc/default/radiator-server on Debian or Ubuntu, or /etc/sysconfig/radiator-server on Red Hat based systems:

RADIATORDB_POSTGRES_PASSWORD=replace-with-a-strong-password

Restrict access to the environment file:

sudo chown root:root /etc/default/radiator-server
sudo chmod 600 /etc/default/radiator-server

Use the path for your operating system in these commands. For a container, supply the variable through the deployment platform's protected environment or secret configuration. See Environment Variables in Configuration.

Normal configuration deployment validates connection settings locally, then starts database setup in the background. A full configuration test connects to each configured PostgreSQL server but does not create or update database state. Incorrect network or authentication settings keep the affected node unavailable while connection probes retry. Provisioning failures stop setup and require repair followed by node removal and reprovisioning, or a Radiator Server restart.

The example keeps 16 connections ready and allows up to 256 per Radiator process. Size PostgreSQL max_connections for every Radiator process that can connect to each node, plus replication and administration. Higher limits use more PostgreSQL memory. See RadiatorDB sizing and the 10k TPS example for capacity guidance.

Step 4: Verify the Deployment

Restart Radiator with the new configuration. For a systemd installation, run:

sudo systemctl restart radiator-server.service
sudo systemctl is-active radiator-server.service
sudo tail -n 100 /var/log/radiator/radiator-server.log | grep -F "Loading configuration done"

The second command must print active. The final command must print a new Loading configuration done log entry from this restart. This entry confirms that Radiator accepted the local configuration and started background RadiatorDB setup. It does not confirm a PostgreSQL connection or completed database setup.

Radiator UI shows RadiatorDB maintenance status, including node setup, replication health, and availability, to management accounts with write or all privilege. Wait for the operational status to show OK before verifying a new complete deployment. Setup runs in the background.

For a container deployment, restart the container and search its logs for the same Loading configuration done entry. Also confirm that the container remains running.

If the operational status remains Degraded or Unavailable, inspect the node and replication relationship status and check the server log. Verify the PostgreSQL address, credentials, privileges, pg_hba.conf, and logical replication settings. Radiator retries temporary connection failures automatically. For a setup failure that requires repair, fix the cause, then remove and reprovision the node, or restart Radiator Server.

Database setup does not require a collection block or a management user. RadiatorDB initializes the PostgreSQL database and its internal schema with an empty collection list. Configure a management account to verify the deployment in Radiator UI. Add collections after the database deployment succeeds.

Multi-Master Setup

RadiatorDB supports multi-master replication with two or more dedicated PostgreSQL instances. Each Radiator process must use the same backend configuration and list every PostgreSQL node. Before you deploy the following configuration, replace 192.168.1.20 and 192.168.1.21 with the addresses of your PostgreSQL nodes. Use addresses that all Radiator and PostgreSQL hosts can reach. Do not set either host to localhost or 127.0.0.1.

backends {
    radiatordb "mydb" {
        server "node1" {
            host "192.168.1.20";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password env.RADIATORDB_POSTGRES_PASSWORD;
            connections {
                min 16;
                max 256;
                idle_timeout 30m;
            }
        }

        server "node2" {
            host "192.168.1.21";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password env.RADIATORDB_POSTGRES_PASSWORD;
            connections {
                min 16;
                max 256;
                idle_timeout 30m;
            }
        }
    }
}

One Radiator process that can reach all configured nodes creates the complete bidirectional replication mesh. Publications, subscriptions, and replication slots remain in PostgreSQL. Each initialized node can enter routing while other nodes retry. Cluster-wide maintenance remains unavailable until every configured node and edge is operational. Starting another Radiator process with the same configuration observes the same static topology. Do not run concurrent initial setup against databases whose provisioning was previously interrupted. Inspect and repair incomplete PostgreSQL resources, then remove and reprovision the node, or restart Radiator Server.

RadiatorDB uses a static topology while Radiator runs. Add, remove, or change nodes in every Radiator configuration, then restart all Radiator processes. For removing nodes and adding or removing collections later, see RadiatorDB maintenance.

Configure peer authentication

Complete Step 2 on every PostgreSQL node. Each pg_hba.conf must allow both the Radiator host addresses and the peer PostgreSQL host addresses. Add the following entries to both PostgreSQL nodes. Replace .10 and .11 with your Radiator host addresses. Replace .20 and .21 with your PostgreSQL host addresses.

host    all    radiatordb_admin    192.168.1.10/32    scram-sha-256
host    all    radiatordb_admin    192.168.1.11/32    scram-sha-256
host    all    radiatordb_admin    192.168.1.20/32    scram-sha-256
host    all    radiatordb_admin    192.168.1.21/32    scram-sha-256

PostgreSQL starts logical replication connections without the password from the Radiator configuration. Store the password in .pgpass in the PostgreSQL system account's home directory on every PostgreSQL host. This directory is commonly /var/lib/postgresql on Debian and Ubuntu, and /var/lib/pgsql on Red Hat based systems.

On node 1, add an entry for node 2. Replace the address, database, username, and password with the values from your RadiatorDB configuration:

192.168.1.21:5432:radiatordb:radiatordb_admin:replace-with-the-account-password

On node 2, add an entry for node 1 and replace the same values:

192.168.1.20:5432:radiatordb:radiatordb_admin:replace-with-the-account-password

Set the file owner and permissions on each node. The following commands use the Debian and Ubuntu path. Replace /var/lib/postgresql with the home directory of the postgres account. Red Hat based systems commonly use /var/lib/pgsql.

sudo chown postgres:postgres /var/lib/postgresql/.pgpass
sudo chmod 600 /var/lib/postgresql/.pgpass

Test the password file from each node. Replace 192.168.1.21, radiatordb, and radiatordb_admin with the peer address, database, and account for that node. The command must connect without a password prompt:

sudo -u postgres psql "host=192.168.1.21 port=5432 dbname=radiatordb user=radiatordb_admin"

See the PostgreSQL password file documentation for escaping rules and alternate locations.

Configure node addresses

Set host to an address that every Radiator and PostgreSQL host can reach. Do not use localhost or 127.0.0.1 for a multi-node deployment unless you also set replication_host to the peer-reachable address.

Deploy the shared configuration

First deploy the complete backend configuration to one Radiator host. Wait for the RadiatorDB operational status to show OK. This confirms that RadiatorDB established the configured bidirectional replication relationships. Then deploy the same backend configuration to the other Radiator hosts. You can perform this deployment without collections.

When you add collections later, deploy the same collection configuration to every Radiator host.

Writes accepted by any node replicate to the other nodes. Concurrent write conflicts use a last-writer-wins strategy.

Performance Tuning

For a measured starting profile with two PostgreSQL nodes, 10,000 read TPS, and 1,000 write TPS, see RadiatorDB PostgreSQL 10k TPS example. The example includes PostgreSQL, Linux, systemd, verification, acceptance-test, and troubleshooting guidance.

After you verify the deployment, configure these RadiatorDB PostgreSQL defaults on each server. Use postgresql.conf or the equivalent startup options for your deployment:

wal_writer_delay = 300ms
wal_writer_flush_after = 20MB

wal_writer_delay limits the maximum asynchronous-commit durability delay to approximately three times the configured value. A 300 millisecond delay keeps this window below one second. wal_writer_flush_after uses a 20 MB threshold to allow more WAL batching before the WAL writer requests a flush.

These settings apply most directly when a RadiatorDB backend uses synchronous_commit off. See synchronous_commit for the durability implications.

Restart PostgreSQL after changing these settings: sudo systemctl restart postgresql

Next Steps

Keep database deployment and application setup as separate operations. After verifying the empty database deployment:

  1. Define RadiatorDB collections.
  2. Configure management user access.
  3. Add Radiator UI navigation.

Use the RadiatorDB REST API to manage documents outside Radiator UI. See RadiatorDB Backup for export and import operations.