Skip to content

CLI Reference

This page documents every command and flag of the sqlanvil CLI. The CLI’s own help is the authority for the version you have installed: sqlanvil help lists the commands and sqlanvil help <command> lists that command’s flags.

Terminal window
npm install -g @sqlanvil/cli
sqlanvil --version # sqlanvil 1.38.0 (Dataform core 3.1.5)

Requires Node.js 20.19+ or 22.12+. --version reports the sqlanvil release and the Dataform core release it is synced with.

Terminal window
sqlanvil <command> [positional arguments] [flags]
  • project-dir is the first positional argument of most commands and defaults to the current directory. Commands that read the project (compile, run, test, validate, format, install, init-creds, migrate-fix) fail unless the directory contains a workflow_settings.yaml. The one exception is run --graph, where the compiled graph is the project.
  • Help: sqlanvil help run and sqlanvil run --help are the same thing. Running sqlanvil with no command prints the command list.
  • Unknown flags are errors. The CLI is strict: a misspelled flag fails with Unknown arguments: … rather than being silently ignored, and a misspelled command gets a “did you mean” suggestion.
  • List flags (--actions, --tags) take space- or comma-separated values: --actions a b and --actions a,b are equivalent.
  • Durations (--timeout, --execution-timeout) accept values such as 30s, 10m, 2h.
  • Boolean flags can be negated with a --no- prefix: --no-artifacts, --no-test-connection.
  • Exit codes: 0 on success, 1 on any failure — compilation errors, a failed or timed-out action, a failed unit test, a validate FAILURE or BLOCKED result, or format --check finding unformatted files. This makes every command usable as a CI gate.
  • Ctrl-C during run cancels in-flight actions; during validate it drops the temporary shadow schemas before exiting.
  • Artifacts: compile writes a queryable catalog, and run adds a run-history entry, as Parquet under target/ in the project directory. They are best-effort (a write failure never fails the command) and read by query, inspect and docs. Add target/ to your .gitignore. See Artifacts & Catalog.
CommandPurpose
initCreate a new sqlanvil project (BigQuery, Postgres, Supabase, or MySQL/MariaDB). Use —interactive for a guided setup, including converting a Dataform project.
installInstall a project’s NPM dependencies.
init-credsBigQuery only. Create a .df-credentials.json file interactively.
compileCompile the project and print a summary of the graph (the full compiled graph with —json). Never connects to a warehouse.
testRun the sqlanvil project’s unit tests.
validateCheck every model’s SQL against the warehouse planner without running it: EXPLAIN on Postgres, Supabase and MySQL, a dry run on BigQuery.
runCompile the project and run it against the warehouse named by warehouse: in workflow_settings.yaml.
queryRun SQL over the project’s artifacts in target/ (views: actions, dependencies, columns, runs) with the bundled DuckDB. No warehouse is involved.
inspectSummarize the artifacts: action counts by type, and the latest run’s status, timing and failures.
docsGenerate a self-contained HTML catalog of the project at target/docs/index.html, from the artifacts.
formatFormat the project’s .sqlx and .js files in place.
introspectRead a source table’s schema from a connection and write a declaration .sqlx with columnTypes.
migrate-dataformConvert a Dataform project to sqlanvil. The source directory is never modified; the converted project and its migration report are written to out-dir, which must be empty.
migrate-fixFinish a converted project’s dialect rewrites once its declarations have been introspected: the third phase of a migration (convert, introspect, fix).
help [command]Show help for every command, or for one command.
Terminal window
sqlanvil init [project-dir] [default-database] [default-location]

Creates a new project: workflow_settings.yaml, package.json, a .gitignore that excludes .df-credentials*.json and node_modules/, and a sample project. For Postgres, Supabase and MySQL/MariaDB it also writes a starter .df-credentials.json for you to fill in.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.
default-databaseNoBigQuery: the Google Cloud project ID models build in. Required for BigQuery; ignored for the other warehouses.
default-locationNoBigQuery only, optional, e.g. US or europe-west2. If omitted, defaultLocation is not written to workflow_settings.yaml and the credentials file’s location is used; if that is also unset, BigQuery infers each job’s location from the tables it reads, and new datasets are created in US.

Options

