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.
Installation
Section titled “Installation”npm install -g @sqlanvil/clisqlanvil --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.
Invocation
Section titled “Invocation”sqlanvil <command> [positional arguments] [flags]project-diris 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 aworkflow_settings.yaml. The one exception isrun --graph, where the compiled graph is the project.- Help:
sqlanvil help runandsqlanvil run --helpare the same thing. Runningsqlanvilwith no command prints the command list.
Global behavior
Section titled “Global behavior”- 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 band--actions a,bare equivalent. - Durations (
--timeout,--execution-timeout) accept values such as30s,10m,2h. - Boolean flags can be negated with a
--no-prefix:--no-artifacts,--no-test-connection. - Exit codes:
0on success,1on any failure — compilation errors, a failed or timed-out action, a failed unit test, avalidateFAILURE or BLOCKED result, orformat --checkfinding unformatted files. This makes every command usable as a CI gate. - Ctrl-C during
runcancels in-flight actions; duringvalidateit drops the temporary shadow schemas before exiting. - Artifacts:
compilewrites a queryable catalog, andrunadds a run-history entry, as Parquet undertarget/in the project directory. They are best-effort (a write failure never fails the command) and read byquery,inspectanddocs. Addtarget/to your.gitignore. See Artifacts & Catalog.
Commands
Section titled “Commands”| Command | Purpose |
|---|---|
init | Create a new sqlanvil project (BigQuery, Postgres, Supabase, or MySQL/MariaDB). Use —interactive for a guided setup, including converting a Dataform project. |
install | Install a project’s NPM dependencies. |
init-creds | BigQuery only. Create a .df-credentials.json file interactively. |
compile | Compile the project and print a summary of the graph (the full compiled graph with —json). Never connects to a warehouse. |
test | Run the sqlanvil project’s unit tests. |
validate | Check every model’s SQL against the warehouse planner without running it: EXPLAIN on Postgres, Supabase and MySQL, a dry run on BigQuery. |
run | Compile the project and run it against the warehouse named by warehouse: in workflow_settings.yaml. |
query | Run SQL over the project’s artifacts in target/ (views: actions, dependencies, columns, runs) with the bundled DuckDB. No warehouse is involved. |
inspect | Summarize the artifacts: action counts by type, and the latest run’s status, timing and failures. |
docs | Generate a self-contained HTML catalog of the project at target/docs/index.html, from the artifacts. |
format | Format the project’s .sqlx and .js files in place. |
introspect | Read a source table’s schema from a connection and write a declaration .sqlx with columnTypes. |
migrate-dataform | Convert 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-fix | Finish 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. |
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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
default-database | No | BigQuery: the Google Cloud project ID models build in. Required for BigQuery; ignored for the other warehouses. |
default-location | No | BigQuery 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
| Flag | Type | Default | Description |
|---|---|---|---|
--warehouse | string | supabase | Target warehouse for the new project: bigquery, postgres, supabase or mysql. |
--iceberg | boolean | false | BigQuery only. Prompts for a workflow-level BigQuery Iceberg table configuration. |
--bare | boolean | false | Skip the sample files; create empty (gitkept) directories only. |
--interactive | boolean | false | Guided 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.
install
Section titled “install”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
None.
init-creds
Section titled “init-creds”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--test-connection | boolean | true | Run SELECT 1 with the new credentials before writing them. —no-test-connection skips it. |
compile
Section titled “compile”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--watch | boolean | false | Recompile whenever a file in the project changes (ignores node_modules). |
--json | boolean | false | Outputs the result as JSON instead of human-readable text. |
--dot | boolean | false | Print the dependency graph in Graphviz dot format. Mutually exclusive with —json. |
--timeout | string | — | Maximum compilation time, e.g. ’30s’ or ‘10m’. |
--quiet | boolean | false | Less verbose output. Mutually exclusive with —verbose. |
--actions | array | — | 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. |
--tags | array | — | Show only actions carrying any of these tags in the printed graph. |
--include-deps | boolean | — | Also show everything the selected actions depend on, transitively. |
--include-dependents | boolean | — | Also show everything downstream of the selected actions, transitively. |
--artifacts | boolean | true | Write the queryable Parquet artifacts under target/ (the catalog on compile, run history on run). —no-artifacts skips them. |
--verbose | boolean | false | More verbose output. |
| Project-config overrides | — | — | See Project-config flags. |
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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--credentials | string | .df-credentials.json | Path to the credentials file, relative to the project directory. An explicit —credentials beats the environment’s credentials:, which beats the default. |
--timeout | string | — | Maximum compilation time, e.g. ’30s’ or ‘10m’. |
--json | boolean | false | Outputs the result as JSON instead of human-readable text. |
| Project-config overrides | — | — | See Project-config flags. |
validate
Section titled “validate”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--actions | array | — | 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. |
--tags | array | — | Select every action carrying any of these tags, space- or comma-separated. Combines with —actions as a union. |
--include-deps | boolean | — | Also select everything the selected actions depend on, transitively. Requires —actions or —tags. |
--include-dependents | boolean | — | Also select everything downstream of the selected actions, transitively. Requires —actions or —tags. |
--credentials | string | .df-credentials.json | Path to the credentials file, relative to the project directory. An explicit —credentials beats the environment’s credentials:, which beats the default. |
--json | boolean | false | Outputs the result as JSON instead of human-readable text. |
--timeout | string | — | Maximum compilation time, e.g. ’30s’ or ‘10m’. |
--keep-shadow | boolean | — | Leave the temporary shadow schemas in place instead of dropping them, for debugging. |
| Project-config overrides | — | — | See Project-config flags. |
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:
--jsonprints the run’s result (aRunResult: 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 --jsonprintsvalidate’s JSON results instead.--build-onlystops after building the execution graph and prints what would run, without running anything, then exits0. 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--jsonit prints the graph itself (the SQL of every task, the project and run config, and the warehouse state).--dry-runand--run-testsare 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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | boolean | — | 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-only | boolean | false | Only 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-tests | boolean | — | Run the project’s unit tests first, and abort the run if any fail. |
--action-retry-limit | number | 0 | Retry failed idempotent actions up to this many times. |
--actions | array | — | 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. |
--credentials | string | .df-credentials.json | Path to the credentials file, relative to the project directory. An explicit —credentials beats the environment’s credentials:, which beats the default. |
--full-refresh | boolean | false | Rebuild incremental tables from scratch. |
--graph | string | — | 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-deps | boolean | — | Also select everything the selected actions depend on, transitively. Requires —actions or —tags. |
--include-dependents | boolean | — | Also select everything downstream of the selected actions, transitively. Requires —actions or —tags. |
--json | boolean | false | Outputs the result as JSON instead of human-readable text. |
--timeout | string | — | Maximum compilation time, e.g. ’30s’ or ‘10m’. |
--execution-timeout | string | — | 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. |
--tags | array | — | Select every action carrying any of these tags, space- or comma-separated. Combines with —actions as a union. |
--job-prefix | string | — | BigQuery only. Prefix for BigQuery job IDs: —job-prefix nightly gives sqlanvil-nightly-<uuid>. |
--job-labels | string | — | BigQuery only. Labels added to every BigQuery job, e.g. team=data,pipeline=nightly. |
--artifacts | boolean | true | Write 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--credentialsto the run. - It can’t be combined with
--dry-runon Postgres, Supabase or MySQL, because validation recompiles from source. Runvalidateon the project instead. - If the graph was compiled by a different minor version of sqlanvil,
runwarns but still runs.
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
| Argument | Required | Description |
|---|---|---|
sql | No | SQL to run, e.g. “select type, count(*) from actions group by 1”. |
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Outputs the result as JSON instead of human-readable text. |
inspect
Section titled “inspect”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--json | boolean | false | Outputs the result as JSON instead of human-readable text. |
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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
None.
format
Section titled “format”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--actions | array | {definitions,includes}/**/*.{js,sqlx} | File globs to format, relative to the project directory (not action names). |
--check | boolean | false | Change nothing; exit 1 if any file would be reformatted. |
--ignore-js-files | boolean | false | Skip .js files (with the default globs, only .sqlx files are formatted). |
introspect
Section titled “introspect”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
| Argument | Required | Description |
|---|---|---|
connection | Yes | Connection name (from workflow_settings.yaml connections). |
tableRef | Yes | Source table as schema.table (or just table). |
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--output | string | — | File to write the declaration .sqlx to. Prints to stdout if omitted. |
migrate-dataform
Section titled “migrate-dataform”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
| Argument | Required | Description |
|---|---|---|
source-dir | Yes | The Dataform project to convert (never modified). |
out-dir | Yes | Where the converted sqlanvil project is written (created; must be empty). |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--target-warehouse | string | supabase | Where 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. |
migrate-fix
Section titled “migrate-fix”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
| Argument | Required | Description |
|---|---|---|
project-dir | No (default .) | The sqlanvil project directory. |
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | boolean | false | Report what would change without writing. |
Selecting actions
Section titled “Selecting actions”run, validate and compile share four selection flags:
| Flag | Description |
|---|---|
--actions | Action 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. |
--tags | Select every action carrying any of these tags. Combines with --actions as a union. |
--include-deps | Also select everything the selected actions depend on, transitively. Requires --actions or --tags. |
--include-dependents | Also 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.
Project-config flags
Section titled “Project-config flags”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.
| Flag | Type | Overrides | Description |
|---|---|---|---|
--default-database | string | defaultProject | Default database. On BigQuery, the Google Cloud project ID. |
--default-schema | string | defaultDataset | Default schema (a dataset on BigQuery). |
--default-location | string | defaultLocation | BigQuery 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-schema | string | defaultAssertionDataset | Schema that assertions are written to. |
--vars | string | vars | Variables 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-suffix | string | projectSuffix | Suffix appended to database names. |
--schema-suffix | string | datasetSuffix | Suffix appended to schema names, e.g. dev gives analytics_dev. Letters, digits and underscores only. |
--table-prefix | string | namePrefix | Prefix added to every table name. |
--disable-assertions | boolean | disableAssertions | Skip every assertion, built-in (uniqueKey, nonNull, rowConditions) and type: “assertion”. |
--default-reservation | string | defaultReservation | BigQuery only. Reservation to run queries in. If neither this nor the file sets one, default BigQuery behavior applies. |
--environment | string | — | 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.
Other shared flags
Section titled “Other shared flags”| Flag | Commands | Description |
|---|---|---|
--credentials | run, test, validate | Path 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. |
--json | compile, run, test, validate, query, inspect | Machine-readable output. |
--timeout | compile, run, test, validate | Maximum compilation time. Use --execution-timeout on run to bound the whole run. |
--no-artifacts | compile, run | Don’t write Parquet artifacts under target/. |
Credentials file
Section titled “Credentials file”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:
connectionsholds credentials for named source connections, keyed by connection name. They are used byintrospectand byrunfor cross-warehouse sources. See Foreign Data Wrappers.storageholds 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.
Examples
Section titled “Examples”First-time project setup
Section titled “First-time project setup”# Supabase (the default warehouse) — then fill in .df-credentials.jsonsqlanvil init my_projectcd my_project && sqlanvil install
# Postgres or MySQL/MariaDBsqlanvil init my_project --warehouse postgres
# BigQuery — the project ID is required; the location (here US) is optionalsqlanvil init my_project my-gcp-project US --warehouse bigquerysqlanvil init-creds my_project
# Not sure? Answer a few questions insteadsqlanvil init --interactiveCompiling and inspecting a project without touching the warehouse
Section titled “Compiling and inspecting a project without touching the warehouse”# Human-readable summarysqlanvil compile
# Full compiled graph as JSON, e.g. to pipe into jqsqlanvil compile --json | jq '.tables[].target'
# Visualize the dependency graphsqlanvil 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 catalogsqlanvil query "select type, count(*) from actions group by 1"sqlanvil docs && open target/docs/index.htmlValidating before running
Section titled “Validating before running”# Check every model against the planner; nothing is executedsqlanvil validate
# Just one model and everything it reads fromsqlanvil validate --actions orders --include-deps
# `run --dry-run` does the same on Postgres/Supabase/MySQL (a BigQuery dry run on BigQuery)sqlanvil run --dry-runRunning unit tests before deploying changes
Section titled “Running unit tests before deploying changes”sqlanvil test
# ...or fail a run early if tests don't passsqlanvil run --run-testsRunning only part of a pipeline
Section titled “Running only part of a pipeline”# Run a specific table (by bare name or full schema.name) and everything downstream of itsqlanvil run --actions orders --include-dependents
# Run everything tagged "daily", including their dependenciessqlanvil run --tags daily --include-deps
# Rebuild the "events" incremental table from scratchsqlanvil run --actions events --full-refreshBounding how long a run is allowed to take
Section titled “Bounding how long a run is allowed to take”# Compilation must finish within 30s; the whole run (compile + execute) within 15 minutessqlanvil run --timeout 30s --execution-timeout 15mTargeting a different environment for one invocation
Section titled “Targeting a different environment for one invocation”# Uses environments.dev from workflow_settings.yaml: its schema suffix, vars and credentials filesqlanvil run --environment dev
# Or override individual settings directlysqlanvil run --schema-suffix pr_123 --vars=region=euCompile once, run later
Section titled “Compile once, run later”Compile a pinned graph, review or store it, then run exactly that graph:
sqlanvil compile --environment prod --json > graph.jsonsqlanvil run --graph graph.json --credentials .df-credentials.prod.jsonIterating on SQLX during development
Section titled “Iterating on SQLX during development”sqlanvil compile --watchChecking formatting without modifying files
Section titled “Checking formatting without modifying files”sqlanvil format --check # exits 1 if anything would change — use as a CI stepInspecting the last run
Section titled “Inspecting the last run”sqlanvil inspectsqlanvil 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”# Job IDs become sqlanvil-nightly-<uuid>; every job carries both labelssqlanvil run --job-prefix nightly --job-labels team=data,pipeline=nightlyDeclaring a cross-warehouse source
Section titled “Declaring a cross-warehouse source”# Write a declaration for bigquery_public's samples.shakespearesqlanvil introspect bigquery_public samples.shakespeare --output definitions/sources/shakespeare.sqlxMigrating a Dataform project
Section titled “Migrating a Dataform project”sqlanvil migrate-dataform ./dataform_project ./sqlanvil_project # 1. convert(cd sqlanvil_project && sh scripts/introspect_all.sh) # 2. introspect sourcessqlanvil migrate-fix ./sqlanvil_project # 3. finish the dialect worksqlanvil compile ./sqlanvil_project