Commands

$ sqlload --help
SQL data loading tooling.

Usage: sqlload [OPTIONS] <COMMAND>

Commands:
  debug         Validate the configuration and test every connection
  plan          Show what `apply` and `load` would do (exporter: each topic's table and objects)
  tables        Print `topic<TAB>table<TAB>stream<TAB>group` per topic (`-` when skipped), without Snowflake
  apply         Create or change tables (exporter: create missing tables, stages and pipes); never loads data
  load          Load the selected tables of a loader project
  run           Export until stopped
  status        Show per-partition lag and committed offsets
  logged-state  Inspect or change the run log of `state = "logged"` tables
  contract      Compare each table's declared columns with its live table, or adopt the live columns into the declarations; exits 1 when they differ
  copy          Copy one table once, between connections named in sqlload.toml or URIs (sqlload.toml is optional)
  help          Print this message or the help of the given subcommand(s)

Command	Page
plan	plan
apply	apply
load	load
copy	copy
contract diff, contract generate	contract
debug	debug
logged-state	logged-state, only for Python tables with state="logged"
run, status, tables	run, status and tables, for the Kafka exporter

Global options

Every command takes these:

Option	Default	Meaning
-c, --config <FILE>	sqlload.toml, or SQLLOAD_CONFIG	The configuration file. Python source paths are relative to its folder.
--log-format <FORMAT>	text	text or json logs, on standard error.
--no-color	off	Print without colour. Also when NO_COLOR is set or the output isn’t a terminal.
-h, --help		Print help.
-V, --version		Print the version.

Exit codes

Code	Meaning
0	Everything selected succeeded, or agreed (contract diff, logged-state verify).
1	A table failed or was left out by a plan error, a contract difference or state disagreement was found, or the configuration is invalid.
2	The command line couldn’t be parsed.
75	From 0.34.0 (not released yet). plan, apply, load or copy failed, but only in ways that running it again unchanged may fix. See Retrying failed runs.
130	load --follow got a second Ctrl-C or SIGTERM and stopped at once.

--json doesn’t change the exit code. A declined --reload exits 1. From 0.27.0, apply --json and load --json print their result as JSON; see Results as JSON.

Retrying failed runs

From 0.34.0 (not released yet), plan, apply, load and copy exit 75 instead of 1 when every failure may pass on a second try, so a scheduler can retry those runs and alert on the rest. A failure counts as retryable when it is one of these:

• A connection that dropped, was refused or timed out, to a target, or to a source while planning or loading.
• Throttling (429) or a server error (5xx) that outlasted its retries, from a warehouse or an sl.http job. An object store failure counts only when it’s a connection that dropped or timed out.
• A Postgres connection failure, out of memory, too many connections, a server shutting down or starting, a serialization failure, a deadlock, or a lock not available.
• A table that another run is loading.
• A Python table function that raised ConnectionError or TimeoutError, or a subclass of either.

Anything else exits 1, including invalid configuration, bad credentials, a missing permission, a plan error and data that doesn’t fit its column. If any one table fails in one of these ways, the whole run exits 1, even when other tables failed in retryable ways.

A rerun after a failure loads no row twice and loses none:

• Tables that load in batches keep the batches that committed and carry on from the destination’s cursor.
• Logged tables resume from their last committed checkpoint.
• replace swaps the new table in only at the end.

See Batches and Logged state. Under --json, each failed table, and the run as a whole, says whether it is retryable; see Results as JSON.