From 5d121b13b58015ea40f8171134db3605892d3bc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Jane=C5=BEi=C4=8D?= Date: Wed, 9 Sep 2026 12:05:11 +0000 Subject: [PATCH] docs: say what changed about names, modes and what check looks at --- README.md | 45 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 21aa507..5d5aab6 100644 --- a/README.md +++ b/README.md @@ -95,15 +95,21 @@ named anything: - **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`. A worker sharing the same build and `env_file` - matches too, so the one publishing ports wins + `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. +lists the services it looked at rather than guessing. Two services that both +build and set the settings module are ambiguous unless exactly one of them +publishes ports. `POSTGRES_USER` and `POSTGRES_DB` are read off the detected postgres service, so `dropdb`, `createdb`, `pg_restore` and `pg_dump` use the role and database the -project declares, falling back to `db` when it declares neither. +project declares, falling back to `db` when it declares neither. Both have to +be names: `ahab` hands them to those tools as a role and a database, and libpq +reads a database name holding an `=` or a url as a whole connection string, +which would send a dump to whatever server it names. A value that could be read +as something other than a name is refused rather than passed on. ## django @@ -138,6 +144,10 @@ ahab postgres import # drop, create, then restore ahab postgres psql # psql in the database container ``` +A dump is written `0600` and under a name of its own until it is complete, then +renamed over the target: a cluster dump carries every role's password hash, and +the default `0644` would hand it to anyone else with an account on the machine. + `psql` passes its arguments through and only asks docker for a terminal when it has one to hand over, so both of these work: @@ -155,9 +165,14 @@ A whole cluster dump from `pg_dumpall` is recognised by its header and handled differently again: it creates its own databases and carries role statements, so the database is dropped but not recreated, the dump goes to `psql` connected to `postgres`, and it runs without `ON_ERROR_STOP` because roles that already exist -report errors that are expected. Gzipped dumps are decompressed on the way in, -whichever of the three they hold. A cluster that has never held the database -yet is a valid target either way, so importing into a fresh one works. +report errors that are expected. Any error it does not expect is reported and +fails the import, since psql without `ON_ERROR_STOP` exits 0 having applied +only part of the dump. Gzipped dumps are decompressed on the way in, whichever +of the three they hold. A cluster that has never held the database yet is a +valid target either way, so importing into a fresh one works. + +`import` stops the project before it starts, so an import that fails leaves it +stopped and says so: `docker compose up` brings it back. ## link @@ -200,10 +215,24 @@ there is nothing to undo for a path whose symlink is gone. 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. +`check` looks at tracked paths too, since git tracks symlinks and one can lead +out of the repository without appearing in any untracked listing. `add` cannot +externalize a tracked path, so all `check` can do is report it, under the code +`T>`. + +A symlink already leading out of the repository is not something `add` will +take: moving the link would move the pointer and leave the contents where they +are, so the store would hold a way back out while `check`, seeing a link into +the store, called the repository clean. + The store lives under `${XDG_DATA_HOME:-$HOME/.local/share}/ahab////`, derived from the git `origin` remote, or `_local/` when there is no remote to -name it after. +name it after. Its directories are created `0700`: it exists to hold what +should not be readable from the repository, and on a shared machine the default +`0755` would leave that to whoever else has an account. A store path derived +from a remote, or a checkout name, that needed characters replacing carries a +short fingerprint of the original, so two of them cannot land on one directory. ## configuration