Deploying

zsql deploy packs the project directory into a tar.gz, POSTs it to the server under the checked-out git branch, and prints what the server loaded: counts, warnings and test results. zsql check loads the same files here, without a server, and prints the same counts. zsql serve inside a project does the deploy for you and repeats it as the files change; this page is for a server elsewhere, or for a local one started with --no-project.

zsql check

zsql check

Loads the project from the files here, forms the join routes, runs the tests, and prints the same counts a deploy prints, with validated in place of deployed and the time it took. No server is involved and nothing is stored. zsql -r check is zsql deploy --dry-run instead: the same archive sent to the server’s validate route, which keeps nothing. See Modeling with zsql for a transcript.

zsql deploy

zsql deploy [--dry-run] [--watch]
$ git branch --show-current
main
$ zsql deploy
deploy tpcds (6214 bytes) as tpcds/main (the production branch) to http://127.0.0.1:3699
deployed tpcds/main: 6 tables, 42 fields, 5 joins, 9 paths, 1 policies
PASSED store net paid by category
PASSED catalog quantity by month
PASSED date range
tests: 3 passed, 0 failed

The first line says what is being sent and where: the project name, the archive size, the uid/branch it lands on, and (the production branch) when the branch equals production_branch in project.yml. The second line is the server’s summary. Then one warning: line per warning, one line per test, and the test total. A project with no tests/*.yml prints no tests deployed (tests/*.yml) instead.

What goes in the archive

ShippedNever shipped
project.yml.zsql, .strata — where every secret lives
security.yml.git
datasources.yml with secret keys removed (password, private_key, personal_access_token, secret_access_key, access_key_id, oauth_client_secret, oauth_client_id, api_key)catalog/<datasource>.json — the server validates nothing against it
every .yml / .yaml under models/ and tests/~/.zsql/results/ — what zsql run kept, which is outside the repository
samples/values.jsonl.gz, when there is oneanything not listed on the left

The sampled values are the one piece of customer data in the archive, and serving them is why they are there: a deployed branch answers GET .../values/{dim} from this file. A project that sampled nothing ships nothing, since sampling is off on every dimension until a model turns it on. If those values may not leave your machine, do not sample the dimensions that hold them.

Exit codes

zsql deploy exits non-zero when the server rejects the archive (a DeployError naming the file and message) and when any test fails. Note the second case: the HTTP deploy succeeds with status 200 and the branch is live with the new model, but the CLI prints tests failed and exits non-zero so a CI job stops. Check the output, fix the model or the test, deploy again.

$ zsql deploy
deploy tpcds (6240 bytes) as tpcds/main (the production branch) to http://127.0.0.1:3699
deployed tpcds/main: 6 tables, 42 fields, 5 joins, 9 paths, 1 policies
PASSED store net paid by category
FAILED catalog quantity by month
       --- generated
       SELECT
       	DATE_TRUNC('month', T1."d_date")::DATE AS "Month(Date)",
       	sum(T0."cs_quantity") AS "Catalog Quantity"
       FROM
       	catalog_sales T0
       	JOIN date_dim T1
       		ON T0.cs_sold_date_sk = T1.d_date_sk
       GROUP BY
       	DATE_TRUNC('month', T1."d_date")::DATE
PASSED date range
tests: 2 passed, 1 failed
Error: tests failed
$ echo $?
1

The production branch

Deploying while main (or whatever production_branch names) is checked out updates what production reads. The output says so: as tpcds/main (the production branch). The server does not protect it: whoever holds the deploy token can deploy to any branch, so production is protected by who holds the token, usually the CI job on your default branch alone (CI/CD).

—watch

$ zsql deploy --watch
deploy tpcds (6214 bytes) as tpcds/main (the production branch) to http://127.0.0.1:3699
deployed tpcds/main: 6 tables, 42 fields, 5 joins, 9 paths, 1 policies
tests: 3 passed, 0 failed
watching /home/you/tpcds for changes (ctrl-c to stop)

Deploys once, then polls the project directory every 500 ms for a changed .yml or .yaml file and redeploys 200 ms after a change. Errors are printed and watching continues. zsql serve inside a project does the same thing with the server in the same process, so --watch is for a server elsewhere.

Branches

The deployed branch is the checked-out git branch. There is no separate “promote” step: a branch is deployed by checking it out and running zsql deploy, and main is updated by merging and deploying main.

  • zsql deploy on feature/returns creates or updates tpcds/feature/returns. Nothing else changes.
  • Each deployed branch is a complete, isolated model. An application names the branch it wants in the URL: /projects/tpcds/branches/feature/returns/sql.
  • Every deployed branch is readable by whoever can reach the server. Which branch an end user’s request goes to is your application’s choice.
  • --branch NAME overrides the git branch. CI checkouts are often detached, so pass it there (see CI/CD).

Deploying from a dirty working tree deploys the files on disk, committed or not.

zsql status

The deployed branch’s summary, as the server returns it.

$ zsql status
{
  "project": "tpcds",
  "branch": "main",
  "deployed_at": "2026-10-01 15:04",
  "datasources": 1,
  "tables": 6,
  "fields": 42,
  "joins": 5,
  "paths": 9,
  "policies": 1,
  "tests": 3,
  "warnings": []
}

A branch that was never deployed answers NotFound: no deployment for project tpcds branch feature/returns.

zsql deployments

One line per deployment on the server across projects and branches.

$ zsql deployments
tpcds                            main             6 tables, 42 fields, 1 policies, 3 tests
tpcds                            feature/returns  7 tables, 48 fields, 1 policies, 3 tests

zsql deployments works outside a project directory too; it only needs a server. (zsql list is the older name, and still works.)

zsql undeploy

Removes the deployed branch from the server. The confirmation is a flag.

$ zsql undeploy
Error: this removes tpcds/feature/returns from http://127.0.0.1:3699; add --yes to confirm
$ zsql undeploy --yes
{
  "removed": "tpcds/feature/returns"
}

Removing a branch removes its deployment, not the project or the git branch.

zsql test

Runs tests/*.yml against the model loaded from the files here. With -r, runs the tests the branch was deployed with, on the server, without redeploying; useful as a cheap health check of a branch.

$ zsql test
PASSED store net paid by category
PASSED catalog quantity by month
PASSED date range
tests: 3 passed, 0 failed

Exits non-zero with tests failed when any fail. The format is on Tests.

Next steps