FlagTypeDefaultDescription
--warehousestringsupabaseTarget warehouse for the new project: bigquery, postgres, supabase or mysql.
--icebergbooleanfalseBigQuery only. Prompts for a workflow-level BigQuery Iceberg table configuration.
--barebooleanfalseSkip the sample files; create empty (gitkept) directories only.
--interactivebooleanfalseGuided Q&A setup: start a fresh project (warehouse, sample project, credentials) or convert an existing Dataform project. Other init arguments are ignored except project-dir, which seeds the directory prompt.

On BigQuery, default-database (the Google Cloud project ID) is required and default-location is optional. The other warehouses ignore both. Without a location, BigQuery infers each job’s location from the tables the job reads. Dataset creation can’t be inferred that way, so new datasets are created in US, and scripts that use SET @@dataset_id with unqualified table names may run in US too (run warns about these). Set a location if your data lives anywhere else.

Terminal window
sqlanvil install [project-dir]

Installs the NPM dependencies declared in the project’s package.json (for example packages). No flags. If compilation fails with Could not find NPM dependencies, run this first.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

None.

Terminal window
sqlanvil init-creds [project-dir]

BigQuery only. Asks for the dataset location (US, EU, another region, or auto, which leaves location out of the file; see init for what an unset location means), whether to use Application Default Credentials or a service-account JSON key, and (optional, press Enter to skip) a service account to impersonate — saved as impersonateServiceAccount, see Credentials file — then writes .df-credentials.json. The connection test runs as the impersonated account, so a missing roles/iam.serviceAccountTokenCreator grant surfaces before the file is written. For Postgres, Supabase and MySQL, edit the template init wrote instead.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--test-connectionbooleantrueRun SELECT 1 with the new credentials before writing them. —no-test-connection skips it.
Terminal window
sqlanvil compile [project-dir]

Compiles the project and prints a summary of the resulting graph. It never connects to a warehouse. Exits 1 if the project has compilation errors. With --json it prints the full compiled graph, which is the file run --graph accepts. The selection flags filter only the printed graph. See Selecting actions.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--watchbooleanfalseRecompile whenever a file in the project changes (ignores node_modules).
--jsonbooleanfalseOutputs the result as JSON instead of human-readable text.
--dotbooleanfalsePrint the dependency graph in Graphviz dot format. Mutually exclusive with —json.
--timeoutstring—Maximum compilation time, e.g. ’30s’ or ‘10m’.
--quietbooleanfalseLess verbose output. Mutually exclusive with —verbose.
--actionsarray—Show only these actions in the printed graph (space- or comma-separated names or patterns, * wildcards allowed). The whole project is still compiled, so ref()s resolve.
--tagsarray—Show only actions carrying any of these tags in the printed graph.
--include-depsboolean—Also show everything the selected actions depend on, transitively.
--include-dependentsboolean—Also show everything downstream of the selected actions, transitively.
--artifactsbooleantrueWrite the queryable Parquet artifacts under target/ (the catalog on compile, run history on run). —no-artifacts skips them.
--verbosebooleanfalseMore verbose output.
Project-config overrides——See Project-config flags.
Terminal window
sqlanvil test [project-dir]

Compiles the project and runs its unit tests (actions of type: "test") against the warehouse. Exits 1 if any test fails, or if the project has no unit tests.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--credentialsstring.df-credentials.jsonPath to the credentials file, relative to the project directory. An explicit —credentials beats the environment’s credentials:, which beats the default.
--timeoutstring—Maximum compilation time, e.g. ’30s’ or ‘10m’.
--jsonbooleanfalseOutputs the result as JSON instead of human-readable text.
Project-config overrides——See Project-config flags.
Terminal window
sqlanvil validate [project-dir]

Checks every model’s SQL against the warehouse’s own planner without running it. On Postgres, Supabase and MySQL that means EXPLAIN; on BigQuery it means a dry run. validate compiles into a temporary, timestamped shadow schema and walks the graph in dependency order. After each model passes, it creates an empty stub of that model so downstream ref()s resolve. The shadow schemas are dropped at the end, and orphans left by interrupted runs are swept on the next run.

Each action reports one of:

  • PASS: the planner accepted the SQL.
  • FAIL: the planner rejected it. The error and its line and column are printed.
  • BLOCK: the action depends on something that failed.
  • SKIP: not validated (operations, imports).

