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.

Two ways to read what it is, and both are accurate:

The second is not a later ambition. It is why the shape is what it is — and it is the supported path today, because the console that would let a person add an instance in a browser is not finished yet (see Two ways to drive it).

One code path is the point, not a convenience. An agent cannot reach a capability a human cannot audit, because there is only one of each. Every run is a row in job_runs and a line in a log with the same shape whoever started it, so "what did the agent do last night" is the same query as "what did the daemon do last night".

The goal

To be a tool a DBA, a DevOps engineer or an SRE can rely on — one that works alongside an AI agent and saves a large amount of its tokens, and works just as well with no agent at all.

Three commitments, and they are meant to be held to:

The shape of that, because it is the whole argument in one picture:

  WITHOUT a tool                              WITH DBA Brain
  agent -> raw SQL -> agent                   agent -> DBA Brain -> database

  "check this database"                       "check this database"
    -> SELECT ... dm_os_wait_stats              -> one JSON request
    <- every row, into the context
    -> SELECT ... sys.databases                 <- one graded envelope:
    <- every row, into the context                    41 checks, 40 OK,
    -> SELECT ... backupset                           1 WARNING: appdb  
    <- every row, into the context                    log backup 31h old
    -> ... once per check, per run
    <- all of it, healthy or not               -> fetch the evidence for
                                                  the ONE that came back bad
  The model reads the evidence and
  derives the verdict, every time.            The verdict was derived in
  It pays for the 95% that was fine.          reviewed SQL, once, by a person.

The saving is not compression — it is not sending what nobody needed to read. Grading a metric is a fixed decision that belongs in SQL somebody reviewed, not a judgement re-made by a model on every cycle from raw rows. The agent's context is then spent on the thing that is actually hard: what to do about the one check that failed.

And the target that is not met yet: a person who has never seen this project should go from pip install dbabrain to a collecting install by pointing an AI agent at these docs — no estate bundle from another machine, and no assumption that they already know what a database ought to be checked for. Today that path expects more DBA knowledge than it should. Closing that gap is the current priority; see docs/first_run.md for where it stands.

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 what an agent operates. Nothing here talks to a model, holds a prompt, or decides anything on its own. It is a toolkit with a CLI, where every capability takes one JSON object and answers with one, and that shape is what lets a human, a shell script, a chat command and an agent drive the same operation without a translation layer. The distinction is worth keeping: a layer that does not reason is a layer you can audit, and the judgement about whether to restore production stays with whoever is accountable for it.
• 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, 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.

Two more, deliberately:

The person who gets paged about a database without being a DBA — the DevOps or SRE owner of a service, in a company that has no DBA at all. They need the same operations and should not have to design a monitoring strategy to get them, so the shipped catalogue is meant to be that expertise: adopting this should be configuring an estate, not deciding what a healthy database looks like. That is the intent — docs/first_run.md is honest about how far it holds today.

Whoever is building an agent that has to touch a database and does not want to hand it a shell. The alternative to a typed operation is an agent composing SQL and psql invocations from prose, where the blast radius is whatever it happened to write. Here what it can do is the set of commands that exist: each one reviewed when it was written, each one logged the way a human's run is.

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.