# Database schema

URL: https://docs.vaultpanel.net/developers/database-schema

> The tables in VaultPanel's MariaDB database by area, the migrations that add them, how secrets are stored at rest and how the audit log is protected.

The panel keeps its state in MariaDB 10.6 or newer (or MySQL 8) through Knex. Migrations are in `database/migrations`; `npm run db:migrate` applies them and then syncs the built-in roles and permissions from `shared/src/permissions.js`. On an installed panel, `vaultpanel update` runs them for you.

- IDs are UUIDs generated by the application, except the high-volume append tables (`audit_logs`, `server_metrics`, `job_logs`), which use auto-increment integers.
- All timestamps are UTC with millisecond precision.
- PostgreSQL is not supported.

This is the panel's own database, separate from the MariaDB the panel installs on servers for websites and apps. On an installed panel it runs in Docker on `127.0.0.1:3307`.

## Accounts and access

| Table | Purpose |
| --- | --- |
| `users` | Accounts: password hash (scrypt), encrypted TOTP secret, lockout counters, soft delete. |
| `roles`, `permissions`, `role_permissions` | Built-in roles and their permissions, synced from code. |
| `user_roles` | Role assignments (the interface assigns one role per user). |
| `teams`, `team_members` | Schema only, for later features. |
| `sessions` | Browser sessions; only a SHA-256 of the cookie value is stored. |
| `password_reset_tokens` | Invite and reset links: hashed, single use, expiring. |
| `user_recovery_codes` | Two-factor recovery codes. |
| `api_tokens` | API tokens: owner, scopes, expiry; only the token's SHA-256. |
| `audit_logs` | The append-only audit trail. |
| `settings` | Panel settings; secrets in it are stored encrypted. |
| `email_messages` | Email the panel sends itself (invites, resets, alerts, tests), kept for retries; the body is encrypted. |

## Servers, monitoring and jobs

| Table | Purpose |
| --- | --- |
| `servers` | Managed servers with their latest system information, service and filesystem snapshots, web stack, Docker summary, security summary and self-check report. Soft delete. |
| `server_enrollment_tokens` | One-time agent enrollment tokens (hashed). |
| `server_agents` | Registered agents and their Ed25519 public keys; revocation. |
| `server_metrics` | Telemetry samples, kept 7 days by default (`VAULTPANEL_METRICS_RETENTION_DAYS`). |
| `server_metrics_hourly` | Hourly averages (and CPU maximum) rolled up from `server_metrics`, kept 90 days by default. |
| `alert_rules` | Thresholds: metric, threshold, how long it must hold, severity, optional server or service. |
| `alert_events` | One row per alert: pending, firing, resolved, acknowledgement. A unique key allows one open event per rule, server and subject. Resolved alerts are kept 90 days by default (`VAULTPANEL_ALERT_HISTORY_DAYS`). |
| `jobs` | Operations requested for servers: type, status, attempts, timeouts, output, error, and the record they belong to (`resource_type`, `resource_id`). |
| `job_logs` | Log lines streamed by agents and the panel for each job. |
| `server_groups`, `server_group_members` | Server groups. |
| `bulk_actions`, `bulk_action_targets` | One action across a group, and one row per server. |
| `terminal_sessions` | Terminal sessions owners opened; recordings are asciicast files in the panel's data folder. |

The monitoring migration seeds five alert rules (CPU, memory, disk, server offline, service down); later migrations add **Website down** and **Server self-check failed**. All can be edited or deleted.

## Websites, DNS and email

| Table | Purpose |
| --- | --- |
| `websites` | Websites: type, server, settings, pending changes, Git deploy settings, uptime status, disk use. |
| `website_domains` | Each website's domains, with the primary one. |
| `ssl_certificates` | Certificates: issuer, expiry, renewal settings, the DNS provider a wildcard was checked through. |
| `website_deployments` | Deployments of static websites from Git. |
| `website_environment_variables` | Environment variables for those deployments' build commands, encrypted. |
| `website_checks`, `website_incidents` | Uptime checks and stretches of downtime, kept 30 days by default (`VAULTPANEL_UPTIME_HISTORY_DAYS`). |
| `cms_installs` | Apps put in a website by the app installer (WordPress, Joomla, Drupal, Laravel), with their database. |
| `file_uploads`, `file_downloads` | Large file-manager uploads and downloads passed through the panel in pieces. |
| `dns_zones`, `dns_records` | DNS zones served by BIND on the panel's servers, and their records. |
| `dns_providers` | Cloudflare and Namecheap accounts used for wildcard certificates; the secret is encrypted. |
| `mail_servers`, `mail_domains`, `mailboxes`, `mail_forwarders` | Email hosting: the mail server on each server, its domains, mailboxes and forwarders. |

## Apps, databases and containers

| Table | Purpose |
| --- | --- |
| `applications` | Apps: runtime, repository, commands, port, copies, CPU and memory limits, the current release, process state. |
| `environment_variables` | Each app's environment variables, encrypted. |
| `deployments` | Each deployment of an app: trigger, commit, stage, status, log. |
| `databases` | MariaDB databases on the servers, with their size and the app or website they belong to. |
| `database_users`, `database_user_grants` | Database users, with encrypted passwords, and their access to databases. |
| `containers` | Docker containers deployed by the panel, with their settings; environment values are encrypted. |