Exits 1 on any FAIL or BLOCK. See the Validate guide.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--actionsarray—Action names or patterns to select, space- or comma-separated. A bare name matches the unqualified name (and errors if it’s ambiguous), a qualified schema.name matches exactly, and * wildcards are allowed.
--tagsarray—Select every action carrying any of these tags, space- or comma-separated. Combines with —actions as a union.
--include-depsboolean—Also select everything the selected actions depend on, transitively. Requires —actions or —tags.
--include-dependentsboolean—Also select everything downstream of the selected actions, transitively. Requires —actions or —tags.
--credentialsstring.df-credentials.jsonPath to the credentials file, relative to the project directory. An explicit —credentials beats the environment’s credentials:, which beats the default.
--jsonbooleanfalseOutputs the result as JSON instead of human-readable text.
--timeoutstring—Maximum compilation time, e.g. ’30s’ or ‘10m’.
--keep-shadowboolean—Leave the temporary shadow schemas in place instead of dropping them, for debugging.
Project-config overrides——See Project-config flags.
Terminal window
sqlanvil run [project-dir]

Compiles the project and executes it against the warehouse named by warehouse: in workflow_settings.yaml. Exits 0 only if every action succeeded. See Selecting actions for running part of the graph.

Output modes:

  • --json prints the run’s result (a RunResult: overall status, and each action’s status, tasks, timing and BigQuery job IDs) as one JSON document on stdout, for real runs and BigQuery dry runs alike. Progress, warnings and failed unit-test details go to stderr. On Postgres, Supabase and MySQL, --dry-run --json prints validate’s JSON results instead.
  • --build-only stops after building the execution graph and prints what would run, without running anything, then exits 0. For each dataset it shows its type and its current state in the warehouse: (does not exist), a type change such as (type: table -> view), and the last modified time where the warehouse reports one (BigQuery). With --json it prints the graph itself (the SQL of every task, the project and run config, and the warehouse state). --dry-run and --run-tests are ignored with it.

Before 1.38.0, --json required --dry-run and printed the execution graph. Scripts that used run --dry-run --json to get the graph should switch to run --build-only --json.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--dry-runboolean—Check the run without applying changes. On BigQuery this is BigQuery’s server-side dry run; on Postgres, Supabase and MySQL it runs validate, because those warehouses have no native dry run.
--build-onlybooleanfalseOnly builds the execution graph (what would run, and each dataset’s current state in the warehouse) without running anything. With —json, prints the graph as JSON. —dry-run and —run-tests are ignored when this is set.
--run-testsboolean—Run the project’s unit tests first, and abort the run if any fail.
--action-retry-limitnumber0Retry failed idempotent actions up to this many times.
--actionsarray—Action names or patterns to select, space- or comma-separated. A bare name matches the unqualified name (and errors if it’s ambiguous), a qualified schema.name matches exactly, and * wildcards are allowed.
--credentialsstring.df-credentials.jsonPath to the credentials file, relative to the project directory. An explicit —credentials beats the environment’s credentials:, which beats the default.
--full-refreshbooleanfalseRebuild incremental tables from scratch.
--graphstring—Run a stored compiled graph (the output of compile —json) instead of compiling. What runs is exactly what was compiled, including any environment overrides baked in at compile time.
--include-depsboolean—Also select everything the selected actions depend on, transitively. Requires —actions or —tags.
--include-dependentsboolean—Also select everything downstream of the selected actions, transitively. Requires —actions or —tags.
--jsonbooleanfalseOutputs the result as JSON instead of human-readable text.
--timeoutstring—Maximum compilation time, e.g. ’30s’ or ‘10m’.
--execution-timeoutstring—Wall-clock deadline for the entire run (compilation plus every action), e.g. ‘15m’. When it expires, in-flight actions are cancelled, pending ones are skipped and the run fails. Off by default.
--tagsarray—Select every action carrying any of these tags, space- or comma-separated. Combines with —actions as a union.
--job-prefixstring—BigQuery only. Prefix for BigQuery job IDs: —job-prefix nightly gives sqlanvil-nightly-<uuid>.
--job-labelsstring—BigQuery only. Labels added to every BigQuery job, e.g. team=data,pipeline=nightly.
--artifactsbooleantrueWrite the queryable Parquet artifacts under target/ (the catalog on compile, run history on run). —no-artifacts skips them.
Project-config overrides——See Project-config flags.

