Configuration File

The Portabase Agent needs to know where your databases are located to connect to them. This configuration is done via a file (commonly named databases.json) mounted into the Docker container.

You can manage this file in two ways:

Via the CLI (command portabase db add): recommended, as it generates IDs and validates the syntax for you.
Manually: useful for automation (Ansible, Terraform) or when you prefer editing files by hand.

The agent supports two formats: JSON (default) and TOML (more human-friendly).

File structure

You can define multiple databases in a single file. This allows a single agent to back up, for example, both your staging and production environments.

Standard format used by the CLI.

databases.json

{
  "databases": [
    {
      "name": "my-site-prod",
      "databases": "my-site-prod",
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "username": "admin_prod",
      "password": "super_secure_password",
      "generatedId": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "name": "my-site-dev",
      "databases": "my-site-dev",
      "type": "mysql",
      "host": "192.168.1.50",
      "port": 3306,
      "username": "root",
      "password": "dev_password",
      "generatedId": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

A format often preferred for its human readability.

databases.toml

[[databases]]
name = "my-site-prod"
type = "postgresql"
host = "localhost"
port = 5432
username = "admin_prod"
password = "super_secure_password"
generatedId = "550e8400-e29b-41d4-a716-446655440000"

[[databases]]
name = "my-site-dev"
type = "mysql"
host = "192.168.1.50"
port = 3306
username = "root"
password = "dev_password"
generatedId = "123e4567-e89b-12d3-a456-426614174000"

Field reference

Here is the meaning of each configuration parameter:

Field	Required	Description
`name`	Yes	The database name to back up (e.g. "prod_api").
`type`	Yes	Engine type: `postgresql`, `mysql`, `mariadb` (use `mysql` for MariaDB).
`host`	Yes	Host IP or name. If the agent runs on the same server, use `localhost` (with `extra_hosts` in Docker) or the local IP.
`port`	Yes	Listening port (`5432` for Postgres, `3306` for MySQL).
`username`	Yes	User with read/dump permissions.
`password`	Yes	Password for that user.
`generatedId`	Yes	A unique UUID v4 identifier.

The `generatedId` rule

Each database must have a unique ID. This ID lets the Dashboard recognize a database's backup history even if you rename it.

Attention

If you create this file manually, you must generate a valid UUID v4. Do not invent a simple random string.

How to generate a UUID:

Terminal: uuidgen.
Python: python3 -c "import uuid; print(uuid.uuid4())".
Online: https://www.uuidgenerator.net/.

Docker mount

If you edit the file manually, ensure it's mounted into the agent container.

docker-compose.yml

services:
  agent:
    # ...
    volumes:
      - ./databases.json:/app/src/data/config/config.json

After any manual change, restart the agent so it picks up the new configuration: docker compose restart agent

Configuration File

File structure

Field reference

The generatedId rule

Docker mount

On this page

The `generatedId` rule