Projects
A project is a directory of YAML: one project.yml, one datasources.yml, model files under models/, optional security.yml and tests/. It lives in git. zsql init writes the skeleton; zsql serve inside it, or the first zsql deploy to a server elsewhere, creates the project there.
zsql init
zsql init [DIR] [--name NAME] [--uid UID]
DIR defaults to the current directory. --name defaults to the directory name; --uid defaults to a slug of the name. A directory that already holds a project.yml is refused; otherwise existing files are kept and missing ones created.
$ zsql init tpcds
create project.yml
create datasources.yml
create security.yml
create AGENTS.md
create models/.keep
create tests/.keep
update .gitignore
git init (branch main) — commit before deploying; zsql deploys the checked-out branch
next: zsql datasource add, or edit datasources.yml; then zsql catalog read --schema <name>, zsql generate, zsql check
The result:
tpcds/
├── .gitignore # .zsql, .strata, samples/values.jsonl.gz
├── project.yml
├── datasources.yml
├── security.yml
├── AGENTS.md
├── models/
└── tests/
Two directories are not created until something fills them, and they are opposites as far as git is concerned:
| holds | git | |
|---|---|---|
catalog/ | <datasource>.json, what zsql catalog read | committed — it is schema, and a diff in review is where drift wants to be seen |
samples/ | values.jsonl.gz, what zsql sample collected | gitignored by default — it is customer data; committing it is a decision about where those values may go |
AGENTS.md is new in a project: the layout, the flow in its non-interactive form, how to author a field and when to enable sampling, written for an agent editing the model and useful to a person reading it.
If the directory has no .git, zsql init runs git init -q -b main, so the first checked-out branch matches the default production_branch. The .gitignore gains:
# zsql: local secrets
.zsql
.strata
.zsql holds the server’s deploy token, if it has one, and datasource secrets. It does not belong in git.
project.yml
The template:
# zsql project. The uid is what the server knows the project as; keep it stable.
name: tpcds
uid: tpcds
description:
# The branch that production reads from. Deploys go to the checked-out git
# branch, so this is the branch to merge into when a change is ready.
production_branch: main
# The server `zsql deploy` sends to, when it is not the local one; the
# server's deploy token, if it has one, lives in .zsql, never here.
# server: http://127.0.0.1:3699
| Key | Required | Meaning |
|---|---|---|
name | yes | Display name. Missing it fails the deploy: Cannot create project: name is required in project.yml. |
uid | no | What the server knows the project as, and the {uid} in every API path (/projects/{uid}/branches/{branch}/sql). Lower-cased. Defaults to the slug of name. Keep it stable: changing it makes a new project. |
description | no | Written by the template, ignored by the loader. |
production_branch | no | The branch production reads from. Default main. Query keys granted without a branch read this one. |
server | no | The server to deploy to, read by the CLI only. Leave it commented for the local one, http://127.0.0.1:3699; commit it when the whole team deploys to the same host. |
uid rules
A uid is a slug: lower-case letters, digits, - and _. The default comes from name by lower-casing, keeping [a-z0-9_-], turning every other run of characters into one -, and trimming trailing -. Store Analytics (EU) becomes store-analytics-eu. A --uid you pass to zsql init is lower-cased as given. The server refuses a deploy whose uid is not a slug.
How a server learns a project
Nothing registers a project ahead of time. zsql serve inside the project deploys it, and the first zsql deploy of a uid to any server creates it there with the name and production_branch from project.yml. A project has no owner on the server and no access list: a deploy needs the server’s deploy token when it has one, and nothing else. Two repositories that deploy the same uid to the same server overwrite each other, so keep uids distinct.
Branches
A deployed branch is named after the checked-out git branch. zsql deploy on feature/returns deploys tpcds/feature/returns; merging to main and deploying there updates tpcds/main. Branches are isolated deployments: an application queries one by name, and nothing on feature/returns changes what main answers. production_branch is only a label the server uses for query keys granted without an explicit branch, and for the (the production branch) note zsql deploy prints. Branch semantics in full are on Deploying.
Directory layout
| Path | Holds |
|---|---|
project.yml | name, uid, production_branch |
datasources.yml | One warehouse per key: name, adapter, tier, connection fields. See Datasources. |
security.yml | Row-level security policies (policies: [] to start). See Security. |
models/**/tbl.*.yml | One table with its dimensions and measures. Any depth under models/; the folder is a domain by convention. |
models/**/rel.*.yml | Joins between one datasource’s tables. |
tests/*.yml | Planner assertions, one per file, run on every deploy. See Tests. |
.zsql | Deploy token (api_key) and server, datasource secrets. Mode 0600, gitignored, never deployed. |
Model files are found by filename prefix (tbl., rel.) and extension (.yml or .yaml), recursively, in sorted order. Everything the loader reads is listed in Semantic model.