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 do physical and PITR (Point-in-Time Recovery) backups work?

Databasus runs physical backups remotely from its own host, connecting to your PostgreSQL over the standard replication protocol, so nothing needs to be installed on the database server. If the database lives in a closed network, Databasus can reach it through an SSH tunnel to an internal host or a bastion, so the database never has to be exposed publicly.

Why this is possible now: for years tools like pgBackRest and WAL-G had to build their own engines for incremental, block-level backups, because PostgreSQL had no native one. That changed with PostgreSQL 17, where the feature was developed by Robert Haas with help from David Steele, the author of pgBackRest. PostgreSQL now ships native server-side block-level incremental backups under the hood (pg_basebackup --incremental and summarize_wal), so Databasus builds on that instead of reinventing one.

How backups work:

  • Full backups are created with pg_basebackup, streamed directly to Databasus
  • Block-level incrementals use pg_basebackup --incremental, where PostgreSQL 17's server-side WAL summaries (summarize_wal = on) track changes so only the changed blocks are transferred
  • WAL is streamed continuously via pg_receivewal to keep the recovery chain complete between backups
  • Physical backups require PostgreSQL 17 or newer; on older versions you use logical pg_dump backups instead

How restoration works:

  • pg_combinebackup reconstructs a runnable data directory from the full backup and its incremental chain
  • PostgreSQL then replays WAL up to the target time you choose, recovering to any second between backups
  • Once you start PostgreSQL, it finishes recovery, promotes to primary and resumes normal operations

You don't have to do this by hand. The Databasus UI gives you step-by-step instructions for restoring to a host or a Docker database, either through a ready-made script or by downloading the backups manually. We prepared the script so a restore is just one command, but you can also rebuild the chain of full, incremental and WAL parts yourself if you prefer. Incremental and WAL are optional too: you can take only a full backup, without incrementals, and WAL is not mandatory.

Why we use PG 17 native backups:

  • They reuse PostgreSQL's own backup machinery instead of reinventing it, so you get battle-tested internals with thousands of tests and edge-cases behind them
  • They give near-zero data loss, letting you restore to any second between backups

Why did Databasus move away from agent-based backups?

An earlier version of Databasus shipped a backup agent: a binary that ran on the database host to stream WAL and create physical backups locally. That first implementation turned out to be a mistake, and we removed it. Physical backups now run remotely from the Databasus host, as described above.

Why the agent was the wrong approach:

  • It was a naive implementation that only copied WAL on top of full backups, which led to a long RTO
  • Users had to configure both Databasus and a separate agent, when doing everything remotely from one place is far simpler
  • Because the agent lived outside the main system, it was hard to cover every test case
  • There is really only one problem an agent solves: reaching a database that is not accessible from outside. For 99% of users that is already handled by running Databasus inside the private network or connecting over SSH, so the agent was reinventing the wheel and making a simple problem far more complicated than it needed to be
  • It could not run on managed databases like RDS and Cloud SQL, which forbid host-level installs but already expose the replication protocol, so a remote path was needed anyway
  • It also came with a lot of edge cases. Broken connections, managing agent updates and gathering logs from a separate process were all painful, and the fewer moving parts a system has, the more reliable it is in everyday use

We made sure existing backups stay safe. If you upgrade from a version that still has agent backups, Databasus won't do it silently: it warns you about the change and lets you either stay on the supported version 3.42.0 or remove the old agent backups yourself before upgrading. The agent-based implementation remains available up to version 3.42.0 and will keep working for a long time, so nothing breaks.

How is AI used in Databasus development?

AI helps us develop Databasus, from planning and implementation to tests and documentation. People set the direction and make the final decision. A human reads every line before a change is merged.

We use spec-driven development (SDD) with OpenSpec to agree on behavior before implementation.

Independent review at each stage

Automatic hooks start separate reviewer sessions with read-only access to the repository. Each agent inspects the relevant code and returns its own findings. The implementing agent cannot approve its own work.

Review starts before implementation. Separate planning agents look for simpler solutions, check proposed names and assess the design. They also check that requirements and verification tasks agree.

  • Code reviewer: Looks for bugs, missed edge cases, broken error handling, races, resource leaks and security problems.
  • Requirements reviewer: Traces each requirement to its implementation and tests. Checks that the tests actually prove the promised behavior.
  • Architecture reviewer: Checks module boundaries, dependency direction, data ownership, migrations and API rules.
  • Code structure reviewer: Checks names, file and function responsibilities, comments and readability.
  • Test reviewer: Checks whether tests would catch missing behavior or a regression. Also checks condition waits, cleanup and verification evidence.
  • Documentation and task reviewer: Checks that documentation matches the code, tasks are complete and verification claims have evidence.

Full implementation reviews run in parallel. Each changed specification gets its own requirements reviewer, alongside separate architecture, test and documentation reviewers. A change covering two specifications therefore gets five full-review agents.

Blocking findings stop acceptance. The implementing agent fixes them or explains why a finding is incorrect. A follow-up reviewer checks that resolution and the subsequent edits. A review that could not run does not count as passed.

Review hook implementation · Reviewer instructions

Automated checks and real restores

Independent review works alongside strict automated checks. golangci-lint and our architecture linter check backend dependencies, module boundaries and migration rules. API checks validate OpenAPI contracts and generated code. Frontend checks cover TypeScript, React, layer imports, styles and localization.

Ruff and ty check Python formatting, lint rules and types. ShellCheck checks shell scripts. actionlint checks GitHub Actions workflows. Pre-commit hooks check affected backend, frontend and Python files without rewriting them. CI also runs linting.

Backend lint checks · Frontend lint checks · Python checks

Tests exercise real behavior. Backend tests use the application API and check engines against real database containers. End-to-end scenarios create backups, restore them and inspect the restored data. Other tests cover upgrades, frontend screens and browser workflows with visual comparisons.

Checks are chosen for each change. Required release suites run on amd64 and arm64. The implementing agent runs the relevant linters and tests before review; review agents inspect the evidence without rerunning those commands.

Test strategy and commands

Before publication, CodeQL and Semgrep analyze code, Gitleaks scans for secrets and dependency checks look for vulnerabilities. Trivy scans container images and Dockerfiles.

Required CI checks must pass before release. Security and reliability engineering.

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.

Databasus accepted into Claude for Open Source program by AnthropicDatabasus accepted into Codex for Open Source program by OpenAI