From bb356127ddc7f9ea735e287180057400f1631889 Mon Sep 17 00:00:00 2001 From: erdgeist Date: Sun, 9 Aug 2026 23:37:59 +0200 Subject: Document loading the schema as the install path db/schema.rb is in the repository, so a fresh install loads it rather than replaying migrations. db:setup and db:reset are safe; db:migrate is for an existing installation. The search_vector trigger is reinstalled by a db:schema:load hook and at boot, so a fresh install needs nothing further. A restore from a dump that predates the trigger needs pages:backfill_search_vector, now listed under one-shot tasks. The test database is no longer created by hand: Rails' db:test:prepare drops and recreates it from database.yml. --- INSTALL.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 55bf768c..bad2c271 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -109,8 +109,6 @@ ALTER ROLE rails CREATEDB; CREATE DATABASE cccms_dev OWNER rails ENCODING 'UTF8' LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; -CREATE DATABASE psql_test OWNER rails ENCODING 'UTF8' - LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8' TEMPLATE template0; ``` `CREATEDB` is needed because the test suite creates and drops its own @@ -153,18 +151,25 @@ production: Cccms::Application.config.secret_key_base = "<64 hex chars, e.g. from `rails secret`>" ``` -### 4a. Migrate. Never load the schema. +### 4a. Load the schema + + bundle exec rails db:schema:load - bundle exec rails db:migrate +`db/schema.rb` is in the repository and is the authoritative description +of the database. Replaying the migration chain is not a supported route: +the oldest migrations predate Rails 4, and some columns were only ever +applied by hand. `db:setup` and `db:reset` are safe. -Do not run `db:setup` or `db:schema:load`. +`bundle exec rails db:migrate` is for an existing installation — see the +deploy sequence in §7. -`db/schema.rb` is gitignored, and it could not be used even if it were -present: the full-text `search_vector` column is maintained by a PostgreSQL -trigger, and Ruby's schema format cannot express triggers. A schema-loaded -database gets the column and its GIN index with nothing populating them, -and site search then silently returns no results. Migrations are the only -complete record of the structure. +The full-text `search_vector` column is maintained by a PostgreSQL trigger, +which Ruby's schema format cannot express. `db:schema:load` reinstalls it +through a rake hook, and the application reinstalls it at boot, so a fresh +install needs nothing further. A database restored from a dump taken before +the trigger existed has rows it cannot repair, because the trigger fires +only on insert or update. You have to run `pages:backfill_search_vector` +once after such a restore. ## 5. First start @@ -296,6 +301,9 @@ old Ruby. second factor from the shell when every administrator is locked out. Deliberately unwitnessed — there is no actor to attribute a shell command to. +- `pages:backfill_search_vector` fills `search_vector` for rows that have + none, and installs the trigger first. Needed after restoring a dump that + predates the trigger; harmless otherwise, since it only fills nulls. Logs are in `log/`, gitignored. The action log inside the application at `/admin/log` records who changed what; `log/production.log` records -- cgit v1.3