You can explore the Database guide, Collection operations and Record operations for more details how to interact with the database. You can also find some examples further below in this guide.
PocketBase comes with a builtin DB and data migration utility, allowing you to version your DB structure, create collections programmatically, initialize default settings, etc.
Because the migrations are regular Go functions, besides applying schema changes, they could be used also to adjust existing data to fit the new schema or any other app specific logic that you want to run only once.
And as a bonus, being .go files also ensure that the migrations will be embedded seamlessly in
your final executable.
You can find all available config options in the
migratecmd
subpackage.
To create a new blank migration you can run migrate create.
The above will create a new blank migration file inside the default command migrations directory.
Each migration file should have a single m.Register(upFunc, downFunc) call.
In the migration file, you are expected to write your "upgrade" code in the upFunc callback.
The downFunc is optional and it should contain the "downgrade" operations to revert the
changes made by the upFunc.
Both callbacks accept a transactional core.App instance.
You can explore the Database guide, Collection operations and Record operations for more details how to interact with the database. You can also find some examples further below in this guide.
To make your application aware of the registered migrations, you have to import the above
migrations package in one of your main package files:
New unapplied migrations are automatically executed when the application server starts, aka. on
serve.
Alternatively, you can also apply new migrations manually by running migrate up.
To revert the last applied migration(s), you can run migrate down [number].
When manually applying or reverting migrations, the serve process needs to be restarted so
that it can refresh its cached collections state.
The migrate collections command generates a full snapshot of your current collections
configuration without having to type it manually. Similar to the migrate create command, this
will generate a new migration file in the
migrations directory.
By default the collections snapshot is imported in extend mode, meaning that collections and
fields that don't exist in the snapshot are preserved. If you want the snapshot to delete
missing collections and fields, you can edit the generated file and change the last argument of
ImportCollectionsByMarshaledJSON method to true.
All applied migration filenames are stored in the internal _migrations table.
During local development often you might end up making various collection changes to test different approaches.
When Automigrate is enabled this could lead in a migration history with unnecessary intermediate
steps that may not be wanted in the final migration history.
To avoid the clutter and to prevent applying the intermediate steps in production, you can remove (or squash) the unnecessary migration files manually and then update the local migrations history by running:
The above command will remove any entry from the _migrations table that doesn't have a related
migration file associated with it.
For all supported record methods, you can refer to Record operations .
You can also create the initial super user using the
./pocketbase superuser create EMAIL PASS
command.
For all supported collection methods, you can refer to Collection operations .