docs(db): drop the pg_restore rollback that fails and name the client tool directories the code searches

Updating offered a second way to roll back a Postgres update: drop the
database, create it again and pg_restore the pre-migrate copy into it. TREK's
copy is a dump of its schema by name, so pg_restore creates public again,
stops at "schema public already exists" and rolls the load back, leaving an
empty database in the middle of a rollback. The page now says so and keeps the
steps that clear the schema instead.

Environment-Variables listed /usr/lib/postgresql/17 to 14 as the default
search path for the client tools; the code and the image start at 18.
This commit is contained in:
Maurice
2026-11-17 21:59:11 +01:00
parent 620f5a94f6
commit f47490dd9f
2 changed files with 2 additions and 2 deletions
+1 -1
View File
@@ -509,7 +509,7 @@ through environment variables. `TREK_PLACE_PHOTO_DIR` below is unaffected.
| `BACKUP_MAX_DECOMPRESSED_MB` | Maximum **decompressed** size (in MB) of a restore-backup archive — the zip-bomb guard. Independent of `BACKUP_UPLOAD_LIMIT_MB` and enforced on both restore paths, so a restore that fits the upload cap can still be refused with `Backup exceeds the maximum decompressed size.` Raise both when restoring a very large instance. | `5120` (5 GB) |
| `TREK_DB_URL` | Run TREK on a PostgreSQL database instead of the SQLite file: `postgres://user:password@host:5432/database` (or `postgresql://`). Needs PostgreSQL 14 to 18, an empty database of its own and a role that is not a superuser. Percent-encode special characters in the password. See [Database: Postgres](Database-Postgres). | unset (SQLite) |
| `TREK_DB_POOL_MAX` | Most connections TREK opens to the PostgreSQL database, from 1 to 100. Unused on SQLite. | `10` |
| `TREK_DB_PG_BIN_DIR` | Directory holding `pg_dump`, `pg_restore` and `psql`, which back up and restore a PostgreSQL database. Unset, TREK looks in `/usr/lib/postgresql/17` to `14` (`bin`), `/usr/local/bin` and `/usr/bin`. Unused on SQLite. See [Database: Postgres](Database-Postgres#where-the-client-tools-are-found). | unset |
| `TREK_DB_PG_BIN_DIR` | Directory holding `pg_dump`, `pg_restore` and `psql`, which back up and restore a PostgreSQL database. Unset, TREK looks in `/usr/lib/postgresql/18` to `14` (`bin`), newest first, then `/usr/local/bin` and `/usr/bin`. Unused on SQLite. See [Database: Postgres](Database-Postgres#where-the-client-tools-are-found). | unset |
| `TREK_DB_FILE` | Explicit path of the SQLite database file. Unset, TREK uses `travel.db` in the data directory. Not used with `TREK_DB_URL`. | unset |
| `TREK_DB_JOURNAL_MODE` | SQLite [journal mode](https://sqlite.org/pragma.html#pragma_journal_mode): `DELETE`, `TRUNCATE`, `PERSIST`, `MEMORY`, `WAL` or `OFF`. Set `DELETE` when the data directory lives on network storage — see below. Values SQLite doesn't know log a warning and fall back. | `WAL` |
| `TREK_DB_PRE_MIGRATE_SNAPSHOT` | Copy the database to `pre-migrate-<schema>-<time>.db` next to it before a startup applies pending migrations, so the previous image can be started on that copy again. On PostgreSQL the copy is a `pg_dump` file, `pre-migrate-<schema>-<time>.pgdump`, and needs the client tools (see `TREK_DB_PG_BIN_DIR`). If the copy cannot be written the startup refuses rather than migrate without one. Set `false` only to get past that when you cannot free space and have a backup of your own. See [Updating](Updating#database-migrations). | `true` |
+1 -1
View File
@@ -155,7 +155,7 @@ The copy cannot be loaded over the migrated schema: it recreates TREK's tables,
Put the password in the `PGPASSWORD` environment variable rather than in the URL, which keeps it out of the command line. Delete `restore.sql` afterwards: it holds the whole database in plain text.
5. Start the previous image with the same `TREK_DB_URL`.
On a server you administer, dropping the database and creating it again with the same owner, then loading the copy with `pg_restore --no-owner --no-privileges --single-transaction -d <url> <copy>`, works as well.
Loading the copy with `pg_restore -d` into a database you dropped and created again does not work: the copy holds TREK's schema by name, so `pg_restore` creates `public` again, stops at `schema "public" already exists` and rolls the whole load back. Use the steps above, which clear the schema instead of the database.
A TREK image without PostgreSQL support cannot read this database at all. It would start on a new SQLite file instead. An image from 5.0 on that refuses a newer database names the copy it can run, if one is in the data directory.