Configuration File
Optionally declare your databases on the agent side, via JSON or TOML.
This file is optional
Since Dashboard 1.29.0 and Agent 1.19.0, you can add your databases directly from the dashboard, without editing any file on the server. See Adding a Database.
The Portabase Agent can also read its databases from a file (commonly named databases.json) mounted into its Docker container. Without this file, the agent only uses the databases defined in the dashboard.
You can manage this file in two ways:
- Via the CLI (command
portabase agent db add): 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": [
{
"name": "my-site-prod (readable name)",
"database": "devdb",
"type": "postgresql",
"host": "localhost",
"port": 5432,
"username": "admin_prod",
"password": "super_secure_password",
"generated_id": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "my-site-dev (readable name)",
"database": "app_dev",
"type": "mysql",
"host": "192.168.1.50",
"port": 3306,
"username": "root",
"password": "dev_password",
"generated_id": "123e4567-e89b-12d3-a456-426614174000"
}
]
}Field reference
Here is the meaning of each configuration parameter:
| Field | Required | Description |
|---|---|---|
name | Yes | The Readable name. |
database | Depends on the engine. | The database to back up (e.g. "prod_api"). |
type | Yes | Engine type: postgresql, postgresql-cluster, mysql, mariadb, mongodb, sqlite, redis, valkey, firebird, mssql, docker-volume. See the engine pages. |
host | Depends on the engine. | Host IP or name. If the agent runs on the same server, use localhost (with extra_hosts in Docker) or the local IP. |
port | Depends on the engine. | Listening port (5432 for Postgres, 3306 for MySQL). |
username | Depends on the engine. | User with read/dump permissions. |
password | Depends on the engine. | Password for that user. |
generated_id | Yes | A unique UUID v4 identifier. |
The generated_id 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. Do not invent a simple random string.
Generating...Combining with the dashboard
The agent merges the databases from this file with those added from the dashboard. For the same generated_id, the dashboard configuration takes precedence over the file entry. This is what happens when you click Configure on a database declared in the file and save it.
Docker mount
If you edit the file manually, ensure it's mounted into the agent container.
services:
app:
# ...
volumes:
- ./databases.json:/config/config.json
# TOML: mount the file as /config/config.toml instead
# - ./databases.toml:/config/config.toml
# environment:
# DATABASES_CONFIG_FILE: "config.toml"To use TOML, mount the file as /config/config.toml and set the DATABASES_CONFIG_FILE variable to config.toml (default: config.json).
After any manual change, restart the agent so it picks up the new configuration:
docker compose restart app (or portabase restart <AGENT_PATH> with the CLI).
Last updated on