Deploying PocketBase
PocketBase Cloud gives you a fully managed PocketBase instance with automatic HTTPS, backups, and a dedicated admin panel. You can create one from the portal or from your terminal — both produce the same thing.
Prerequisites
- An active PocketBase Cloud account with a plan subscription — your first project is created at signup (Projects)
- For the CLI path:
pbcinstalled and logged in (Installing the CLI)
Step 1: Create the instance
Using the portal
- Open your project from the Projects page and click the PocketBase tab
- Click New PocketBase
- Keep the auto-generated name or type your own (e.g.,
apiormain-db) - On Starter, pick a region (or leave Any region); on Pro, pick your dedicated compute. Free is placed automatically.
- Under Advanced Configuration, optionally tune the runtime flags (dev mode, hooks pool size, query timeout)
- Click Create
You’ll be taken to the provisioning page, where you can watch the progress.
Using the CLI: an empty instance
If you only want the database — from a script, from a CI step, or before there
is anything to deploy — create provisions one and stops there:
pbc pocketbase create my-app-db
Nothing is built, packaged, or uploaded. The instance is recorded in this
directory’s pbc.json, exactly as a deploy would record it, so shipping files to
it later takes no flags:
# …add pb_hooks/, pb_migrations/, pb_public/ when you have them
pbc pocketbase deploy # no --name: the binding is already there
--env <name> records it under another environment (default: production, or
the file’s own default). A directory bound to frontends or backends is refused,
and so is an environment that already names an instance — repointing it would
leave the old one with nothing pointing at it.
A name already used by an instance in the project is refused rather than
duplicated — redeploy that one with pbc pocketbase deploy --name my-app-db.
create takes the same --location, --compute, --pb-version,
--admin-email and --admin-password flags as the deploy below, plus
three runtime flags and a restore flag:
| Flag | What it does |
|---|---|
--dev <true|false> |
Dev mode: request log traces and verbose debugging output |
--hooks-pool <1-100> |
Concurrent JS engine instances pool (default 15) |
--query-timeout <1-3600> |
Maximum query execution timeout, in seconds (default 30) |
--backup <file.zip> |
Restore a PocketBase backup ZIP during creation (max 150 MB). Existing superusers are preserved, so it cannot be combined with --admin-email / --admin-password |
Restoring a backup at creation
A backup ZIP (from Settings → Backups in any instance’s admin panel, or
from pbc admin settings backup download) can seed a new instance — schema,
records, uploaded files, and superusers arrive as they were:
Using the portal
- On the create form, under Source, choose Restore Backup
- Upload the backup
.zip(max 150 MB). The instance name is suggested from the file name — change it under Advanced configuration if you like - Click Deploy. The preserved superusers stay valid; the printed credentials step is skipped because PocketBase Cloud never sees them
Using the CLI
pbc pocketbase create restored-db --backup backup.zip
Admin login: preserved from backup; credentials are not available to PocketBase Cloud.
Log in with the same superuser email and password the backup was taken with.
Using the CLI: deploying a directory
Run deploy in the directory holding your PocketBase project — the one with
pb_public, pb_hooks, and pb_migrations (see
Local Development for how to
scaffold one). None of the three directories is required: a directory holding
none of them still deploys, sends no archive at all, and creates the instance
empty — the same result as pbc pocketbase create, reached from a directory.
cd db
pbc pocketbase deploy --name my-app-db
pbc deploy --name my-app-db does the same: any of pb_hooks,
pb_migrations, or pb_public identifies the directory as a PocketBase
project, so the CLI runs this command for you. See
One deploy command for all three.
The CLI packages the directory, creates the instance, waits for it to come up, and prints the URL plus a generated superuser login:
Creating my-app-db (environment: production)…
status: creating
status: running
Done: my-app-db is running.
https://my-app-db.pocketbasecloud.com
Admin login: [email protected] / xxxxxxxxxxxx
| Flag | What it does |
|---|---|
--name <name> |
Which instance to deploy. Asked for when omitted and nothing is linked. |
--location <loc> |
Region for the deployment (Starter) |
--compute <id> |
Which compute to deploy onto. Asked for on Pro, and in an organization’s project, when there is more than one — the owner’s dedicated compute is never auto-selected. List them with pbc compute ls. (Formerly --server, still accepted.) |
--pb-version <v> |
PocketBase release to install. Defaults to the pin in pbc.json. |
--skip-env |
Don’t push the neighbouring .env |
--zip <file> |
Upload an archive you built yourself |
--env <name> |
Which pbc.json environment to target (staging, production, …) |
Provisioning typically takes 30–60 seconds on either path.
Step 2: Grab the credentials
A new instance gets a superuser account: your account email, and a generated password.
Using the portal
The instance’s Settings page shows the admin email and password under Admin access.
Using the CLI
The password is printed once, when the deploy finishes. To read it later:
pbc pocketbase info --name my-app-db
Override either credential at creation with --admin-email /
--admin-password.
Step 3: Redeploy
Deploying again replaces the running version.
Using the portal
Open the instance and click Deploy, then drop the project files or a ZIP holding them. The dialog previews what will go up and reports what was stripped as local junk. What it may contain mirrors what the CLI ships:
pb_migrations/is merged with the migrations already on the instance, so the ones its admin UI generated are kept. New ones apply on the restart that follows.pb_public/is replaced wholesale, so files dropped from your build stop being served.pb_hooks/is ignored by the upload — hooks are edited in place on the Code tab, or pushed withpbc pocketbase deploy.pb_data/and the PocketBase binary are never writable from an upload.
To change a few files rather than redeploy, use the Code tab. It works
like a code editor: the icons on the far left switch the side panel between
Files (pb_hooks, pb_migrations and pb_public in one tree) and
History, and the shield opens environment secrets. Each folder’s … menu
holds its actions, such as New migration or Upload files.
- pb_hooks: edit, Save as a draft and Deploy, as before. The API tester and the CLI command are in the … menu at the top right.
- pb_public: text files such as
index.htmlor CSS open in the editor, and Save puts the change live straight away. Images show a preview. Above the editor, the upload icon replaces the file and the bin deletes it. - pb_migrations: migrations already on the instance are read-only, since
PocketBase may have run them and writes its own when you change the schema in
its admin UI. To add one, choose New migration and give it a name: the
file gets PocketBase’s timestamp prefix and a
migrate(up, down)skeleton, and stays a Draft you can edit and Save as often as you like. Drafts are kept with the instance, so teammates see them too. Deploy sends every draft at once; PocketBase runs them in file name order on the restart that follows. Upload migrations adds.jsfiles you already have. A migration that fails changes nothing: the platform removes it again, starts the instance and names the line that failed, and a deployed draft stays a draft so you can fix it.
Each change is saved as a revision. Open the History panel to compare any file with its previous version or restore an earlier revision; see version history.
Using the CLI
The first deploy records the instance in pbc.json in that directory, so from
then on:
pbc pocketbase deploy # redeploys the linked instance
pbc pocketbase deploy --dry-run # shows what would upload, changes nothing
A redeploy uploads only the files the instance does not already have, so changing one hook sends one file. Every deploy is saved as a revision in the instance’s Version History; a first deploy and a portal upload also appear in the Deployments list.
On a redeploy a single file can be up to 1 MB on Free and 100 MB on Starter and Pro. Keep larger files, and anything your users upload, in a file field instead.
To leave files out, list them in a .pbcignore next to pbc.json, one pattern
per line as in .gitignore: a name matches at any depth, a trailing / matches
folders only, and a pattern with a / is matched from pb_public/,
pb_hooks/ or pb_migrations/. Source maps (*.map) are left out by default;
add !*.map to ship them. The deploy prints how many files were left out.
# .pbcignore
uploads/
pb_public/drafts
!vendor.js.map
Try a change on a preview first
A deploy can go to a preview instead of live: a copy of your project, with its own address, that starts from a copy of your live data. Every website and service in the project gets a copy in it too, and so does one you add later; each copy gets the preview’s PocketBase address. Previews and environments need a project with one PocketBase. Free gets one preview at a time for 24 hours with a small sample of the data; Starter gets 2 for 3 days and Pro 10 for 7 days. Try the change there, then ship it to live or discard it. Live is not touched until you ship.
- Portal: in the Deploy dialog pick Preview first (it is picked for you when the deploy adds a migration). On the Code page, Try on a preview sends your unsaved edits to a new preview. The environment menu at the top switches the whole project between live, its environments and its previews: the Overview, websites, services and their pages follow it.
- CLI:
pbc pocketbase deploy --preview --preview-name fix-loginprints the preview’s address; run it again to deploy to the same preview, thenpbc pocketbase preview shiporpbc pocketbase preview rm. - AI assistant (MCP): ask it to try a change on a preview first. It uses
create_preview, works on the preview by name, shows youdiff_previewand ships only when you say so.
The copy stays small. Under Data pick Small (the default, about 100
rows per collection), Medium (about 1,000) or Full copy, which is
only for databases up to 100,000 rows. Rows are
picked so they match each other: a product’s reviews come with it, and every
row a kept row links to comes too. Add your own email under Always keep
these users to sign in to the preview as yourself. You can also keep a
collection whole or bring its schema only. Uploaded files are read from live
instead of copied, and logs stay behind. A trimmed copy is still your real
data. The CLI takes --preview-size and --preview-keep-user.
Live keeps running while the copy is made, and a copy that takes longer than 30 seconds is stopped so it never slows live down; choose Small and try again.
Crons, email, S3 storage and scheduled backups are off on a preview, so it
never acts on real services or writes into live’s buckets. Calls your hooks
make to other services are real.
Shipping applies the hooks, migrations and pb_public that changed on the
preview; it never copies the preview’s data back. If live changed since the
preview was made, Update preview first brings live’s newer files into the
preview and keeps your changes (pbc pocketbase preview update). When you and
live edited different parts of the same file, both edits are kept. When you
edited the same lines, the file is marked to resolve: open Resolve to see
live’s version (or the one before either change) beside yours, then keep
yours, take live’s, or edit the result. In the CLI, pbc pocketbase preview conflicts --out <folder> writes the versions to disk and pbc pocketbase preview resolve <file> --mine|--live|--from <path> settles each one. Shipping
waits until none are left. A preview lasts 3
days on Starter and 7 on Pro, and Keep longer restarts that time.
Nothing you change on a preview is lost. Every change to its hooks,
migrations and public files is kept as a draft on the live instance, even
after the preview is discarded or expires. A draft takes your preview’s name
(or, for preview-1 and the like, the name of its first changed file), so
name previews after what they do, or rename the draft later. Open Drafts from the
environment switcher (or pbc pocketbase preview drafts) and reopen one as a
new preview on top of the latest live (pbc pocketbase preview reopen --draft <name>). Drafts keep files, not records.
What the platform does for you
On either path, PocketBase Cloud automatically:
- Selects a server based on your plan and current capacity (Free and Starter), or uses your dedicated compute (Pro)
- Assigns a port and generates superuser credentials
- Provisions the instance and sets up DNS
- Issues an HTTPS certificate
Once complete, your instance is live at:
https://<instance-name>.pocketbasecloud.com
and its admin panel at:
https://<instance-name>.pocketbasecloud.com/_/
The detail page lists the platform URL plus the admin and API URLs, and a verified custom domain next to them when one is set.
A brand-new domain can take a few minutes to answer while its certificate is issued, even after the status reads running. An error right after a deploy usually means “wait a moment”, not “the deploy failed”.
What gets deployed
The CLI ships the directory’s pb_public, pb_hooks, and pb_migrations on
every deploy, so your schema and hooks are in place from the first boot and stay
in step afterwards. Their locations come from the build block in pbc.json:
// db/pbc.json
{
"build": {
"pbPublic": "pb_public",
"pbHooks": "pb_hooks",
"pbMigrations": "pb_migrations"
}
}
On a redeploy the same directories go up, but only the files whose content
the instance does not have yet are uploaded. Hooks are written so the portal’s
hook editor stays in sync, and the platform installs pb_migrations and
pb_public on the running instance. Migrations are merged — files already on the instance,
including ones its admin panel generated, are kept — while pb_public is
replaced, so files dropped from your build stop being served. Your database
is never touched, and new migrations are applied by the restart that follows.
Managing your instance
From the portal’s instance detail page you can view connection details, edit hooks, stream logs, manage environment variables, and delete the instance. The CLI equivalents:
pbc pocketbase ls # statuses at a glance
pbc pocketbase info --name my-app-db # URL, version, server, admin login
pbc logs pocketbase --name my-app-db -f
pbc pocketbase rm --name my-app-db
See Managing Your Instance for backups, exports, and instance settings.
Using PocketBase hooks
Hooks let you add custom server-side logic. In the portal, use the
instance’s Code tab; from the CLI, keep them in pb_hooks/ and push with
pbc pocketbase deploy or pbc pocketbase hooks push. Either way they can add API
routes, react to record changes, schedule cron jobs, and send email — see
Extending with Hooks.