Server and deploy token
Commands that run here need no server and no credential. Commands about a server (deploy, status, anything with -r) resolve the server from a flag, an environment variable, a small YAML file in the project or project.yml, and fall back to the address zsql serve binds.
The server has no accounts, users or API keys. Every read (sql, explain, explore, fields, tables, values, status, deployments) is answered for whoever can reach it, so there is nothing to sign in to. The one credential is the server’s deploy token, and only a server that was started with ZSQL_DEPLOY_TOKEN has one.
What needs the token
| Command | Needs the token |
|---|---|
zsql deploy, zsql deploy --dry-run, zsql check -r | yes |
zsql test -r | yes |
zsql undeploy | yes |
everything else, with or without -r | no |
A server with no token takes those from anyone who reaches it, which is right on your own loopback and nowhere else.
zsql auth
zsql auth --api-key TOKEN [--server URL]
Writes the token (and the server, if given) into .zsql in the project directory, replacing any existing line for the same key. The file is created with mode 0600 and is in the .gitignore that zsql init wrote. The flag and the file key are still called api_key; the value is the deploy token.
$ zsql auth --api-key 4f1c… --server http://10.0.0.5:3699
saved to /home/you/tpcds/.zsql
The file:
# zsql local configuration: deploy token (api_key), server, datasource secrets. Do not commit.
api_key: 4f1c…
server: http://10.0.0.5:3699
zsql auth must run inside a project (or with --project DIR), because the file is per project. One project holds one token at a time; switch by running it again.
Environment variables
ZSQL_API_KEY wins over every file. It is the right place for the token in CI and in any shell where you do not want a file on disk:
export ZSQL_API_KEY=4f1c…
zsql deploy --branch main
ZSQL_SERVER sets the server the same way. Unlike --server, it does not imply -r: a command that runs here still runs here.
~/.zsql/config
The same YAML keys as .zsql (api_key, server), read when the project file has no value for them. Put a token there once and every project on the machine uses it unless its own .zsql says otherwise. The repl keeps its history beside it, in ~/.zsql/history, and the server its data directory in ~/.zsql/data. ZSQL_HOME moves the whole directory.
Resolution order
The deploy token:
ZSQL_API_KEYapi_key:in.zsqlin the project directory, or.strataif.zsqldoes not existapi_key:in~/.zsql/config
The server:
--server URLZSQL_SERVERserver:in.zsql(or.strata) in the project directory, then in~/.zsql/configserver:inproject.ymlhttp://127.0.0.1:3699, wherezsql servelistens
Because of step 5, a server on your own machine needs no configuration. For one elsewhere, set it once: zsql auth --api-key TOKEN --server URL, or export ZSQL_SERVER=URL, or commit it as server: in project.yml when the whole team deploys to the same place. A trailing / is trimmed.
.strata is read only when .zsql is absent. It exists so a project that already has a .strata file with an api_key works without a second file; new projects use .zsql.
zsql server health
zsql server health
Resolves the server the same way and calls its liveness route. No token needed.
$ zsql server health
http://127.0.0.1:3699 ok
On a server that has a deploy token, a missing or wrong one shows up on the first deploy, never on a read:
$ zsql deploy
deploy TPC-DS (12544 bytes) as tpcds/main (the production branch) to http://10.0.0.5:3699
Unauthorized: this server takes a deploy token for deploys, tests and removals: Authorization: Bearer <token> (from the CLI: `zsql auth --api-key <token>`, or ZSQL_API_KEY)
$ ZSQL_API_KEY=wrong zsql deploy
Unauthorized: this deploy token is not valid
Next steps
- Running the server: the deploy token, and securing access in front of the server
- Deploying
- CI/CD