DBA Brain

A database operations toolkit for people who are on call. It collects health metrics from your SQL Server, Oracle, PostgreSQL and MySQL instances, grades them against policies you write, runs your scheduled SQL, takes backups and proves them by restoring them, checks objectives against real measurement history, and tells you about it — on a schedule, without an agent on any monitored machine.

It sends nothing anywhere by itself. No telemetry, no usage reporting, no update check. It connects to the databases and hosts you list, and — only if you turn it on and give it a token — to a chat service. Nothing else.

This project is being renamed. The distribution and the module path are still db_ops, so every command below reads python -m db_ops.<app>.cli. They become dbabrain when the code moves to the public repository; nothing else changes with them.

What it is not

• It is not an AI agent. It is a toolkit with a CLI, where every capability takes one JSON object and answers with one. That shape is what lets a human, a shell script, a chat command and an AI agent all drive the same operation without a translation layer — and it is why an agent-facing interface can be added later without rewriting anything underneath it. Today nothing here talks to a model.
• It does not replace incident analysis, change approval, or runbooks. It supports them. A restore drill proves a backup is restorable; deciding to restore production is still yours.
• It is not a dashboard product. It has a web console for reading reports and editing configuration, but the primary interface is a CLI and its primary output is a record in a database you own.
• It installs nothing on your databases. No agent, no extension, no stored procedure. It logs in with a read-only account and asks questions.

Who it is for

A DBA or small team responsible for a handful to a few dozen instances across more than one engine, who already know what they want checked and are tired of it living in twelve cron jobs and a folder of scripts. If you have one PostgreSQL cluster and a hosted monitoring product you are happy with, this is more machinery than you need.

Capabilities

Ordered to match the reference docs; the ORD number links to each one.

Fourteen components, and the list is closed. ORD 01–12 are the apps — one directory, one CLI each — and 13/14 are the two shared layers they all sit on.

Every component has a doc, and every doc has a component. One docs/NN_*.md per package, both directions, enforced by tests/test_docs_cover_every_component.py. A component is not finished until its doc exists.

That is a claim few projects can make, and it was written the hard way: one shared layer reached 46 modules and roughly 6,500 lines with no documentation and a fully green suite, because nothing connected the two directories.

Install

Python 3.12+. Every database driver is an extra, so a DBA who runs only PostgreSQL is not made to install an ODBC driver and an Oracle client to start.

python -m venv .venv
.venv/bin/pip install 'dbabrain[postgres]'      # Windows: .venv\Scripts\pip

Full instructions, including the two prerequisites that are not pip-installable and the container image: docs/installation.md.

Five minutes

A throwaway container, a least-privilege login, seven real measurements — and nothing to uninstall afterwards:

examples/postgres-quickstart/ — needs no system packages. examples/sqlserver-quickstart/ — same shape, and it finds a real problem with the instance, then clears it once you fix it.

cd examples/postgres-quickstart
docker compose up -d
python -m db_ops.db.cli      --config config.json init
python -m db_ops.metrics.cli --config config.json collect --dry-run
python -m db_ops.metrics.cli --config config.json collect
python -m db_ops.metrics.cli --config config.json report

Two ways to drive it

After pip install, someone has to describe the estate — which instances exist, which credentials reach them, where alerts go. There are two ways to do that, and they differ only in who writes the files.

The agent path is the supported one on purpose: the configuration surface has to be settled before something generates it, and a console that writes files nobody has agreed the shape of becomes a second source of truth. The console itself ships — it serves the reports and edits configuration — but adding an instance from a host, a port and a password is not in it yet.

Both paths are written out step by step, with what to assert after each one, in docs/first_run.md. It is written to be followed by a program and to be readable by a person, because until the console lands they do the same thing.

How it is configured

Everything is JSON you own. A new threshold, target, route, schedule or severity belongs in data/*.json, never as a literal in Python — the design assumes the person affected by a setting can read it, change it, and be reviewed on the change.

config.json      → where runtime output goes, and which declaration files to read
data/*.json      → what to run, monitor, report and deliver
secrets/         → the plaintext source of the encrypted secret store (git-ignored)
assets/          → the SQL and scripts that implement it

Every configuration file has a *.example.json beside it, complete enough to copy, rename and edit, with a notes array explaining what it decides and why.

The tool finds its configuration by a stated order, not by where its code sits on disk: DB_OPS_HOME, then the working directory if it holds data/ or config.json, then the package location. That is what makes an installed copy work, and it is why standing in an example directory is enough to run against it.

See docs/configuration.md.

Secrets

Passwords and tokens live encrypted in data/encrypted_secret_text.json — PBKDF2-HMAC-SHA256 over a per-file salt, sealed with Fernet. The passphrase is supplied at run time and is never written to disk, a log, or the store. Configuration names a reference; the value is resolved from the environment first and the encrypted store second, so an organisation with an external secret manager never has to use the built-in one.

A request carrying a password is passed on stdin, never as a command-line word — argv is world-readable in the process table.

See docs/security.md, which also covers the least-privilege login the toolkit needs on each engine, the audit trail, and running with no outbound network access.

How it is put together

Fourteen components, two shared layers, four rules about who may call whom — and a guard test beside each rule, because a diagram describes what someone intended and a test describes what is true this morning.

common may not be imported — it is only ever run as a CLI. lib may not run a CLI — it is only ever imported. No app imports another app. No shared layer imports an app.

See docs/architecture.md.

Documentation

Tests

The suite is offline: no database, no network, no delivery. That is why it runs anywhere and why you can refactor with it.

.venv/bin/python -m pytest tests -q                    # full suite
.venv/bin/python -m pytest tests/test_<area>.py -q     # while developing

Tests read as prose — a module docstring explaining why the behaviour matters, then test names that are sentences.

License

Apache License 2.0. See NOTICE.