CI/CD
A project is a git repository, so the pipeline is short: install zsql, run zsql check on pull requests, and on merge zsql deploy to the server your applications call. The deployed branch is whatever --branch names, and the job fails when a test fails because zsql exits non-zero. zsql check needs no server at all: it loads the project from the checkout and runs the tests there.
What you need
- A server the runner can reach. The server is not meant to sit on the public internet, so a hosted runner reaches it over a tailnet or VPN joined in the workflow, or through your proxy on the write routes; a self-hosted runner on the same private network just uses its address. See deploying to a server elsewhere.
- The server’s deploy token (its
ZSQL_DEPLOY_TOKEN), stored as a CI secret. It is the one credential the server has, and it is not scoped: whoever holds it can overwrite or remove any branch of any project on that server, so give it only to the jobs that deploy. ZSQL_API_KEYset from that secret. It wins over any.zsqlfile, and nothing is written to disk.ZSQL_SERVERset to the server’s URL, unlessproject.ymlnames it asserver:.--branch. CI checkouts are usually detached (git rev-parse --abbrev-ref HEADsaysHEAD), andzsqltakes the branch from git for the deploy. Pass the CI’s branch variable explicitly, always.
GitHub Actions
.github/workflows/zsql.yml:
name: zsql
on:
pull_request:
push:
branches: [main]
env:
ZSQL_API_KEY: ${{ secrets.ZSQL_API_KEY }}
ZSQL_SERVER: http://10.0.0.5:3699 # the server's private address, reached over your VPN or tailnet
jobs:
check:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install zsql
run: curl -fsSL https://0sql.io/install.sh | sh
- name: Validate and run tests
run: zsql check
deploy:
if: github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install zsql
run: curl -fsSL https://0sql.io/install.sh | sh
- name: Deploy
run: zsql deploy --branch "${{ github.ref_name }}"
On a pull request, zsql check validates the model and runs the tests from the checkout, without a server and without deploying. On a push to main, zsql deploy --branch main updates tpcds/main on your server. To also deploy feature branches as isolated previews, add their pattern to push.branches and the same step deploys tpcds/<branch>; remove them with zsql undeploy --yes --branch <branch> when the pull request closes.
GitLab CI
.gitlab-ci.yml:
variables:
ZSQL_SERVER: https://0sql.example.com
default:
image: debian:bookworm-slim
before_script:
- apt-get update -qq && apt-get install -y -qq curl ca-certificates git
- curl -fsSL https://0sql.io/install.sh | sh
check:
stage: test
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
script:
- zsql check
deploy:
stage: deploy
rules:
- if: $CI_COMMIT_BRANCH == "main"
script:
- zsql deploy --branch "$CI_COMMIT_BRANCH"
Store ZSQL_API_KEY as a masked, protected CI/CD variable; it reaches the job as an environment variable, which is where zsql looks first.
Failing on tests
zsql check and zsql deploy exit non-zero when the archive is rejected or when any test fails. In the deploy case the model is already live (the HTTP call returned 200 with test_results.failed > 0), so a red job after a merge means “deployed, and a test broke”: fix forward. To keep a broken model off main, require the check job on pull requests before merging.
deploy tpcds (6240 bytes) as tpcds/main (the production branch) to http://10.0.0.5:3699
deployed tpcds/main: 6 tables, 42 fields, 5 joins, 9 paths, 1 policies, 0 sampled dimensions
FAILED catalog quantity by month
--- generated
...
tests: 2 passed, 1 failed
Error: tests failed
Protecting production
The server does not know who is deploying: every holder of the token can deploy to every branch, and its log names the project and branch, never the sender. Protecting main is therefore done where the token lives. Keep it in a protected CI secret that only the workflow on your default branch can read, require the check job before merging, and do not hand the token to laptops. Then the only way onto the production branch is a reviewed merge.