RadiatorDB

Overview

RadiatorDB is built into Radiator server. It is a document database like MongoDB but built on top of PostgreSQL, so it requires access to one or more PostgreSQL instances.

Feature highlights

• Multi-master support
  • Configure multiple PostgreSQL instances to get multimaster replication support
  • Write to any single instance and changes replicate automatically to all other instances
  • Multimaster write conflicts are handled using a simple last-writer-wins strategy
  • Use for high availability or horizontal read scaling
• JSON REST API for database access with role-based access control
• Database UI
  • Define database UIs for create, read, update, and delete operations
  • Choose UI widgets (text, password, number etc.) for each field
  • Role-based access control
• Revision history and audit log
  • Each database insert, update, or delete generates a revision history entry with information about who made the change
  • Use the built-in UI to view the revision history and restore items as needed
• Automatically expiring documents
  • Useful for session stores that should clear automatically
• Automatic SQL schema management
  • RadiatorDB only needs write access to a PostgreSQL database and it automatically sets up the required SQL tables and replication configurations

Concepts

RadiatorDB stores collections of free-form JSON documents. Each document is keyed by a multivalue key that must be unique within its collection. The documents can be retrieved using the full key, part of the key, or using the JSON data itself.

The documents look like this:

{
  "collection": "users",
  "key": ["mikem", "example.com"],
  "doc": {
    "username": "mikem",
    "email": "mikem@example.com",
    "password": "$argon2i$v=19$m=16,t=2,p=1$M0cyOUZCazI2bWlibkhSdQ$dL2WSQcnvgCbTq+0YfunEA"
  }
}

Define a Collection

Define each collection inside its radiatordb backend. The collection configuration sets the document key, access roles, fields, and Management UI form. The underlying SQL schema does not define the document fields.

backends {
    radiatordb "mydb" {
        collection "users" {
            roles {
                read "support";
                write "ops";
            }

            name "Users";
            description "WiFi users and support-managed credentials";

            # Build the multivalue key from these fields
            key {
                field {
                    name "Username";
                    type text;
                }

                field {
                    name "Email";
                    type text;
                }
            }

            # Other fields in the doc content

            field "passwordHash" {
                name "Password Hash";
                type password;
                required true;
            }

            field "groups" {
                name "Groups";
                type list;

                field "group" {
                    name "Group";
                    type text;
                }
            }
        }
    }
}

This configuration generates a Management UI form that validates documents before inserting them into RadiatorDB.

See the collection configuration reference for all collection, key, field, role, and expiration options.

Add Management UI Navigation

Add sidebar links after you configure the RadiatorDB backend and collections. The landing page lists every database and collection that the authenticated user can access. A database-specific link is optional:

ui {
    sidebar {
        section "Main";
        item "RadiatorDB" {
            url "/radiatordb";
            icon "Storage";
        }
    }

    sidebar {
        section "RadiatorDB";
        item "mydb" {
            url "/radiatordb/database?dbName=mydb";
            icon "Database";
        }
    }
}

Set dbName to the exact, case-sensitive name of the radiatordb backend that contains the collection definitions. If separate RadiatorDB backends define queries and collections for the same PostgreSQL database, use the name of the backend that defines the collections. Restart Radiator or deploy the configuration to apply the sidebar change.

Configure Management User Access

Configure management access after you define at least one collection. This step is not required to deploy the PostgreSQL database or initialize RadiatorDB.

Use your existing management authentication policy to authenticate RadiatorDB users. Management users can come from SQL, LDAP, HTTP, a JSON file, or another backend supported by the AAA policy. See Management Authentication Policies for configuration examples.

Set user.radiatordb_role in the policy from backend data or policy rules. The role names must match the read or write roles in each collection's roles block. Write access also grants read access. A user without a matching role cannot access that collection through Management UI or REST API.

RadiatorDB roles are separate from the management API privilege in user.privilege. See RadiatorDB REST API access control for role-mapping examples and detailed access rules.

What RadiatorDB is not

RadiatorDB should not be considered an SQL database even though it is built on top of PostgreSQL. The database must not be written to using SQL as it will break constraints RadiatorDB assumes. All writes have to go through the REST API or the radconf backends in execution pipelines.

For full details see the RadiatorDB backend documentation.