Restrictions on --graph:

  • It can’t be combined with --environment, because environment overrides are applied at compile time. Compile with --environment, then pass --credentials to the run.
  • It can’t be combined with --dry-run on Postgres, Supabase or MySQL, because validation recompiles from source. Run validate on the project instead.
  • If the graph was compiled by a different minor version of sqlanvil, run warns but still runs.
Terminal window
sqlanvil query [sql] [project-dir]

Runs SQL over the project’s artifacts with the bundled DuckDB. No warehouse is involved. The available views are actions, dependencies and columns (written by compile) and runs (written by run). Run compile first.

Positional arguments

ArgumentRequiredDescription
sqlNoSQL to run, e.g. “select type, count(*) from actions group by 1”.
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--jsonbooleanfalseOutputs the result as JSON instead of human-readable text.
Terminal window
sqlanvil inspect [project-dir]

Summarizes the artifacts: action counts by type, plus the latest run’s status, success and failure counts, wall time, and up to 20 failures with their error messages.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--jsonbooleanfalseOutputs the result as JSON instead of human-readable text.
Terminal window
sqlanvil docs [project-dir]

Writes a self-contained HTML catalog of the project to target/docs/index.html, covering models, types, tags, columns, dependencies and last-run status. It is built from the artifacts, so run compile (or run) first. No flags.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

None.

Terminal window
sqlanvil format [project-dir]

Formats the project’s files in place. By default that is every .sqlx and .js file under definitions/ and includes/. For format, --actions takes file globs relative to the project directory, not action names.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--actionsarray{definitions,includes}/**/*.{js,sqlx}File globs to format, relative to the project directory (not action names).
--checkbooleanfalseChange nothing; exit 1 if any file would be reformatted.
--ignore-js-filesbooleanfalseSkip .js files (with the default globs, only .sqlx files are formatted).
Terminal window
sqlanvil introspect <connection> <tableRef> [project-dir]

Reads a source table’s schema through one of the named connections: in workflow_settings.yaml and generates a declaration .sqlx with its columnTypes. Source types are mapped to the warehouse’s types. tableRef is schema.table, or just table. The source’s credentials come from the connections section of .df-credentials.json. See Foreign Data Wrappers.

Positional arguments

ArgumentRequiredDescription
connectionYesConnection name (from workflow_settings.yaml connections).
tableRefYesSource table as schema.table (or just table).
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--outputstring—File to write the declaration .sqlx to. Prints to stdout if omitted.
Terminal window
sqlanvil migrate-dataform <source-dir> <out-dir>

Converts a Dataform project to sqlanvil. The source directory is never modified. The converted project, plus migration-report.md and migration-report.json, are written to out-dir, which must be empty. See Migrate from Dataform.

Positional arguments

ArgumentRequiredDescription
source-dirYesThe Dataform project to convert (never modified).
out-dirYesWhere the converted sqlanvil project is written (created; must be empty).

Options

FlagTypeDefaultDescription
--target-warehousestringsupabaseWhere the converted project runs. supabase or postgres moves the warehouse: BigQuery sources become named connections and the SQL gets safe dialect rewrites plus inline SQLANVIL-MIGRATE markers. bigquery is a tooling swap: the project keeps running on BigQuery with its SQL and bigquery: {} blocks untouched.
Terminal window
sqlanvil migrate-fix [project-dir]

The third phase of a migration (convert, introspect, fix). Run it after the converted project’s declarations have been introspected (sh scripts/introspect_all.sh, generated by migrate-dataform). It expands SELECT * EXCEPT (...) into explicit column lists and rewrites GROUP BY ALL as positional ordinals; both need the source columns that introspection provides. It is safe to re-run. It reports anything it couldn’t resolve, rather than guessing, and exits 1 if anything is unresolved.

Positional arguments

ArgumentRequiredDescription
project-dirNo (default .)The sqlanvil project directory.

Options

FlagTypeDefaultDescription
--dry-runbooleanfalseReport what would change without writing.

run, validate and compile share four selection flags:

FlagDescription
--actionsAction names or patterns. A bare name (orders) matches by unqualified name and errors if it’s ambiguous; a qualified name (analytics.orders) matches exactly. * wildcards are allowed: stg_* matches unqualified names, and analytics.* matches qualified ones.
--tagsSelect every action carrying any of these tags. Combines with --actions as a union.
--include-depsAlso select everything the selected actions depend on, transitively. Requires --actions or --tags.
--include-dependentsAlso select everything downstream of the selected actions, transitively. Requires --actions or --tags.

