Frequently Asked Questions

Find answers to the most common questions about Databasus, including installation, configuration and backup strategies.

Why does Databasus not use raw SQL dump format for logical PostgreSQL backups?

For logical backups, Databasus uses pg_dump's custom format with zstd compression at level 5 instead of the plain SQL format because it provides the most efficient balance between:

• Backup creation speed
• Restore speed
• File size compression (up to 20x times smaller than plain SQL format)

This decision was made after extensive testing and benchmarking of different PostgreSQL backup formats and compression methods. You can read more about testing here PostgreSQL backups: comparing pg_dump speed in different formats and with different compression.

Databasus will not include raw SQL dump format, because:

• extra variety is bad for UX;
• makes it harder to support the code;
• current dump format is suitable for 99% of the cases

Where is Databasus installed if installed via .sh script?

Databasus is installed in /opt/databasus/ directory.

How does Databasus support PITR (Point-in-Time Recovery)?

Databasus supports PITR through the Databasus agent — a lightweight Go binary that runs alongside your PostgreSQL database. The agent connects outbound to your Databasus instance, so the database never needs to be exposed publicly.

How backups work:

• The agent runs two concurrent processes: WAL streaming and periodic physical backups
• WAL segments are compressed with zstd and continuously uploaded to Databasus with gap detection to ensure chain integrity
• Physical backups are created via pg_basebackup, streamed as compressed TAR directly to Databasus — no intermediate files on disk
• Full backups are triggered on schedule or automatically when the WAL chain is broken

How restoration works:

• Run databasus-agent restore --target-dir <pgdata> --target-time <timestamp>
• The agent downloads the full backup and all required WAL segments from Databasus
• It extracts the basebackup, configures PostgreSQL recovery mode (recovery.signal, restore_command, recovery_target_time)
• Start PostgreSQL — it replays WAL to the target time, promotes to primary and resumes normal operations

Suitable for:

• Disaster recovery with near-zero data loss — restore to any second between backups
• Self-hosted and on-premise databases where hourly or daily logical backups are not granular enough
• Databases in closed networks — the agent connects outbound to Databasus, so no inbound access is needed
• Large databases where physical backups are faster than logical dumps

How is AI used in Databasus development?

There have been questions about AI usage in project development in issues and discussions. As the project focuses on security, reliability and production usage, it's important to explain how AI is used in the development process.

AI is used as a helper for:

• Verification of code quality and searching for vulnerabilities
• Cleaning up and improving documentation, comments and code
• Assistance during development
• Double-checking PRs and commits after human review

AI is NOT used for:

• Writing entire code
• "Vibe code" approach
• Code without line-by-line verification by a human
• Code without tests

The project has:

• Solid test coverage (both unit and integration tests)
• CI/CD pipeline automation with tests and linting to ensure code quality
• Verification by experienced developers with experience in large and secure projects

So AI is just an assistant and a tool for developers to increase productivity and ensure code quality. The work is done by developers.

Moreover, it's important to note that we do not differentiate between bad human code and AI vibe code. There are strict requirements for any code to be merged to keep the codebase maintainable.

Even if code is written manually by a human, it's not guaranteed to be merged. Vibe code is not allowed at all and all such PRs are rejected by default (see contributing guide).

We also draw attention to fast issue resolution and security vulnerability reporting.

How to backup Databasus itself?

If you want to backup your Databasus instance (including all configurations, databases and credentials), follow these steps:

1. Go to /opt/databasus (or the folder where you installed Databasus)
2. Navigate to the databasus-data directory

You need to backup:

• secret.key — encryption key for your credentials
• /pgdata — internal PostgreSQL database of Databasus that contains all your configurations and backup metadata

If you use local storage for backups, you can also backup the backups folder.

Important: There are two different scenarios for recovery:

• Recover backups without Databasus UI: You can recover your database backups using only the secret.key file, without needing Databasus or its internal data. See the manual recovery guide for detailed instructions.
• Restore Databasus UI and all configurations: If you want to restore the Databasus interface with all your configurations, scheduled backups and backup history, you need to backup both secret.key and the /pgdata folder (which contains the encryption metadata and all Databasus configurations).

To restore Databasus on another server: simply recreate the databasus-data folder structure with the backed up files and start Databasus.

How is Databasus supported by Anthropic and OpenAI open-source programs?

