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
| Shipped | Never 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 one | anything 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 deployonfeature/returnscreates or updatestpcds/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 NAMEoverrides 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.