Migrations

FrogBot exposes a full suite of migration controls available for your use. Run them with the frogbot command that your app installs, through npx (or pnpm exec, yarn, bunx) in your project directory:

npx frogbot migrate:status

Migration file contents

FrogBot stores all created migrations in a folder that you can specify. By default, migrations are stored in ./src/migrations. A migration file has two exports - an up function, which is called when a migration is executed, and a down function that will be called if for some reason the migration fails to complete successfully. The up function should contain all changes that you attempt to make within the migration, and the down should ideally revert any changes you make. Here is an example migration file:

import { MigrateUpArgs, MigrateDownArgs } from '@frogbotai/your-db-adapter'

export async function up({ frogbot, req }: MigrateUpArgs): Promise<void> {
  // Perform changes to your database here.
  // You have access to `frogbot` as an argument, and
  // everything is done in TypeScript.
}

export async function down({ frogbot, req }: MigrateDownArgs): Promise<void> {
  // Do whatever you need to revert changes if the `up` function fails
}

Using Transactions

When migrations are run, each migration is performed in a new transaction for you. All you need to do is pass the req object to any Local API or direct database calls, such as frogbot.db.updateMany(), to make database changes inside the transaction. Assuming no errors were thrown, the transaction is committed after your up or down function runs. If the migration errors at any point or fails to commit, it is caught and the transaction gets aborted. This way no change is made to the database if the migration fails.

Using database directly with the transaction

Additionally, you can bypass FrogBot’s layer entirely and perform operations directly on your underlying database within the active transaction:

MongoDB:

import { type MigrateUpArgs } from '@frogbotai/db-mongodb'

export async function up({
  session,
  frogbot,
  req,
}: MigrateUpArgs): Promise<void> {
  const posts = await frogbot.db.collections.posts.collection
    .find({ session })
    .toArray()
}

Postgres:

import type { MigrateUpArgs } from '@frogbotai/db-postgres'
import { sql } from '@frogbotai/db-postgres/drizzle'

export async function up({ db, frogbot, req }: MigrateUpArgs): Promise<void> {
  const { rows: posts } = await db.execute(sql`SELECT * from posts`)
}

SQLite:

In SQLite, transactions are disabled by default. More.

import { type MigrateUpArgs, sql } from '@frogbotai/db-sqlite'

export async function up({ db, frogbot, req }: MigrateUpArgs): Promise<void> {
  const { rows: posts } = await db.run(sql`SELECT * from posts`)
}

Migrations Directory

Each DB adapter has an optional property migrationDir where you can override where you want your migrations to be stored/read. If this is not specified, FrogBot will check the default and possibly make a best effort to find your migrations directory by searching in common locations ie. ./src/migrations, ./dist/migrations, ./migrations, etc. All database adapters should implement similar migration patterns, but there will be small differences based on the adapter and its specific needs. Below is a list of all migration commands that should be supported by your database adapter.

Commands

Command	Description
`frogbot migrate`	Runs every migration that hasn’t run yet.
`frogbot migrate:create [name]`	Creates a migration file from the schema changes since the last migration.
`frogbot migrate:status`	Lists which migrations have run and which haven’t.
`frogbot migrate:down`	Rolls back the last batch of migrations.
`frogbot migrate:refresh`	Rolls back every migration that has run, then runs them all again.
`frogbot migrate:reset`	Rolls back every migration.
`frogbot migrate:fresh`	Drops everything in the database, then runs every migration.

Flag	Applies to	Description
`--name <name>`	`migrate:create`	Name of the migration file. Same as the positional `name`, and takes precedence over it. Also accepts `--name=<name>`.
`--file <path>`	`migrate:create`	Creates the migration from a predefined migration instead of the schema: a module path or package export that provides `upSQL`, `downSQL`, and `imports`.
`--skip-empty`	`migrate:create`	On Postgres and SQLite, exits without creating a file when no schema changes are detected, instead of asking whether to create a blank one. On MongoDB, which doesn’t detect schema changes, no file is written.
`--force-accept-warning`	`migrate:create`, `migrate:fresh`	Answers yes to confirmation prompts. `migrate:fresh` drops the database without asking, and on Postgres and SQLite `migrate:create` writes a blank migration when there are no changes.
`--help`, `-h`	Every command	Prints usage.

