8.1k

Roll Commands

Commands for managing database migrations

The roll commands help you manage database migrations using pgroll.

Subcommands

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>] [--verbose] [-h|--help]
  • --lock-timeout: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • -h, --help: 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>] [--verbose] [-h|--help]
  • --lock-timeout: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • -h, --help: 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: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • --local: Retrieve the latest version from a local migration directory
  • --with-schema: Prefix the version with the schema name
  • -h, --help: 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: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • --backfill-batch-delay: Duration of delay between batch backfills (eg. 1s, 1000ms)
  • --backfill-batch-size: Number of rows backfilled in each batch
  • --complete: Complete the final migration rather than leaving it active
  • -h, --help: Print help information and exit
  • <folder>: 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: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • --json: Output each migration in JSON format instead of YAML
  • --with-prefixes: Prefix each migration filename with its position in the schema history
  • -h, --help: Print help information and exit
  • <folder>: 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: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • -h, --help: 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>] [--verbose] [--backfill-batch-delay <delay>] [--backfill-batch-size <size>] [--complete] [--skip-validation] [-h|--help]
  • <file>: The migration file to start
  • --lock-timeout: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • --backfill-batch-delay: Duration of delay between batch backfills (eg. 1s, 1000ms)
  • --backfill-batch-size: Number of rows backfilled in each batch
  • --complete: Mark the migration as complete
  • --skip-validation: Skip migration validation
  • -h, --help: 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: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • -h, --help: 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>: The migration file to start
  • --lock-timeout: Postgres lock timeout in milliseconds for pgroll DDL operations
  • --pgroll-schema: Postgres schema to use for pgroll internal state
  • --postgres-url: Postgres URL
  • --role: Optional postgres role to set when executing migrations
  • --schema: Postgres schema to use for the migration
  • --verbose: Enable verbose logging
  • --json: Output migration file in JSON format instead of YAML
  • -h, --help: Print help information and exit

Global Flags

  • -h, --help