Zetaris client setup

Use JDBC to run Lightning SQL through the Zetaris Java driver. You need your Zetaris user ID and password, JDK 11 or later and the matching driver JAR. For a remote instance, use the JDBC URL supplied to you.

Set up .env.local

Copy the needed settings from .env.example into .env.local at the repository root. If the file already exists, add settings without replacing its other values. Scripts also find the top-level checkout's .env.local when run from a Git worktree.

Keep passwords and API keys in this local, gitignored file. Never put them in a prompt, source file, command output or URL.

Prepare JDBC

To connect with JDBC, you need Java 11 or later, the Zetaris driver file (a .jar file), and your Zetaris username and password. The driver must match your Zetaris instance. Get its full file path from whoever supplied the driver; the setup scripts do not search for it.

On macOS, the java command may not find an installed Java runtime. If that happens, check /usr/libexec/java_home or the Homebrew JDK location /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home, then set JAVA_HOME to the JDK folder. The preflight finds a Java path but does not check its version. Confirm it with:

"$JAVA_HOME/bin/java" -version

To check your setup, run this read-only preflight from the repository folder:

python3 scripts/preflight.py --jdbc --jar "/full/path/to/your/zetaris-driver.jar"

Replace the example path with the actual path to your driver file. The preflight installs nothing and does not change your Zetaris instance. It also checks REST, so read the JDBC results separately; a REST problem by itself does not mean JDBC is unavailable.

The repository's Python SQL runner also needs a local Python environment (.venv) and the jaydebeapi package. If either is missing, that runner is not ready. A direct Java JDBC connection does not need these Python components. Ask before installing missing software or packages.

If a local port check says Operation not permitted, Codex may be blocked from accessing your computer's local network. That result does not show that the port is closed or that the JDBC URL is wrong. Retry the same read-only check with network access, or run it in a terminal that can reach Zetaris. For a remote instance, use its supplied host and port; localhost refers to the machine running the JDBC client.

If Java is missing, ask before installing it. If JDBC is unavailable, use REST if your account has access.

JDBC starter prompt

Set the JDBC values in .env.local, then submit this as the first instruction. Replace the goal with your task.

Read AGENTS.md and follow it. Run python3 scripts/preflight.py --jdbc and show
me the result. Report JDBC and REST checks separately. Stop on JDBC failures and report
what is missing. REST failures alone do not block JDBC. If the driver JAR path is not set, ask me
for it. Once readiness checks pass, connect over JDBC to the instance
configured in .env.local and confirm with SELECT 1 and SHOW LIGHTNING DATABASES.

If a local port check returns `Operation not permitted`, retry the same
read-only check with approved network access before reporting the endpoint as
closed. Distinguish missing Python runner dependencies (`.venv` or
`jaydebeapi`) from direct Java JDBC readiness; do not install dependencies
without asking.

Goal: <for example: list NY_TAXI and TPCDS_DB tables, then read 5 rows from
NY_TAXI.taxi_zones; keep it read-only>

Dry-run before creating anything and wait for my go-ahead.

Verify access

Run the JDBC preflight shown above and read its JDBC result separately from its REST result. The script also runs REST checks, but a missing REST key or unreachable REST service alone does not block a JDBC connection.

SELECT 1 should return 1. SHOW LIGHTNING DATABASES shows the instance's Lightning databases; an empty list is normal on a clean instance.

SHOW DATASOURCES lists sources registered with CREATE DATASOURCE. Use SHOW LIGHTNING DATABASES for REST and file sources.

Safety and permissions

• Start with read-only commands such as SHOW, DESCRIBE, and SELECT.
• On a shared instance, get your team prefix and permissions first. Check that an existing object belongs to your team and matches the definition before reusing it.
• Creating, dropping, granting, or writing changes the instance. Preview create scripts with --dry-run and wait for the user's clear go-ahead before running them.
• Send one Lightning SQL statement per call. Keep a multi-table COMPILE USL together as one statement; do not split it at semicolons.
• Keep credentials out of prompts, logs, source files, and commits.

Troubleshooting

For JDBC script options, see scripts/HOWTO.md.

Use REST to run SQL or call platform endpoints over HTTP. No Java runtime or JDBC driver is needed. Choose the route used by your client:

For Zetaris Cloud or another remote instance, use the URLs supplied to you. The routes use separate addresses: put the API base in ZETARIS_REST_URL and the web UI origin in ZETARIS_BASE_URL.

