Installation¶

Prerequisites¶

Python 3.12+
Rust toolchain (for the native Arrow IPC extension)
Node.js 25+ (only if building the frontend from source)

GitHub Codespaces (zero setup)¶

Click "Open in Codespaces" on the repo and the server is running by the time the browser tab opens. No local toolchain needed. See Codespaces for what the devcontainer provisions.

Docker (Easiest)¶

No local toolchain required:

docker compose up -d --build

Open http://localhost:8765 in your browser.

From Source¶

1. Install dependencies and build the Rust extension¶

uv sync

This installs all Python dependencies and compiles the Rust extension via maturin.

2. Build the frontend (optional)¶

If you want the notebook UI served by the backend:

cd frontend
npm ci
npm run build
cd ..

The server auto-detects frontend/dist/ and serves it.

3. Start the server¶

uv run strata-server

Or equivalently:

uv run python -m strata

The server starts on port 8765 by default. Open http://localhost:8765.

Verify¶

curl http://localhost:8765/health
# {"status":"ok"}

Development Commands¶

# Run all tests
uv run pytest

# Format and lint
pre-commit run --all-files

# Type check
uv run ty check src/

# Start frontend dev server (hot reload, proxies to backend)
cd frontend && npm run dev

Integration test dependencies¶

A subset of integration tests needs a real PostgreSQL instance (the Iceberg SQL catalog tests). A throwaway Postgres container is shipped as docker-compose.test.yml:

# Start the test Postgres (port 5432)
docker compose -f docker-compose.test.yml up -d

# Run the integration suite
uv run pytest tests/test_*_integration.py

# Tear it down
docker compose -f docker-compose.test.yml down

The compose file is dev-only: it has no health-bound dependency on the main docker-compose.yml, and the credentials are intentionally fixed (strata/strata) for predictable local connection strings.