Without --include-deps, only the selected actions run, so their upstream tables must already exist.

compile, run, test and validate accept these flags. Each one overrides a setting in workflow_settings.yaml for a single invocation. When a flag is unset, the file’s value applies.

FlagTypeOverridesDescription
--default-databasestringdefaultProjectDefault database. On BigQuery, the Google Cloud project ID.
--default-schemastringdefaultDatasetDefault schema (a dataset on BigQuery).
--default-locationstringdefaultLocationBigQuery only. Default location, e.g. US. run and validate send BigQuery jobs and create new datasets in this location, even when the credentials file names a different location (run warns about the mismatch). See https://cloud.google.com/bigquery/docs/locations for supported values.
--assertion-schemastringdefaultAssertionDatasetSchema that assertions are written to.
--varsstringvarsVariables as comma-separated key=value pairs, e.g. —vars=env=staging,region=eu, read in code as sqlanvil.projectConfig.vars.<key>. Values can’t contain , or =. Keys merge with the file’s vars, so a —vars key overrides only that key.
--database-suffixstringprojectSuffixSuffix appended to database names.
--schema-suffixstringdatasetSuffixSuffix appended to schema names, e.g. dev gives analytics_dev. Letters, digits and underscores only.
--table-prefixstringnamePrefixPrefix added to every table name.
--disable-assertionsbooleandisableAssertionsSkip every assertion, built-in (uniqueKey, nonNull, rowConditions) and type: “assertion”.
--default-reservationstringdefaultReservationBigQuery only. Reservation to run queries in. If neither this nor the file sets one, default BigQuery behavior applies.
--environmentstring—Load a named environment from environments: in workflow_settings.yaml. That environment’s schemaSuffix, vars, defaultDatabase, defaultLocation and credentials file apply, and explicit flags override them. See https://sqlanvil.com/docs/guides/environments/

Precedence is flags > --environment > workflow_settings.yaml. vars merge key by key, so a --vars key overrides that key and keeps the others.

FlagCommandsDescription
--credentialsrun, test, validatePath to the credentials file, relative to the project directory. Defaults to .df-credentials.json. An explicit --credentials beats the environment’s credentials:, which beats the default.
--jsoncompile, run, test, validate, query, inspectMachine-readable output.
--timeoutcompile, run, test, validateMaximum compilation time. Use --execution-timeout on run to bound the whole run.
--no-artifactscompile, runDon’t write Parquet artifacts under target/.

Warehouse connections, including secrets, live in .df-credentials.json in the project directory. It is gitignored by init and must never be committed. Non-secret settings stay in workflow_settings.yaml. The file’s shape depends on warehouse:.

Postgres / Supabase: for Supabase, use the session pooler host, because the direct db.<ref>.supabase.co host is IPv6-only.

{
"host": "aws-1-us-east-1.pooler.supabase.com",
"port": 5432,
"database": "postgres",
"user": "postgres.your-project-ref",
"password": "…",
"sslMode": "require",
"defaultSchema": "public"
}

sslMode is one of disable, allow, prefer, require, verify-ca, verify-full.

MySQL / MariaDB:

{
"host": "localhost",
"port": 3306,
"database": "sqlanvil",
"user": "root",
"password": "…",
"sslMode": "disable"
}

sslMode is disable or require.

BigQuery (written by init-creds):

{
"projectId": "my-gcp-project",
"location": "US",
"credentials": "{\"type\": \"service_account\", …}"
}

location is optional: without it (and without defaultLocation in workflow_settings.yaml), BigQuery infers each job’s location, as described under init. credentials is the service-account key JSON as a string. Omit it to use Application Default Credentials (gcloud auth application-default login). accessToken takes a short-lived OAuth2 token instead, and wins over credentials. impersonateServiceAccount (a service-account email) makes the CLI run BigQuery queries as that account without holding its key: your ADC identity, or the credentials key, is the source and needs roles/iam.serviceAccountTokenCreator on it. Precedence: accessToken → impersonateServiceAccount → credentials → ADC. The same fields work in a connections.<name> BigQuery entry.

