Skip to content

Version History

Every change to a PocketBase instance’s pb_hooks, pb_migrations and pb_public is saved as a numbered revision: who made it, from where, and which files it touched. Nothing needs setting up and you don’t need a GitHub repository — history starts by itself, with the files the instance has when you first open it.

A revision comes from wherever the change was made:

Source Example
Portal Saving, uploading or deleting a file in the Code page
pbc CLI pbc pocketbase deploy, pbc pocketbase hooks push
AI assistant write_cloud_files or edit_cloud_file through the MCP server
GitHub A push to a connected repository
Instance A migration PocketBase wrote itself after a schema change in the admin panel or through the API

Migrations an instance writes itself are picked up within about ten minutes, or as soon as you open the history.

Revisions and deployments

A change that reaches the instance is also a deployment: saving a hook, uploading files, restoring a revision, a CLI deploy, an assistant’s write, or a GitHub deploy. It appears under Deployments on the instance’s page with who made it, how, the commit when there is one, and its revision number. Each deployment’s … menu has View files in History, and each revision’s … menu in the History panel has View deployment. Drafts (a draft hook or a migration draft) never reach the instance, so they are neither; neither is a migration the instance wrote itself.

When a change stops the instance from starting, its deployment is marked failed with the error line.

Viewing the history

Using the portal

  1. Open the instance and go to Code under Build
  2. Click the clock icon on the left to open the History panel. Revisions are listed newest first, with who made them, from where, and when
  3. Click a revision to list the files it added (A), changed (M) and removed (D)
  4. Click a file to compare it side by side with the version before

Click the folder icon to go back to the files.

Using the CLI

pbc pocketbase revisions ls                        # newest first
pbc pocketbase revisions diff 12                   # what revision 12 changed
pbc pocketbase revisions diff 12 --against 8       # compare two revisions
pbc pocketbase revisions show 12 pb_hooks/main.pb.js

Run them in a directory bound to the instance, or add --name <instance>.

Restoring a revision

A restore has two modes:

Mode What goes back What stays
Files only Hooks and pb_public Migrations and the database schema
Files and schema Hooks, pb_public, and the schema: migrations added since are reverted with their down parts, newest first Records the down parts don’t touch

Changing hooks restarts the instance. With Files and schema the instance is stopped while the migrations are reverted, and a migration’s down part can drop a collection together with its records. Before reverting, the database is copied aside; if a down part fails, that copy is put back and nothing else changes. Files and schema needs PocketBase 0.32.0 or later and automigrate on.

A restore is saved as a new revision, so you undo it the same way: restore the revision before it. Nothing is deleted: the revisions between the one you restore and the latest stay in the history.

Rolling back a deployment under Deployments does the same as restoring its revision with Files only, and shows as a Rollback deployment.

Using the portal

  1. In the Code page’s History panel, open the revision to go back to
  2. Click Restore #N above the comparison, or Restore this version in the revision’s … menu
  3. Pick Files only or Files and schema, check the list of changes, and click Restore

Using the CLI

pbc pocketbase revisions restore 12            # files only
pbc pocketbase revisions restore 12 --schema   # files and schema

Both print the changes first and ask before restoring; pass --yes in scripts.

An AI assistant connected through the MCP server uses preview_restore_revision and restore_revision, and asks you before restoring.

When a change stops the instance from starting

After a change to hooks or migrations — saving in the Code page, pbc pocketbase hooks push, a redeploy from the CLI, a portal upload or a GitHub push, an AI assistant’s deploy_hooks, or a restore — the platform waits for the instance to answer. If PocketBase exits instead — a typo in a hook, say — the previous hooks and pb_public are put back as a new revision and the error names the file and line, for example pb_hooks/main.pb.js:3:1. Fix it and deploy again.

A new migration that fails is removed the same way. PocketBase runs each migration in a transaction, so one that fails never changed the database and is safe to take out. A migration that did run is kept, since the database already has its changes: undo it with a Files and schema restore.

Instances that deploy from GitHub

Each deploy from GitHub, from a push or Deploy now, is a revision titled with the commit’s first line. Below it the panel shows the commit’s author (their GitHub login, or their name when the commit is not linked to a GitHub account) and the short commit SHA. Open commit on GitHub in the revision’s … menu opens the commit. A push that changes nothing in pb_hooks, pb_migrations or pb_public adds no revision.

pbc pocketbase deploy run inside a git checkout does the same: the revision is titled with the commit and credits its author. If the deployed folder has uncommitted changes, the title says so, and the commit link appears once the commit is pushed to GitHub. Other changes show who made them: you, a teammate by name, or Platform for changes PocketBase made itself.

Pushing changes to GitHub

When an instance deploys from a connected repository, the repository stays the source of truth, but nothing is written to it on its own. A change you make in the portal, with the CLI or through an AI assistant is applied to the instance at once and stays only there until you push it. The next push to the branch replaces anything you have not pushed.

To push, click Push (N) in the Code page’s toolbar, where N counts the files GitHub does not have yet: the files changed since the last GitHub deploy or push. Check the list, write a commit message if you like, and click Commit and push. The files are committed to the linked branch at the paths pbc.json names; the instance already runs them, so it is not deployed again. An AI assistant pushes with push_to_github, and only when you ask it to.

The platform never overwrites work in the repository. When the branch changed one of the same files since the instance last had it, the push opens a pull request instead and names the files. To review every push before it reaches the branch, open the repository’s Edit settings and turn on Review changes made in PocketBase Cloud: each push then opens a pull request.

pbc never pushes for you, since you work in the repository there; it warns that the next push to the branch will replace the change.

Downloading the files

Take the files out to keep them locally or put them in git.

Using the portal

In the Code page, choose Download zip in the … menu at the top right for the current files, or in a revision’s … menu in the History panel for that revision.

Using the CLI

pbc pocketbase pull                  # current files into this directory
pbc pocketbase pull --revision 12    # as they were in revision 12
pbc pocketbase pull --dir ./backup   # somewhere else

pull asks before overwriting local files that differ and leaves files that exist only locally alone.

What history does not keep

  • Older revisions. On Starter and Pro, history keeps the last 100 revisions and every revision from the last 30 days. On Free, it keeps the last 10 revisions and every revision from the last 7 days. The plan of the instance’s owner decides, so a downgrade to Free shortens history at the next daily cleanup. Older revisions are removed once a day; download a zip to keep one longer.
  • Records and uploaded files: those are your data, covered by Continuous Backup.
  • pb_data and environment variables.

Next steps