Skip to main content
The roll commands help you manage database migrations using pgroll.

Subcommands

baseline

Create a baseline migration for an existing database schema.
xata roll baseline [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--use-version-schema] [--verbose] [--json] [--yes] [-h|--help] [<name>] [<folder>]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--use-version-schema
boolean
Create version schemas for each migration
--verbose
boolean
Enable verbose logging
--json
boolean
Output in JSON format instead of YAML
--yes
boolean
Skip confirmation prompt
-h, --help
boolean
Print help information and exit
name
string
Name of the migration (e.g., “01_initial_schema”)
folder
string
The directory that contains the migrations (default: .xata/migrations)

complete

Complete an ongoing migration with the operations present in the given file.
xata roll complete [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--use-version-schema] [--verbose] [-h|--help]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--use-version-schema
boolean
Create version schemas for each migration
--verbose
boolean
Enable verbose logging
-h, --help
boolean
Print help information and exit

init

Initialize pgroll in the target database.
xata roll init [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--use-version-schema] [--verbose] [-h|--help]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--use-version-schema
boolean
Create version schemas for each migration
--verbose
boolean
Enable verbose logging
-h, --help
boolean
Print help information and exit

latest

Print the name of the latest schema version, either in the target database or a local directory.
xata roll latest [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [--local] [--with-schema] [-h|--help]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
--local
boolean
Retrieve the latest version from a local migration directory
--with-schema
boolean
Prefix the version with the schema name
-h, --help
boolean
Print help information and exit

migrate

Apply outstanding migrations from a directory to a database.
xata roll migrate [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [--backfill-batch-delay <delay>] [--backfill-batch-size <size>] [--complete] [-h|--help] [<folder>]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
--backfill-batch-delay
string
Duration of delay between batch backfills (eg. 1s, 1000ms)
--backfill-batch-size
number
Number of rows backfilled in each batch
--complete
boolean
Complete the final migration rather than leaving it active
-h, --help
boolean
Print help information and exit
folder
string
The directory that contains the migrations (default: .xata/migrations)

update

Update outdated migrations in a directory.
xata roll update [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [-h|--help] [<folder>]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
-h, --help
boolean
Print help information and exit
folder
string
The directory that contains the migrations (default: .xata/migrations)

pull

Pull migration history from the target database and write it to disk.
xata roll pull [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [--json] [--with-prefixes] [-h|--help] [<folder>]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
--json
boolean
Output each migration in JSON format instead of YAML
--with-prefixes
boolean
Prefix each migration filename with its position in the schema history
-h, --help
boolean
Print help information and exit
folder
string
The target directory to pull migrations into (default: .xata/migrations)

rollback

Roll back an ongoing migration.
xata roll rollback [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [-h|--help]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
-h, --help
boolean
Print help information and exit

start

Start a migration for the operations present in the given file.
xata roll start <file> [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--use-version-schema] [--verbose] [--backfill-batch-delay <delay>] [--backfill-batch-size <size>] [--complete] [--skip-validation] [-h|--help]
file
string
required
The migration file to start
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--use-version-schema
boolean
Create version schemas for each migration
--verbose
boolean
Enable verbose logging
--backfill-batch-delay
string
Duration of delay between batch backfills (eg. 1s, 1000ms)
--backfill-batch-size
number
Number of rows backfilled in each batch
--complete
boolean
Mark the migration as complete
--skip-validation
boolean
Skip migration validation
-h, --help
boolean
Print help information and exit

status

Show pgroll status.
xata roll status [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [-h|--help]
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
-h, --help
boolean
Print help information and exit

convert

Convert SQL statements to a pgroll migration.
xata roll convert <file> [--lock-timeout <ms>] [--pgroll-schema <schema>] [--postgres-url <url>] [--role <role>] [--schema <schema>] [--verbose] [--json] [-h|--help]
file
string
required
The migration file to start
--lock-timeout
number
Postgres lock timeout in milliseconds for pgroll DDL operations
--pgroll-schema
string
Postgres schema to use for pgroll internal state
--postgres-url
string
Postgres URL
--role
string
Optional postgres role to set when executing migrations
--schema
string
Postgres schema to use for the migration
--verbose
boolean
Enable verbose logging
--json
boolean
Output migration file in JSON format instead of YAML
-h, --help
boolean
Print help information and exit

Global Flags

-h, --help
boolean
Print help information and exit
I