RadiatorDB Installation

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.

During configuration validation, RadiatorDB connects first to the postgres maintenance database. It then creates the configured database when needed, connects to that database, and creates or updates the schema. Incorrect network, authentication, privilege, or replication settings therefore cause configuration deployment to fail.

The connections block keeps 16 connections ready, permits up to 256 connections, and closes connections above the minimum after 30 minutes of idle time. Together with PostgreSQL max_connections = 500, this is a starting point for one production Radiator process and one RadiatorDB backend. Without this block, min defaults to 0, max defaults to 16, and idle-timeout defaults to 5m. The min setting controls the warm connection pool. It does not disable the connections required for configuration validation and database initialization.

Size max_connections for the complete deployment. For each PostgreSQL node, add the max values of every RadiatorDB server pool in every Radiator process that can connect to that node. Then reserve connections for logical replication, configuration deployment, monitoring, administration, and failover. For example, two Radiator processes with a maximum pool of 1,024 connections each require more than 2,048 PostgreSQL connections. A limit of 2,200 allows a small operational reserve.

Higher connection limits increase PostgreSQL memory and process overhead. Verify the setting against the database host capacity and expected concurrency. Increase the pool only when workload measurements show that requests wait for database connections.

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. Radiator writes this entry only after it connects to the configured PostgreSQL server, creates the database when needed, applies the RadiatorDB schema, and loads all other configuration objects.

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 restart or log check fails, inspect the complete server log. Verify the PostgreSQL address, credentials, privileges, pg_hba.conf, and logical replication settings before retrying.

This deployment does not require a collection block or a management user. RadiatorDB initializes the PostgreSQL database and its internal schema with an empty collection list. Add collections and management access only 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. Starting another Radiator process with the same configuration is safe because setup is idempotent.

RadiatorDB uses a static topology while Radiator runs. Add, remove, or change nodes in every Radiator configuration, then restart all Radiator processes.

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. RadiatorDB connects to both PostgreSQL nodes and establishes bidirectional replication. After that deployment succeeds, 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 Management UI navigation.

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