Two optional sections can sit alongside the warehouse fields:

  • connections holds credentials for named source connections, keyed by connection name. They are used by introspect and by run for cross-warehouse sources. See Foreign Data Wrappers.
  • storage holds object-store credentials (s3, gcs) for file exports and imports on Postgres/Supabase. See File Exports.

To keep one file per environment, name them .df-credentials.<env>.json (also gitignored) and point each environment’s credentials: at its file.

Terminal window
# Supabase (the default warehouse) — then fill in .df-credentials.json
sqlanvil init my_project
cd my_project && sqlanvil install
# Postgres or MySQL/MariaDB
sqlanvil init my_project --warehouse postgres
# BigQuery — the project ID is required; the location (here US) is optional
sqlanvil init my_project my-gcp-project US --warehouse bigquery
sqlanvil init-creds my_project
# Not sure? Answer a few questions instead
sqlanvil init --interactive

Compiling and inspecting a project without touching the warehouse

Section titled “Compiling and inspecting a project without touching the warehouse”
Terminal window
# Human-readable summary
sqlanvil compile
# Full compiled graph as JSON, e.g. to pipe into jq
sqlanvil compile --json | jq '.tables[].target'
# Visualize the dependency graph
sqlanvil compile --dot | dot -Tsvg > graph.svg
# Show only part of the graph (the whole project still compiles)
sqlanvil compile --actions orders --include-deps
# Ask questions of the compiled catalog
sqlanvil query "select type, count(*) from actions group by 1"
sqlanvil docs && open target/docs/index.html
Terminal window
# Check every model against the planner; nothing is executed
sqlanvil validate
# Just one model and everything it reads from
sqlanvil validate --actions orders --include-deps
# `run --dry-run` does the same on Postgres/Supabase/MySQL (a BigQuery dry run on BigQuery)
sqlanvil run --dry-run

Running unit tests before deploying changes

Section titled “Running unit tests before deploying changes”
Terminal window
sqlanvil test
# ...or fail a run early if tests don't pass
sqlanvil run --run-tests
Terminal window
# Run a specific table (by bare name or full schema.name) and everything downstream of it
sqlanvil run --actions orders --include-dependents
# Run everything tagged "daily", including their dependencies
sqlanvil run --tags daily --include-deps
# Rebuild the "events" incremental table from scratch
sqlanvil run --actions events --full-refresh

Bounding how long a run is allowed to take

Section titled “Bounding how long a run is allowed to take”
Terminal window
# Compilation must finish within 30s; the whole run (compile + execute) within 15 minutes
sqlanvil run --timeout 30s --execution-timeout 15m

Targeting a different environment for one invocation

Section titled “Targeting a different environment for one invocation”
Terminal window
# Uses environments.dev from workflow_settings.yaml: its schema suffix, vars and credentials file
sqlanvil run --environment dev
# Or override individual settings directly
sqlanvil run --schema-suffix pr_123 --vars=region=eu

Compile a pinned graph, review or store it, then run exactly that graph:

Terminal window
sqlanvil compile --environment prod --json > graph.json
sqlanvil run --graph graph.json --credentials .df-credentials.prod.json
Terminal window
sqlanvil compile --watch

Checking formatting without modifying files

Section titled “Checking formatting without modifying files”
Terminal window
sqlanvil format --check # exits 1 if anything would change — use as a CI step
Terminal window
sqlanvil inspect
sqlanvil query "select readable_name, status from runs where run_id = (select max(run_id) from runs)"

Tracking and labeling BigQuery jobs from a run

Section titled “Tracking and labeling BigQuery jobs from a run”
Terminal window
# Job IDs become sqlanvil-nightly-<uuid>; every job carries both labels
sqlanvil run --job-prefix nightly --job-labels team=data,pipeline=nightly
Terminal window
# Write a declaration for bigquery_public's samples.shakespeare
sqlanvil introspect bigquery_public samples.shakespeare --output definitions/sources/shakespeare.sqlx
Terminal window
sqlanvil migrate-dataform ./dataform_project ./sqlanvil_project # 1. convert
(cd sqlanvil_project && sh scripts/introspect_all.sh) # 2. introspect sources
sqlanvil migrate-fix ./sqlanvil_project # 3. finish the dialect work
sqlanvil compile ./sqlanvil_project