When frogbot migrate runs without an interactive terminal, such as in CI, it fails if the database has schema changes pushed in development mode. Run it interactively to confirm those changes first.

Migrate

The migrate command will run any migrations that have not yet been run.

npx frogbot migrate

Create

Create a new migration file in the migrations directory. You can optionally name the migration that will be created. By default, migrations will be named using a timestamp.

npx frogbot migrate:create optional-name-here

See the flags table for --name, --file, --skip-empty, and --force-accept-warning.

Upgrading from earlier FrogBot versions

After upgrading, create the next migration from FrogBot’s upgrade migration instead of the schema:

npx frogbot migrate:create upgrade --file frogbot/migrations/upgrade-0.34

On Postgres and SQLite it makes the schema change, and on SQLite it also rebuilds changed tables without losing their rows. Earlier versions stored authors in createdByField() and lastModifiedByField() fields; they’re now the built-in createdBy and updatedBy fields. Remove those fields first: the migration copies each old author column into createdBy or updatedBy. Columns it can’t place are listed in the console and at the top of the file, set to null: assign each to 'createdBy' or 'updatedBy', or leave it to drop the column. The next migrate:create drops the old columns. On MongoDB it moves the createdBy and lastModifiedBy keys; edit the map at the top of the file for other names. Folders from earlier versions (payload-folders) aren’t carried over: files keep everything else, and come back unfiled.

Status

The migrate:status command will check the status of migrations and output a table of which migrations have been run, and which migrations have not yet run. frogbot migrate:status

npx frogbot migrate:status

Down

Roll back the last batch of migrations.

npx frogbot migrate:down

Refresh

Roll back all migrations that have been run, and run them again.

npx frogbot migrate:refresh

Reset

Roll back all migrations.

npx frogbot migrate:reset

Fresh

Drops all entities from the database and re-runs all migrations from scratch.

npx frogbot migrate:fresh

When to run migrations

Depending on which Database Adapter you use, your migration workflow might differ subtly. In relational databases, migrations will be required for non-development database environments. But with MongoDB, you might only need to run migrations once in a while (or never even need them).

MongoDB#mongodb-migrations

In MongoDB, you’ll only ever really need to run migrations for times where you change your database shape, and you have lots of existing data that you’d like to transform from Shape A to Shape B. In this case, you can create a migration by running pnpm frogbot migrate:create, and then write the logic that you need to perform to migrate your documents to their new shape. You can then either run your migrations in CI before you build / deploy, or you can run them locally, against your production database, by using your production database connection string on your local computer and running the pnpm frogbot migrate command.

Postgres#postgres-migrations

In relational databases like Postgres, migrations are a bit more important, because each time you add a new field or a new collection, you’ll need to update the shape of your database to match your FrogBot Config (otherwise you’ll see errors upon trying to read / write your data). That means that Postgres users of FrogBot should become familiar with the entire migration workflow from top to bottom. Here is an overview of a common workflow for working locally against a development database, creating migrations, and then running migrations against your production database before deploying. 1 - work locally using push mode FrogBot uses Drizzle ORM’s powerful push mode to automatically sync data changes to your database for you while in development mode. By default, this is enabled and is the suggested workflow to using Postgres and FrogBot while doing local development. You can disable this setting and solely use migrations to manage your local development database (pass push: false to your Postgres adapter), but if you do disable it, you may see frequent errors while running development mode. This is because FrogBot will have updated to your new data shape, but your local database will not have updated. For this reason, we suggest that you leave push as its default setting and treat your local dev database as a sandbox. For more information about push mode and prototyping in development, click here. The typical workflow in FrogBot is to build out your FrogBot configs, install plugins, and make progress in development mode - allowing Drizzle to push your changes to your local database for you. Once you’re finished, you can create a migration. But importantly, you do not need to run migrations against your development database, because Drizzle will have already pushed your changes to your database for you. 2 - create a migration Once you’re done with working in your FrogBot Config, you can create a migration. It’s best practice to try and complete a specific task or fully build out a feature before you create a migration. But once you’re ready, you can run pnpm frogbot migrate:create, which will perform the following steps for you:

We will look for any existing migrations, and automatically generate SQL changes necessary to convert your schema from its prior state to the new state of your FrogBot Config
We will then create a new migration file in your /migrations folder that contains all the SQL necessary to be run

