scratch

Creates a branch from the parent given, runs what it is asked to, and deletes the branch afterwards, so a query or a migration can be tried against real data without touching an existing branch. This command also takes -h, --help.

Run SQL or a Postgres client command against a temporary scratch branch Creates a branch from the parent given, runs what it is asked to, and deletes the branch afterwards, so a query or a migration can be tried against real data without touching an existing branch.

xata scratch [--organization value] [--project value] [--parent-branch value] [--database value] [--execute value] [--profile value] [--debug] [--json] <command>...

string

Organization ID

string

Project ID

string

Source branch ID or name for the scratch branch

string

Database name

string

SQL query to execute in the scratch 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.

string

Binary command to run with scratch database environment variables; pass arguments to the binary after —

Examples:

# Run SQL with the built-in client
xata scratch --execute "select count(*) from users"
# Run SQL using the short execute flag
xata scratch -x "select count(*) from users"
# Run psql with arguments
xata scratch -- psql -c "select count(*) from users"
# Run a database tool against the scratch branch
xata scratch -- npm run migrate

​scratch

scratch