User Guide
Manage your agents, databases, channels and backup policies on a daily basis.
Understanding the Architecture
Portabase runs as two separately deployed components.
The Dashboard centralizes configuration: agents, databases, backup schedules, retention, alerts and storage channels.
The Agent is a Rust binary installed on the same network as your databases. It is responsible for:
- detecting and reporting your databases automatically
- executing backups according to the defined schedule
- sending backup files to your storage destinations
- reporting logs and status back to the dashboard
The dashboard never connects directly to your databases. Everything goes through the agent. This architecture lets you protect databases on a private network or behind a firewall without exposing your servers.
The agent regularly sends a ping to the dashboard. This ping transmits the list of available databases, agent status and operation results. In return, the dashboard sends instructions (schedules, restore orders, etc.).
Entity Hierarchy
Organisation
├── Agents
│ └── Databases (discovered automatically)
│ ├── Project assignment (optional)
│ ├── Backup policy (cron)
│ ├── Retention policy
│ ├── Alert policies ──→ Notification channels
│ └── Storage policies ──→ Storage channels
├── Projects (logical grouping)
├── Notification channels
└── Storage channelsManaging Agents
An agent represents one instance of the Portabase Agent program deployed on a server. A single agent can manage multiple databases on the same server. If you have databases on multiple servers, create one agent per server.
Creating an Agent
Prerequisite: you must be owner or admin of the organisation.
Go to Organisation > Settings > Agents and click Add agent.
Fill in the fields:
- Name — human-readable identifier (e.g.
Production Server EU,Dev Machine) - Description — free notes about this agent's role
Confirm. The agent is created and an Edge Key is generated automatically.
Copy the Edge Key from the agent detail page (button Show Key), then paste it into the Portabase Agent Rust configuration on your server.
Verifying the Connection
On next startup, the agent pings the dashboard. You'll know it's connected when:
- the Last Contact column shows a recent timestamp
- the status turns green in the interface
From the first ping, the agent transmits the list of all databases it can see. These databases appear automatically in the dashboard — you don't need to create them manually.
Monitoring Agent Health
From the agent detail page, the Health tab shows a 12-hour ping history as a grid. Each cell represents one ping: green if received, red if missed.
Organising Databases with Projects
A project is a logical folder for grouping databases. It has no effect on backup execution — it is purely an organisational tool.
Typical uses: group all databases for an application, separate production from staging, organise by team or client.
Creating a Project
Prerequisite: you must be owner or admin of the organisation.
- Go to Organisation > Projects
- Click New project
- Give the project a name, choose databases and confirm
Configuring a Database
How Databases Appear
Databases are not created manually. They appear automatically as soon as the connected agent detects them via its ping.
If a database doesn't appear, check that:
- the agent is connected (green status, recent Last Contact)
- the database is accessible from the agent's server
Configuration Tabs
From the database detail page (Projects > [project] > [database]):
| Tab | Content |
|---|---|
| Overview | KPIs, status, general information |
| Backups | Backup list, manual actions |
| Restore | Available restore operations |
| Schedule | Cron schedule + retention |
| Alerts | Alert policies |
| Storage | Storage policies |
| Logs | Detailed operation logs |
Triggering a Manual Backup
From the Backups tab, click Backup now. The backup moves to waiting status, then ongoing as soon as the agent picks it up at the next ping.
| Status | Meaning |
|---|---|
waiting | Waiting to be picked up by the agent |
ongoing | Currently running |
success | Completed successfully |
failed | Failed — check the Logs tab for details |
Importing an External Backup
- From the Backups tab, click Import
- Drag and drop your file or browse your filesystem
Restoring a Database
Restoration overwrites the current data in the target database. Make sure you have a recent backup before restoring. Restore is not available for Redis and Valkey.
From the Restore tab, two options:
- From an existing backup — choose a backup from the list and click Restore
- From external storage — select a file available in one of your storage channels
Configuring Channels
Channels are connectors to external services, used in two contexts: notifications and storage. They are configured at the organisation level and can be reused across multiple databases.
Creating a channel:
- Organisation > Notifications > Channels > Add channel
- Choose the provider
- Fill in the connection details
- Give the channel a recognisable name (e.g.
Slack #ops-alerts) - Test with the Test button
- Enable the channel
A disabled channel receives no notifications even if alert policies point to it. Use this flag to temporarily silence a channel without losing its configuration.
Creating a channel:
- Organisation > Storages > Channels > Add channel
- Choose the provider
- Fill in the connection parameters
- Give the channel a name (e.g.
S3 Backup Bucket EU) - Enable the channel
The Local provider stores files on the agent's server, not the dashboard server. If the agent moves to another server or the disk changes, locally stored backups will no longer be accessible.
Setting Up Policies
Policies are configured at the database level. A database can have multiple policies of different types.
Backup Schedule (cron)
Where to configure: database detail page > Schedule tab
The schedule is a cron expression that defines when automatic backups run.
┌──────── minute (0–59)
│ ┌───── hour (0–23)
│ │ ┌── day of month (1–31)
│ │ │ ┌─ month (1–12)
│ │ │ │ ┌ day of week (0–7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *| Expression | Result |
|---|---|
0 2 * * * | Every day at 2 AM |
0 */6 * * * | Every 6 hours |
0 2 * * 1 | Every Monday at 2 AM |
0 2 1 * * | 1st of every month at 2 AM |
Need help building an expression? Use crontab.guru.
To disable automatic backups, switch to Manual mode. You can still trigger backups manually from the Backup now button.
Deleting the schedule also deletes the associated retention policy. If you add a schedule later, you will need to reconfigure retention.
Retention Policy
Where to configure: database detail page > Schedule tab > Retention section
Prerequisite: an active cron schedule must exist on the database.
Keeps only the N most recent backups. Older backups are deleted as new ones are created.
| Parameter | Min | Max | Default |
|---|---|---|---|
| Number of backups | 1 | 100 | 7 |
Ideal for development databases or when disk space is limited.
Keeps all backups from the past N days.
| Parameter | Min | Max | Default |
|---|---|---|---|
| Number of days | 1 | 3,650 | 30 |
Ideal for databases with legal retention requirements over a specific period.
The Grandfather-Father-Son strategy keeps the best representative of each time period to maximise historical coverage.
| Level | What is kept | Default | Max |
|---|---|---|---|
| Daily | The last N days | 7 | 31 |
| Weekly | Last backup of the last N weeks | 4 | 52 |
| Monthly | Last backup of the last N months | 12 | 120 |
| Yearly | Last backup of the last N years | 3 | 50 |
With default values: maximum 26 backups covering 3 years of history.
Ideal for production databases with compliance or long-term audit requirements.
There can only be one retention policy per database. Creating a new one automatically replaces the existing one.
Alert Policies
Where to configure: database detail page > Alerts tab
Prerequisite: at least one notification channel must be configured and enabled.
| Event | When is it triggered? |
|---|---|
error_backup | A backup fails |
success_backup | A backup completes successfully |
error_restore | A restore fails |
success_restore | A restore completes successfully |
error_health_database | The agent reports the database is no longer accessible |
The weekly_report event is not yet implemented. Want to help? See the
Contributing guide.
Creating a policy:
- Alerts tab > Add policy
- Select the target notification channel
- Check the events to monitor
- Enable and save
You can create multiple policies on the same database, for example, Slack for errors and SMTP for successes. Each policy can be individually disabled without deleting it.
Storage Policies
Where to configure: database detail page > Storage tab
Prerequisite: at least one storage channel must be configured and enabled.
Creating a policy:
- Storage tab > Add policy
- Select the target storage channel
- Enable and save
You can create multiple storage policies on the same database. The backup file will be sent simultaneously to all active destinations.
From the Backups tab, each backup shows the send status per channel:
| Status | Meaning |
|---|---|
pending | Waiting to be sent |
success | Sent (path, size and checksum verified) |
failed | Send failed for this channel |
Quick Reference
| What you're looking for | Path |
|---|---|
| Create an agent | Settings > Agents > Add agent |
| View an agent's key | Settings > Agents > [agent] > Show Key |
| Create a project | Projects > New project |
| View an agent's databases | Settings > Agents > [agent] > Databases |
| Configure backup schedule | Projects > [project] > [database] > Schedule |
| Configure retention | Projects > [project] > [database] > Schedule > Retention |
| Configure alerts | Projects > [project] > [database] > Alerts |
| Configure backup storage | Projects > [project] > [database] > Storage |
| Add a notification channel | Organisation > Notifications > Channels > Add channel |
| Add a storage channel | Organisation > Storages > Channels > Add channel |
| Notification logs | Organisation > Notifications > Logs |
| Agent health | Settings > Agents > [agent] > Health |
Last updated on