In March 2026, Databasus was accepted into both Claude for Open Source by Anthropic and Codex for Open Source by OpenAI. It is really valuable for us that the project has been recognized as important open-source software for the industry by two of the world's leading AI companies — especially given the high eligibility requirements of both programs.

What does it mean for users? It just one more reliability confirmation that the project has been independently evaluated and recognized by industry leaders as critical infrastructure worth supporting. So we have even higher code quality, faster security reviews and continued active development due to access to the latest unlimited AIs.

Despite having access to these programs, Databasus maintains strict AI usage rules as described in the AI usage section. All code requires line-by-line human verification, full test coverage and experienced developer review. Vibe coding is not allowed. AI remains a tool for developers — not a replacement for human judgment.

Why are PostgreSQL and Valkey packaged inside the container?

Databasus uses PostgreSQL as its internal storage (backup metadata, database configurations, audit logs, etc.) and Valkey for caching. Both are bundled inside the image. Here is why:

For users:

• You only pull one image — no extra configs, no managing other images, no tracking internal service versions, no environment variables to set. Just run docker run, even if you manage hundreds of databases.
• Auto-update covers everything — enable auto-update for the Databasus image and forget about it. There are no separate upgrade guides for internal services and no multiple image versions to keep in sync.
• The backup guide just works — it is written around the internal PostgreSQL. With an external database you would have to figure out its backup separately.

For Databasus maintainers:

• We know exactly what is inside the image — we control migrations, extensions and service configuration. That means we can safely bump internal service versions without breaking compatibility and stay focused on development.
• Users never have to touch their compose files for upgrades — PostgreSQL and Valkey versions are updated inside the image. With external services, many users would skip or delay upgrade steps and run into compatibility issues across versions.

So, summing up, it is reasonable approach for projects which focus on simple UX and do not face hunders of RPS. For example, GitLab CE follows same approach.

What about performance overhead? — there is none worth noting. Databasus is network-intensive (uploading and downloading backup files to remote storage), not database-intensive. The internal PostgreSQL typically use 100–150 MB of RAM for hundreds of backup jobs across hundreds of databases with millions of backups records. If you increase your server resources, it will increase accordingly so there is no chance to reach vertical scaling limits.

Both services are only accessible inside the container (PostgreSQL runs on port 5437, Valkey binds to 127.0.0.1 only) and are never exposed externally.

I don't care and still want to use my external PostgreSQL or Valkey

The only reason we use external services ourselves is the Databasus playground — it runs on a cluster of distributed servers that together handle up to 100 Gbit/s of throughput, so all nodes need to share the same database.

Why do we use a multi-node cluster for the playground, but not recommend it to you even you have hundreds of DBs? Our playground is a public service used by thousands of users (because Databasus is the most popular PostgreSQL backup tool now). Because it is public, we also face DDoS attacks and need far higher throughput than any typical company would. It's not just production use, it's permanent defence 🛡️. You are almost certainly not running anything like this.

Actually, we don't know which company needs to backup thousands of DBs like our playground. Usual production use of Databasus is from a couple of databases to hundreds of databases (in DBA outsourcing companies)

Anyway, if you genuinely face the same situation as we — use variables below (we do not lock this ability despite it's hard to maintain it), but lock Databasus version before. By the way, for a regular single-server installation this adds complexity with no benefit. For internal backuping of our DBs we also use regular Databasus installation with internal PostgreSQL and Valkey.

If you still want to proceed, here are the environment variables that control this:

External PostgreSQL:

• DATABASE_DSN — full PostgreSQL connection string. Example: postgresql://user:password@host:5432/databasus

External Valkey:

• VALKEY_HOST — hostname of your Valkey instance
• VALKEY_PORT — port (default 6379)
• VALKEY_USERNAME — username, leave empty if not set
• VALKEY_PASSWORD — password
• VALKEY_IS_SSL — true or false

What if I need distributed stateless HA?

If your goal is a fully distributed, stateless HA setup where multiple application nodes share the same PostgreSQL and Valkey instances — neither Databasus, WAL-G, nor pgBackRest are the right tools for that. Those are backup tools, not cluster orchestrators.

For distributed PostgreSQL HA you should look at purpose-built Kubernetes operators:

• CloudNativePG (CNPG) + Barman Cloud — the CNCF-backed operator with built-in WAL archiving and backup to object storage via Barman Cloud
• PGO (Crunchy Postgres Operator) + object storage — another mature operator with pgBackRest integration and S3-compatible storage support