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; the first zsql deploy creates the project on the service.

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 models/.keep
create tests/.keep
update .gitignore
git init (branch main)

next: describe your warehouses in datasources.yml, `zsql new table ...`, `zsql auth --api-key ...`, `zsql deploy`

The result:

tpcds/
├── .gitignore
├── project.yml
├── datasources.yml
├── security.yml
├── models/
└── tests/

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 your API key. It does not belong in git.

project.yml

The template, verbatim:

# 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

# A self-hosted zsqld, if any. The hosted service is used otherwise; the
# api key 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 service 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	An alternative server URL, read by the CLI only. Leave it commented to use the hosted service.

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 service refuses a deploy whose uid is not a slug.

How the service learns a project

Nothing registers a project ahead of time. The first zsql deploy of a uid creates it on the service with the name and production_branch from project.yml, and the user whose personal key made the deploy becomes its owner. Later deploys need write access on the branch; deploying to a protected production branch needs an owner. Access levels and query-key grants are managed in the console, see Accounts.

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 service 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`	API key and server. 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.