We won’t immediately run this migration for you, however. 3 - set up your build process to run migrations Generally, you want to run migrations before you build FrogBot for production. This typically happens in your CI pipeline and can usually be configured on platforms like FrogBot Cloud, Vercel, or Netlify by specifying your build script. A common set of scripts in a package.json, set up to run migrations in CI, might look like this:

  "scripts": {
    // For running in dev mode
    "dev": "next dev",

    // To build your Next + FrogBot app for production
    "build": "next build",

    // A "tie-in" to FrogBot's CLI for convenience
    // this helps you run `pnpm frogbot migrate:create` and similar
    "frogbot": "cross-env NODE_OPTIONS=--no-deprecation frogbot",

    // This command is what you'd set your `build script` to.
    // Notice how it runs `frogbot migrate` and then `pnpm build`?
    // This will run all migrations for you before building, in your CI,
    // against your production database
    "ci": "frogbot migrate && pnpm build",
  },

In the example above, we’ve specified a ci script which we can use as our “build script” in the platform that we are deploying to production with. This will require that your build pipeline can connect to your database, and it will simply run the frogbot migrate command prior to starting the build process. By calling frogbot migrate, FrogBot will automatically execute any migrations in your /migrations folder that have not yet been executed against your production database, in the order that they were created. If it fails, the deployment will be rejected. But now, with your build script set up to run your migrations, you will be all set! Next time you deploy, your CI will execute the required migrations for you, and your database will be caught up with the shape that your FrogBot Config requires.

Running migrations in production

In certain cases, you might want to run migrations at runtime when the server starts. Running them during build time may be impossible due to not having access to your database connection while building or similar reasoning. If you’re using a long-running server or container where your Node server starts up one time and then stays initialized, you might prefer to run migrations on server startup instead of within your CI. In order to run migrations at runtime, on initialization, you can pass your migrations to your database adapter under the prodMigrations key as follows:

// Import your migrations from the `index.ts` file
// that FrogBot generates for you
import { migrations } from './migrations'
import { buildConfig } from 'frogbot'

export default buildConfig({
  // your config here
  db: postgresAdapter({
    //  your adapter config here
    prodMigrations: migrations,
  }),
})

Passing your migrations as shown above will tell FrogBot, in production only, to execute any migrations that need to be run prior to completing the initialization of FrogBot. This is ideal for long-running services where FrogBot will only be initialized at startup.

Environment-Specific Configurations and Migrations

Your configuration may include environment-specific settings (e.g., enabling a plugin only in production). If you generate migrations without considering the environment, it can lead to discrepancies and issues. When running migrations locally, FrogBot uses the development environment, which might miss production-specific configurations. Similarly, running migrations in production could miss development-specific entities. This is an easy oversight, so be mindful of any environment-specific logic in your config when handling migrations. Ways to address this:

Manually update your migration file after it is generated to include any environment-specific configurations.
Temporarily enable any required production environment variables in your local setup when generating the migration to capture the necessary updates.
Use separate migration files for each environment to ensure the correct migration is executed in the corresponding environment.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Migration file contents

Using Transactions

Using database directly with the transaction

MongoDB:

Postgres:

SQLite:

Migrations Directory

Commands

Migrate

Create

Upgrading from earlier FrogBot versions

Status

Down

Refresh

Reset

Fresh

When to run migrations

MongoDB#mongodb-migrations

Postgres#postgres-migrations

Running migrations in production

Environment-Specific Configurations and Migrations

​Migration file contents

​Using Transactions

​Using database directly with the transaction

​MongoDB:

​Postgres:

​SQLite:

​Migrations Directory

​Commands

​Migrate

​Create

​Upgrading from earlier FrogBot versions

​Status

​Down

​Refresh

​Reset

​Fresh

​When to run migrations

​MongoDB#mongodb-migrations

​Postgres#postgres-migrations

​Running migrations in production

​Environment-Specific Configurations and Migrations

Migration file contents

Using Transactions

Using database directly with the transaction

MongoDB:

Postgres:

SQLite:

Migrations Directory

Commands

Migrate

Create

Upgrading from earlier FrogBot versions

Status

Down

Refresh

Reset

Fresh

When to run migrations

MongoDB#mongodb-migrations

Postgres#postgres-migrations

Running migrations in production

Environment-Specific Configurations and Migrations