roll - Xata

The pgroll binary version is pinned by the CLI and can be overridden with the XATA_PGROLL_BINARY_VERSION environment variable.

Every command below also takes -h, --help.

xata roll baseline — Create a baseline migration for an existing database schema
xata roll complete — Complete an ongoing migration with the operations present in the given file
xata roll init — Initialize pgroll in the target database
xata roll latest — Print the name of the latest schema version or migration
- xata roll latest migration — Print the latest migration name
- xata roll latest schema — Print the latest version schema name
xata roll migrate — Apply outstanding migrations from a directory to a database
xata roll update — Update outdated migrations in a directory
xata roll pull — Pull migration history from the target database and write it to disk
xata roll rollback — Roll back an ongoing migration
xata roll start — Start a migration for the operations present in the given file
xata roll status — Show pgroll status
xata roll convert — Convert SQL statements to a pgroll migration

baseline

Create a baseline migration for an existing database schema

xata roll baseline [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--json] [--yes] [--profile value] [--debug] [<version>] [<folder>]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

boolean

Output in JSON format instead of YAML

boolean

Skip confirmation prompt

string

The profile to use

boolean

Print where each resolved value came from

string

Version name for the baseline, for example 01_initial_schema

string

The directory that contains the migrations

complete

Complete an ongoing migration with the operations present in the given file

xata roll complete [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--profile value] [--debug] [--json]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

init

Initialize pgroll in the target database

xata roll init [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--profile value] [--debug] [--json]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

latest

Print the name of the latest schema version or migration

latest migration

Print the latest migration name

xata roll latest migration [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--local value] [--profile value] [--debug] [--json]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

Retrieve the latest migration from a local migration directory

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

latest schema

Print the latest version schema name

xata roll latest schema [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--local value] [--profile value] [--debug] [--json]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

Retrieve the latest version from a local migration directory

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

migrate

Apply outstanding migrations from a directory to a database

xata roll migrate [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--backfill-batch-delay value] [--backfill-batch-size value] [--complete] [--expect-one] [--profile value] [--debug] [--json] [<folder>]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

Duration of delay between batch backfills (eg. 1s, 1000ms)

string

Number of rows backfilled in each batch

boolean

Complete the final migration rather than leaving it active

boolean

Abort if there is more than one migration to be applied

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

string

The directory that contains the migrations

update

Update outdated migrations in a directory

xata roll update [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--json] [--profile value] [--debug] [<folder>]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

boolean

Output migration file in JSON format instead of YAML

string

The profile to use

boolean

Print where each resolved value came from

string

The directory that contains the migrations

pull

Pull migration history from the target database and write it to disk

xata roll pull [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--json] [--profile value] [--debug] [<folder>]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

boolean

Output each migration in JSON format instead of YAML

string

The profile to use

boolean

Print where each resolved value came from

string

The target directory to pull migrations into

rollback

Roll back an ongoing migration

xata roll rollback [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--profile value] [--debug] [--json]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

start

Start a migration for the operations present in the given file

xata roll start [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--backfill-batch-delay value] [--backfill-batch-size value] [--complete] [--skip-validation] [--profile value] [--debug] [--json] <file>

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

Duration of delay between batch backfills (eg. 1s, 1000ms)

string

Number of rows backfilled in each batch

boolean

Mark the migration as complete

boolean

Skip migration validation

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

string

required

The migration file to start

status

Show pgroll status

xata roll status [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--profile value] [--debug] [--json]

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

string

The profile to use

boolean

Print where each resolved value came from

boolean

Output in JSON format when the command supports it. Defaults to on when an AI agent runs the command.

convert

Convert SQL statements to a pgroll migration

xata roll convert [--lock-timeout value] [--pgroll-schema value] [--postgres-url value] [--role value] [--schema value] [--use-version-schema] [--verbose] [--organization value] [--project value] [--branch value] [--database value] [--json] [--profile value] [--debug] <file>

string

Postgres lock timeout in milliseconds for pgroll DDL operations

string

Postgres schema to use for pgroll internal state

string

Postgres URL

string

Optional postgres role to set when executing migrations

string

Postgres schema to use for the migration

boolean

Create version schemas for each migration

boolean

Enable verbose logging

string

Organization ID

string

Project ID

string

Branch ID or name

string

Database name on the branch

boolean

Output migration file in JSON format instead of YAML

string

The profile to use

boolean

Print where each resolved value came from

string

required

The migration file to convert