ahab/README.md

ahab

A wrapper around docker compose for our dockerized Django projects, so the same commands work in every repository.

It reads docker compose config to work out which service runs Django and which one is the database, so nothing here takes a service name or a -f. Everything it does, it does by running docker, git and the Postgres tools.

Installing

You will need Rust installed. Clone the repo and run:

cargo install --path .

Django

Each of these runs docker compose run --rm against the Django service, so it goes through the image's own entrypoint:

ahab django run <cmd>                # anything, in a fresh container
ahab django bash                     # a shell in a fresh container
ahab django manage <args>            # manage.py
ahab django makemigrations
ahab django migrate <args>
ahab django shell
ahab django make-command <app> <name>

Postgres

ahab postgres dump <path>             # pg_dump, custom format
ahab postgres dump -F plain <path>    # pg_dump, plain SQL
ahab postgres dump -F tar <path>      # pg_dump, tar
ahab postgres dump -F directory <d>   # pg_dump, a directory of files
ahab postgres dump -F cluster <path>  # pg_dumpall, roles and all databases
ahab postgres dump -F plain -z <path> # any of them, gzipped
ahab postgres import <path>           # drop, create, then restore
ahab postgres psql <args>             # psql in the database container

Dumps are written 0600, under a name of their own until they are complete and then renamed over the target.

Arguments reach psql untouched, and Docker is only asked for a terminal when there is one to hand over, so both of these work:

ahab postgres psql                          # interactive
ahab postgres psql -tAc 'select count(*) from auth_user' | wc -l

What an import makes of a dump

The shape is read from the file rather than from its name:

• a PGDMP or toc.dat header — an archive, restored with pg_restore, as is a directory produced by pg_dump -Fd
• a pg_dumpall header — a whole cluster, which creates its own databases and carries role statements, so the database is dropped but not recreated and the dump goes to psql connected to postgres
• gzip magic — decompressed on the way in, whichever of the three is inside
• anything else — SQL, fed to psql with ON_ERROR_STOP and --single-transaction, so a bad file rolls back instead of half applying

A cluster restore runs without ON_ERROR_STOP, so the expected complaints about roles that already exist do not stop it. Any other error fails the import. Importing into a cluster that has never held the database works either way.

Containers are stopped before an import starts, so one that fails leaves the project stopped and says so.

Link

A sandbox that mounts the repository can read anything untracked sitting in it — a .env, a dump, a key. Those paths can be moved out to a store of ahab's own and symlinked back: the host resolves the link, the sandbox does not.

ahab link add .env secrets/         # move out, leave symlinks behind
ahab link restore .env              # move it back into the repository
ahab link restore --all             # everything this repo has linked
ahab link list                      # what the store holds for this repository
ahab link check                     # what a sandbox can still read
ahab link check --porcelain         # `<code> <path>`, for scripts
ahab link check --exit-code         # exit 4 when anything is outside the store

Restoring is the inverse of adding: the file comes back to where it was and the store keeps nothing. A second checkout linking the same path is left with a dangling symlink, there being only ever one stored copy.

Every stored path is in one of three states:

$ ahab link list
store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik
	linked:    .env
	shadowed:  config.local.py
	missing:   secrets/token

• linked — the symlink is there and points at the store
• shadowed — a real file took the path back, so nothing reads the stored copy
• missing — the symlink is gone, and nothing reads the stored copy either

Only a linked path can be moved back, so restore --all says how many it left alone.

Adding refuses two kinds of path:

• a tracked path, which git would restore anyway. Where one is a symlink leading out of the repository, check reports it under the code T>
• a symlink already leading out of the repository, since moving it would move the pointer and leave the contents where they are

For scripts there is --porcelain, and -z for filenames that need it: entries end with a NUL, and the two paths of a symlink leading elsewhere are separated by one as well, the way git status -z reports a rename.

The store lives under ${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/, derived from the Git origin remote, or _local/<checkout> when there is no remote to name it after. Its directories are created 0700. A remote or checkout name that needed characters replacing carries a short fingerprint of the original, so two of them cannot share a directory.

What ahab makes of your project

Running ahab status prints the services it picked, the containers behind them, the credentials it would use and what the store holds. It reports whatever it cannot work out rather than stopping at the first problem:

$ ahab status
services: db, django
django: django (built from the project)
	container: 0a8b19e27634
postgres: db (postgres:18-alpine)
	container: 189d4d395d62
	user:      myproject
	database:  myproject_db
store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik
	linked:    2
	`ahab link check` lists what a sandbox can still read

Seeing what it runs

• -v — print each Docker command as it runs
• --dry-run — print the commands it would run, without running them
• -q — print only what was asked for, dropping the progress along the way, Compose's own included

All three work before or after the subcommand:

ahab -v django migrate
ahab --dry-run postgres import ./dump
ahab -q postgres dump ./dump

Nothing is written under --dry-run, the filesystem included: link add and django make-command say what they would do and leave the tree alone.

Service detection

Services can be named anything; ahab matches on what they are:

• postgres — the service whose image is a Postgres flavour, matching postg, timescale, pgvector or citus
• django — the service that both builds an image and sets DJANGO_SETTINGS_MODULE. Where more than one does, a worker beside the web service say, the one publishing ports wins

If nothing matches, or two candidates cannot be told apart, ahab says so and lists the services it looked at rather than guessing.

The role and database come from POSTGRES_USER and POSTGRES_DB on the detected service, falling back to db when neither is set. Both have to be names: a value holding an =, a URL or a leading dash is refused, libpq reading such a name as a whole connection string.

The compose file

Compose finds its own file and ahab does not pass -f, so set Docker's own COMPOSE_FILE when the file is not in the working directory, including its base.yaml:override.yaml form. A project's .env is a good place for it, since Docker reads that too:

COMPOSE_FILE=docker/docker-compose.yaml

Shell completion

Completion scripts are written to stdout, for Bash, Elvish, Fish, PowerShell or Zsh:

ahab completions zsh > ~/.local/share/zsh/completions/_ahab
eval "$(ahab completions zsh)"      # or one line in .zshrc, never goes stale

They are generated during the build as well, landing in target/*/build/*/out/. To install a single shell's file straight into place:

SHELL_COMPLETIONS_DIR_ZSH=~/.local/share/zsh/completions \
SHELL_COMPLETIONS_DIR_FISH=~/.config/fish/completions \
  cargo install --path .

Set SHELL_COMPLETIONS_DIR to write every shell into one directory instead. Either way the path has to be absolute.

Exit codes

• 0 — it ran and had nothing to report
• 1 — it could not finish
• 2 — the arguments were wrong
• 4 — it ran fine and found something worth reporting, which today means link check --exit-code with anything outside the store

Environment variables

• AHAB_LINK_ROOT — where ahab link keeps its store, the same as --store, which takes precedence. Defaults to ${XDG_DATA_HOME:-$HOME/.local/share}/ahab. Read by ahab status too, so it reports the store the link commands actually use