Execute a multi-statement SQL script file with variable substitution and per-statement progress reporting.
delta-forge-cli run <FILE> [-D <KEY>=<VALUE>]...## Overview `run` executes a UTF-8 SQL script file sequentially, printing a progress line to stderr for each statement. It is the workhorse for migrations, seed data, and any batch SQL executed from disk. ## Behavior - The file is read in full, then variable substitution is applied across the entire text before splitting. - Statement splitting treats `;` as the terminator, but preserves semicolons that appear inside single-quoted string literals and ignores anything after `--` until end of line. - Each statement is sent as a separate request to the compute engine. The authenticated client is reused across statements, and tokens are refreshed automatically as they approach expiry. - Progress lines are printed to stderr as ` [N/TOTAL] <preview> ... <message> (<elapsed>ms)`. The preview is the first non-empty, non-comment line of the statement, truncated to 60 characters. - Failure of any statement halts execution immediately and returns exit code 1. There is no implicit transaction around the script, so statements that committed before the failure remain applied. - Variable substitution is purely textual (no type coercion and no quoting). The substituted text replaces `{{KEY}}` verbatim, so values that contain SQL special characters need to be escaped in the value itself. ## Compatibility - `run` and piped-stdin execution (`cat file.sql | delta-forge-cli`) use the same statement splitter and the same executor. The only differences are that piped execution reads from stdin and does not emit `[N/TOTAL]` progress lines. - `run` does not support named connections or multi-file execution in one call. Use shell chaining for multi-file scripts.
| Name | Type | Description |
|---|---|---|
FILE | Path to a `.sql` file, read as UTF-8. Semicolon-terminated statements are split via the internal `split_sql_statements` function, which respects single-quoted string literals and `--` line comments. | |
-D / --var | Textual variable substitution. Replaces every occurrence of `{{KEY}}` in the script with VALUE before statements are split. May be repeated. Path separators in VALUE are not normalised by `run` (unlike `demo-test`, which rewrites Windows backslashes to forward slashes). |
# Minimal: run a script with no variables
delta-forge-cli run migrations/v2.sql# Inject zone and data path
delta-forge-cli run setup.sql -D zone_name=production -D data_path=/data/warehouse# Reference injected variables inside the script:
# CREATE ZONE {{zone_name}} LOCATION '{{data_path}}';
delta-forge-cli run setup.sql -D zone_name=prod -D data_path=/mnt/prod# Use a profile for connection, inject a tenant
delta-forge-cli --profile staging run fixtures/seed.sql -D tenant=acme# JSON format surfaces per-statement result tables on stdout;
# progress lines stay on stderr
delta-forge-cli --format json run report.sql >results.json# CI: fail the job on first error (exit code 1)
delta-forge-cli --profile ci run nightly/etl.sql || exit $?