Database

Migrations, operational scripts, and database maintenance for Pages CMS.

Pages CMS stores app state in PostgreSQL: auth data, collaborators, parsed config, and cache metadata. Content itself stays in GitHub.

Migrations

Generate a migration when the schema changes:

npm run db:generate

Apply migrations with:

npm run db:migrate

npm run build also runs migrations through postbuild.

Use manual npm run db:migrate when:

  • setting up local development,
  • deploying on platforms where postbuild is skipped,
  • applying migrations before switching traffic to a new deployment.
Table Purpose
config Parsed .pages.yml plus its SHA.
cache_file Cached collection/media rows.
cache_file_meta Branch and folder snapshot state.
cache_permission Cached repo permission checks.

Database scripts

Script Purpose Typical use
npm run db:clear-cache Clears cache tables used for repository/config/permission caching. Safe when cache state is stale or corrupted. GitHub remains the source of truth.
npm run db:collaborators:export -- --output=collaborators.csv Exports collaborators to CSV. Move collaborators to a new deployment/database.
npm run db:collaborators:import -- --input=collaborators.csv Imports collaborators from CSV. Restore/migrate collaborator assignments.

Operational note

After cache-logic upgrades, it can be worth running npm run db:clear-cache once so old cached rows do not survive into the new behavior.

Caching Migrating collaborators