PocketBase migrations and hooks (pb_migrations / pb_hooks)

What this means

What this means

PocketBase is an open-source backend written in Go. A CM Cloud PocketBase deployment installs the PocketBase binary, creates a persistent pb_data/ directory, and — if you supply a Git repository — clones it and loads your pb_migrations/ and pb_hooks/ from it. Your data lives at the app level, not inside a release, so it survives redeployments and rollbacks. File storage is local to the runtime VM (not S3). Deploying without a repository still gives you a working, empty PocketBase you configure entirely through the dashboard at /_/.

Before you start

Before you start

Decide whether you want a code-defined backend or a dashboard-defined one. For code-defined, push a Git repository containing pb_migrations/ (collection schema and API rules) and/or pb_hooks/ (custom endpoints, scheduled jobs, mail) and paste its URL into the Artifact Reference field; private repos also need a GitHub token with repo scope. For dashboard-defined, leave that field empty and create everything in /_/. You do not need to install Go or compile anything.

Step-by-step guidance

Step-by-step guidance

1. Keep pb_migrations/ and pb_hooks/ at the root of the repository (or of the subdirectory you deploy, for a monorepo).
2. Deploy the PocketBase app and paste your repository URL into the Artifact Reference field. For a private repo, also supply a GitHub token with repo scope.
3. Check the deploy log. It states plainly whether each directory was found — 'Loaded pb_migrations/ from your repository (N file(s))' or 'No pb_hooks/ in your repository — skipping'.
4. Migrations are applied automatically when the service starts. Hooks are loaded at the same time; a routerAdd endpoint is reachable immediately.
5. Use current timestamps in migration filenames. A file named with a timestamp older than PocketBase's own built-in migrations is skipped without any error — the most common reason a migration 'does nothing'.
6. Take care attaching a repository to an existing app. Migrations run against the database you already have, and a migration that creates a collection you previously made by hand will fail and can stop the service. The deploy log warns you when the app already has a database.
7. Your data in pb_data/ is never touched by a redeployment — it lives at the app level, outside the release directory.

What CM Cloud support will review

What CM Cloud support will review

Support can confirm what your deployment is running: whether the repository was cloned, which directories were found, the exact flags the service was started with, and whether a migration failed at startup.

What is not automated yet

What is not automated yet

Support cannot write or debug your migrations and hooks — they are your application code. A migration that fails at startup will stop the service; the deploy log and the app's logs will show the error. Migrations are never rolled back automatically, and pb_data/ is not reverted if a migration goes wrong, so test schema changes against a non-production app first.