For a local install, browse the available endpoints in the REST API docs. Scripts use the separate API base http://localhost:8888/api/v1.0; the docs page is not the API base.

Set up .env.local

Copy the needed settings from .env.example into .env.local at the repository root. If the file already exists, add settings without replacing its other values. Scripts also find the top-level checkout's .env.local when run from a Git worktree.

Keep passwords and API keys in this local, gitignored file. Never put them in a prompt, source file, command output or URL.

Create an API key

1. Sign in to the Zetaris UI with your account.
2. In the sidebar, open Management → API Tokens.
3. Click the + button at the top right to create an API key.
4. Copy the key when it is shown and save it as ZETARIS_API_KEY in .env.local.

Each key is shown in plaintext only once. The key has your account's permissions. Never ask an agent to create or fetch it, and do not paste it into a prompt. If REST returns 401, create a fresh key on this page and update the local value.

The UI-proxy helpers can use that API key directly. If it is not set, they can log in with both ZETARIS_USERNAME and ZETARIS_PASSWORD. Direct REST uses the bearer key.

Find your organisation ID

1. Sign in to the Zetaris UI.
2. In the sidebar, open Management → Organisation.
3. Copy the numeric value in the ID field into ZETARIS_ORG_ID in .env.local.

Use the ID, not the organisation name or login URL slug. For example, if the ID field shows 1, set ZETARIS_ORG_ID=1. Use the value shown for your organisation.

If you cannot access this page, ask your organiser or administrator for the numeric organisation ID. Direct REST and the UI-proxy helpers require this setting.

REST starter prompt

Create your API key and set the REST values in .env.local first. Then submit this as the first instruction.

Read AGENTS.md and follow it. Run python3 scripts/preflight.py and show me the
result. Then connect over REST to the instance configured in .env.local and
confirm with SELECT 1 and SHOW LIGHTNING DATABASES.

Goal: <for example: list NY_TAXI and TPCDS_DB tables, then read 5 rows from
NY_TAXI.taxi_zones; keep it read-only>

Dry-run before creating anything and wait for my go-ahead.

Verify access

For direct REST, run the read-only preflight:

python3 scripts/preflight.py

It checks GET /datasource/datasources, SELECT 1 and the instance's Lightning databases.

SELECT 1 should return 1. SHOW LIGHTNING DATABASES shows the instance's Lightning databases; an empty list is normal on a clean instance.

SHOW DATASOURCES lists sources registered with CREATE DATASOURCE. Use SHOW LIGHTNING DATABASES for REST and file sources.

REST returns values as strings, and decimals may use exponent format; convert them before comparing.

Verify the UI proxy

The small query_zetaris and check_zetaris helpers use the UI proxy. Choose Python or Deno; each example runs one query:

./scripts/query_zetaris.ts "SELECT 1"
python3 scripts/query_zetaris.py "SELECT 1"

These use ZETARIS_BASE_URL, not the direct REST URL. A successful direct REST preflight does not verify the UI-proxy route.

Safety and permissions

• Start with read-only commands such as SHOW, DESCRIBE, and SELECT.
• On a shared instance, get your team prefix and permissions first. Check that an existing object belongs to your team and matches the definition before reusing it.
• Creating, dropping, granting, or writing changes the instance. Preview create scripts with --dry-run and wait for the user's clear go-ahead before running them.
• Send one Lightning SQL statement per call. Keep a multi-table COMPILE USL together as one statement; do not split it at semicolons.
• Keep credentials out of prompts, logs, source files, and commits.

Fetch the OpenAPI specification

Fetch a fresh specification when you need a direct REST endpoint. The spec route uses HTTP Basic authentication with ZETARIS_USERNAME and ZETARIS_PASSWORD. It does not accept the bearer API key. Save the spec outside the repository because it may contain environment-specific details.

set -a
. ./.env.local
ZETARIS_REST_URL="${ZETARIS_REST_URL:-http://localhost:8888/api/v1.0}"
set +a
curl -sS -u "$ZETARIS_USERNAME:$ZETARIS_PASSWORD" \
  "${ZETARIS_REST_URL%/api/v1.0}/redoc/docs.yaml" \
  -o /tmp/zetaris-docs.yaml

For a local instance this fetches http://localhost:8888/redoc/docs.yaml. For a remote instance, ZETARIS_REST_URL must point to its /api/v1.0 API base. Do not print or echo the credentials.

Troubleshooting

For script-specific setup and the difference between one-request helpers and multi-statement runners, see scripts/HOWTO.md.