## Backups, cron and webhooks

| Table | Purpose |
| --- | --- |
| `backups` | Backups of websites, apps and databases: status, size, SHA-256, where they are kept. |
| `backup_schedules` | Backup schedules with how many to keep. |
| `backup_restores` | Restores and their safety backups. |
| `backup_storages` | Off-server destinations: S3-compatible buckets and SFTP servers. |
| `cron_jobs`, `cron_runs` | Cron jobs and the result of each run. |
| `webhooks`, `webhook_deliveries` | Webhooks and each delivery, with retries. URLs and signing secrets are encrypted. |

## Hosting, assistant and plugins

| Table | Purpose |
| --- | --- |
| `hosting_plans` | Plans: limits, app caps, price, billing cycle, server group. |
| `customers` | Hosting accounts: plan, server, billing id, status, what suspending turned off. |
| `customer_ports` | Each customer's own app ports per server. |
| `api_keys` | Billing API keys; only the key's SHA-256. |
| `assistant_conversations`, `assistant_messages`, `assistant_actions` | AI assistant conversations, every model reply, tool call and result, and proposed actions. |
| `plugins` | Installed plugins: manifest, approved scopes, the token's SHA-256 and the encrypted signing secret. |
| `plugin_directories` | Plugin directories and the last copy read. |

## Migrations

| Migration | Adds |
| --- | --- |
| `20261003000001_foundation` | Accounts, servers, agents, metrics, jobs, the audit log, settings. |
| `20261004000001_monitoring` | Hourly metrics, alert rules and events. |
| `20261004000002_websites` | Websites, domains, SSL certificates. |
| `20261004000003_applications_databases` | Apps, environment variables, deployments, databases and users. |
| `20261004000004_backups_cron_webhooks` | Backups, schedules, restores, cron jobs, webhooks. |
| `20261004000005_local_server` | Marks the panel's own server. |
| `20261004000006_security` | The servers' security summary, two-factor recovery codes, app CPU and memory limits. |
| `20261005000001_multi_server` | Server groups and bulk actions. |
| `20261005000002_hosting` | Plans, customers, billing API keys. |
| `20261005000003_assistant` | The AI assistant. |
| `20261005000004_containers` | Containers. |
| `20261005000005_api_tokens` | API tokens. |
| `20261005000006_plugins` | Plugins. |
| `20261006000001_customer_ports` | Customer app ports. |
| `20261006000002_backup_storage` | Off-server backup storage. |
| `20261006000003_app_instances` | Several copies of an app. |
| `20261007000001_dns_zones` | DNS zones and records. |
| `20261007000002_mail` | Email hosting. |
| `20261007000003_custom_nginx` | Custom NGINX rules for websites. |
| `20261008000001_cms_installs` | The app installer. |
| `20261008000002_panel_email` | Panel email. |
| `20261012000001_site_git_deploy` | Static website Git deploy. |
| `20261012000002_website_environment` | Website environment variables. |
| `20261012000003_ssl_renewal` | SSL renewal settings. |
| `20261012000004_customer_dns` | Name servers and DNS zones for customers. |
| `20261012000005_file_uploads` | Large uploads. |
| `20261013000010_file_downloads` | Large downloads. |
| `20261013000101_terminal_recordings` | Terminal sessions and recordings. |
| `20261013000140_plugin_directories` | Plugin directories. |
| `20261019000001_website_spa` | Single-page app websites. |
| `20261019000101_signed_git_webhooks` | Signed push-to-deploy webhooks. |
| `20261019000102_app_zero_downtime` | Zero-downtime reloads. |
| `20261031000001_dns_providers` | DNS providers for wildcard certificates. |
| `20261031000002_website_uptime` | Website uptime monitoring. |
| `20261031000003_server_self_check` | The server self-check report. |
| `20261101000001_database_website_link` | Linking a database to a website. |

## Secrets at rest

- Passwords are scrypt hashes.
- Session, enrollment and reset tokens, API tokens, plugin tokens, push-to-deploy tokens and billing API keys are stored as SHA-256 hashes, so they are shown once.
- TOTP secrets, the job-signing private key, app and website environment variables, database user passwords, container environment variables, webhook URLs and signing secrets, plugin signing secrets, DNS provider secrets, the assistant's API keys and panel email bodies are encrypted with AES-256-GCM, with keys derived from `VAULTPANEL_SECRET_KEY`.
- Passwords sent to the agent are removed from the stored job when it finishes.

> **Warning:**
Losing `VAULTPANEL_SECRET_KEY` means users must set up two-factor sign-in again, agents must be registered again, environment variables must be entered again and database passwords reset. The [panel backup](https://docs.vaultpanel.net/getting-started/backing-up-the-panel) includes it.

## Audit log protection

On MariaDB and MySQL, triggers reject every `UPDATE` and `DELETE` on `audit_logs`. `TRUNCATE` and `DROP` bypass triggers, so run the panel with a database user that lacks `DROP` where you can.
