Connect your app to a PocketBase backend

What this means

What this means

CM Cloud provisions PocketBase v0.23 or newer. In v0.23 the old admin API was merged into a built-in _superusers collection, so the admin login endpoint moved. Apps written against older PocketBase (v0.22 and earlier) that call /api/admins/auth-with-password receive a 404 Not Found and cannot authenticate, so any setup or migration code that creates collections never runs. Regular end-user and custom-collection auth endpoints are unchanged. The same v0.23 update also changed the collection-creation API: collection fields moved from the old "schema" array to a "fields" array, and field properties are now flattened (no nested "options" object). Code that still posts a "schema" payload creates a collection with no fields, so any index referencing those columns fails with a 400 "no such column" error. You can seed collections two ways: import a full snapshot in one call with PUT /api/collections/import (the same JSON the admin dashboard exports under Settings → Import collections), or create them individually with POST /api/collections. Run whichever you choose from your app's startup code so it re-executes automatically on every redeploy.

Before you start

Before you start

Know your PocketBase URL (for example https://pocketbase.yourdomain.com), your superuser email and password (created at /_/ the first time you open the dashboard), and which PocketBase version your client library targets. Set the PocketBase URL and credentials as environment variables in the deploy form instead of hard-coding them.

Step-by-step guidance

Step-by-step guidance

1. Confirm the version: open https://your-pocketbase-domain/api/health — CM Cloud runs PocketBase v0.23 or newer.
2. For admin/superuser login call POST /api/collections/_superusers/auth-with-password — NOT the old /api/admins/auth-with-password, which returns 404 on v0.23+.
3. Send the body {"identity": "<superuser-email>", "password": "<superuser-password>"} and read the returned token from the response.
4. For regular end-user login keep using /api/collections/users/auth-with-password — that endpoint is unchanged.
5. For any custom auth collection (for example staff) use /api/collections/<collection>/auth-with-password.
6. Store your PocketBase URL and superuser credentials as environment variables in the deploy form (commonly POCKETBASE_URL, POCKETBASE_ADMIN_EMAIL, POCKETBASE_ADMIN_PASSWORD). Environment variables persist across redeploys and are never committed to your repository.
7. If you use an official PocketBase SDK, upgrade it to a version that targets v0.23+ — recent SDKs call the superuser endpoint when you use pb.collection('_superusers').authWithPassword(...).
8. Redeploy your app and check the runtime logs: a successful superuser login means your setup/migration code that creates collections will run.
9. When creating collections via POST /api/collections, use the v0.23 format: send fields under "fields" (not "schema"), and put properties like maxSelect, values, min, max, pattern, collectionId, and cascadeDelete directly on each field — not nested under an "options" object.
10. When reading or patching an existing collection (for example adding fields to the built-in users collection), read its field list from "fields", not "schema".
11. If a collection create returns 400 with "no such column" on an index, your fields were sent in the old "schema" format and were ignored — switch the payload to "fields" so the columns exist before the index is built.
12. v0.23 no longer adds created/updated system fields automatically. If your app sorts or filters by created (or updated), declare them explicitly as autodate fields in the collection's fields array — for example {"name": "created", "type": "autodate", "onCreate": true, "onUpdate": false} and {"name": "updated", "type": "autodate", "onCreate": true, "onUpdate": true}. Otherwise list queries using created return 400 Bad Request even though the collection exists.
13. Adding a field to a collection definition does not change collections that already exist — typical setup code skips collections that are already present ("if it exists, skip"). So if you add fields (like the created/updated autodate fields) after a collection was already created, the new fields are never applied and queries still fail. Fix it one of three ways: delete the existing collection in the admin dashboard at /_/ and let your setup recreate it (only safe if it has no data you need), add the fields manually at /_/, or make your setup PATCH existing collections to add missing fields (the same approach used for the built-in users collection).
14. The most reliable place to run collection setup is your app's startup hook — FastAPI lifespan, before app.listen() in Express, AppConfig.ready() in Django, or boot() in Laravel. CM Cloud restarts your app on every deploy, so startup code runs automatically on each deploy. Wrap it in try/except (or try/catch) so a transient PocketBase hiccup logs an error instead of crashing the boot — the next deploy retries.
15. If you already have a collections snapshot (admin dashboard → Settings → Import collections shows the JSON), you can import the whole snapshot in one request instead of coding each collection by hand. Commit that exported JSON to your repository, for example as pb_schema.json.
16. After the superuser login (step 2), send PUT /api/collections/import with the body {"collections": <your exported array>, "deleteMissing": false}. This is additive and idempotent — it creates or updates the collections in the file and runs safely on every deploy without touching existing records.
17. Keep deleteMissing set to false unless you deliberately want the live database to become an exact mirror of the file. deleteMissing: true DELETES any collection (and all its records) that is not present in the file — only use it when that is exactly what you intend.
18. Redeploy and check the runtime logs: you should see the import (or per-collection setup) succeed once per boot. Because the operation is idempotent, your existing data is preserved on every subsequent deploy.

What CM Cloud support will review

What CM Cloud support will review

Support can confirm the PocketBase version, that the admin dashboard at /_/ is reachable, and that a superuser account exists. Support does not edit your application code or change your SDK version.

What is not automated yet

What is not automated yet

CM Cloud does not rewrite your application's PocketBase calls. Collections, API rules, and superuser accounts are created by you — through the admin dashboard at /_/ or your own setup code — not automatically. Your superuser email and password are whatever you set at /_/; they are not generated for you.