Studio Quickstart

CrateStack Studio is a single binary you launch locally to inspect data behind one or more .cstack schemas. You describe the workspace once in a studio.toml — schemas, database URLs, and (optionally) deployed service endpoints — and cratestack studio run serves a web UI against those targets. Studio replaces the older generate-studio codegen scaffold from the 0.3.x line. If you were generating a Leptos+Axum project per schema set, see the migration section.

Phase 1d + 4 (current) complete the rewrite. Phase 1d retires the one-text-box-per-field create + edit forms in favor of typed inputs (enum dropdowns, JSON textarea, datetime-local, numeric inputs). Phase 4 ships SQL preview, drift detection, CSV/JSON export, schema search, an audit log, and a SQLSTATE → VALIDATION_ERROR mapping so unique / foreign-key violations come back through the same per-field envelope as the in-process validators.Reference pages: Studio Read API, Studio Write API, Studio UI, Studio Power Tools, Studio Eject.

1. Install The CLI

If you already have cratestack from the workspace build, you’re set. Otherwise from a checkout of the framework repo:

cargo build -p cratestack-cli --bin cratestack

Verify:

cratestack studio --help

2. Seed `studio.toml`

cratestack studio init

This writes a starter studio.toml in the current directory. Pass --out <dir> to target a different directory; pass --force to overwrite an existing file. The starter file is heavily commented. The minimum a real target needs is a key, a schema path, and one of [target.db] / [target.api]:

[workspace]
name = "acme"
default_mode = "ro"             # "ro" | "rw" — applied when a target omits `mode`

[[target]]
key = "catalog"                 # URL-safe; used in routes and the target switcher
display_name = "Catalog"
schema = "schemas/catalog.cstack"
mode = "rw"                     # overrides workspace default for this target

[target.db]
url = "env:CATALOG_DB_URL"      # `env:NAME` resolves at boot; literals also work
driver = "postgres"             # "postgres" (sqlx) or "sqlite" (rusqlite)
max_connections = 5             # Postgres only; SQLite uses a single connection

[target.api]
base_url = "https://catalog.internal"
auth = { kind = "bearer", token = "env:CATALOG_TOKEN" }
prefer_for = ["procedures"]     # which operations to route here instead of the DB

A target with neither [target.db] nor [target.api] is rejected at load time — Studio has no other way to reach data.

3. Run It

cratestack studio run

By default Studio binds to 127.0.0.1:7878. Override with --bind:

cratestack studio run --config infra/studio.toml --bind 0.0.0.0:9000

While Studio is running:

Endpoint	Phase 0 behavior
`GET /`	Stub page with a link to `/api/health`.
`GET /api/health`	JSON: workspace name + per-target `has_db` / `has_api` / `mode`.

Quick smoke test:

curl http://127.0.0.1:7878/api/health
# {"ok":true,"workspace":"acme","targets":[{"key":"catalog","has_db":true,"has_api":true,"mode":"rw"}]}

4. Multiple Schemas

Studio is designed around multi-target workspaces — one studio.toml can describe every .cstack in a monorepo:

[workspace]
name = "platform"
default_mode = "ro"

[[target]]
key = "catalog"
schema = "services/catalog-service/schema/catalog.cstack"
[target.db]
url = "env:CATALOG_DB_URL"
driver = "postgres"

[[target]]
key = "accounts"
schema = "services/accounts-service/schema/accounts.cstack"
[target.db]
url = "env:ACCOUNTS_DB_URL"
driver = "postgres"

[[target]]
key = "inventory"
schema = "services/inventory-service/schema/inventory.cstack"
mode = "rw"
[target.db]
url = "env:INVENTORY_DB_URL"
driver = "postgres"
[target.api]
base_url = "https://inventory.internal"
auth = { kind = "bearer", token = "env:INVENTORY_TOKEN" }

Each target gets its own entry in the UI’s target switcher.

SQLite targets

Studio talks to SQLite databases through rusqlite. The url accepts sqlite:, sqlite://, sqlite::memory:, and bare file paths.

[[target]]
key = "embedded"
schema = "schemas/embedded.cstack"

[target.db]
url = "sqlite:./local-state.db"
driver = "sqlite"

[[target]]
key = "scratch"
schema = "schemas/scratch.cstack"

[target.db]
url = "sqlite::memory:"
driver = "sqlite"

Studio uses rusqlite rather than sqlx-sqlite so it coexists with the rest of the framework’s SQLite path (cratestack-rusqlite).

Direct DB vs deployed service

A target can declare a [target.db] block, a [target.api] block, or both:

[target.db] only — Studio opens its own sqlx pool. Best for schemas without a running service, or when you want to bypass application-level RBAC for debugging.
[target.api] only — Studio proxies through your deployed CrateStack service. Same auth and policy the service enforces in production. Pick this for shared environments where direct DB access is undesirable.
Both — Studio uses the DB for browsing and routes procedures (and anything in prefer_for) through the API. The DB pool is read-only unless the target also has mode = "rw".

Read-only vs read/write

mode controls whether Studio renders edit affordances and accepts mutation calls for a target:

"ro" (workspace default) — list, paginate, follow relations, copy generated Rust queries. No edit/delete UI. Mutation endpoints reject with 403.
"rw" — adds inline edits, create flows, delete confirmations, and the validation-error pass-through from cratestack-policy. Lands in Phase 3.

Set the workspace default in [workspace] default_mode, then override per target via mode = "...".

Migration from `generate-studio`

If you were on the 0.3.x scaffold generator:

Delete the generated studio/ workspace from your repo — Studio is no longer code you check in.

Run cratestack studio init and translate your old flags into [[target]] blocks. Roughly:

Old flag	New `studio.toml` field
`--schema <path>`	`target.schema`
`--service-url <url>`	`target.api.base_url`
`--context <key>`	`target.key`
`--name <studio-name>`	`workspace.name`
`--mount-path <path>`	(gone — Studio is its own server)
`--profile dev` / `--profile prod`	(gone — runtime-only behavior now)

Add a [target.db] block if you want direct DB browsing. The old generator’s reverse-proxy mode mapped to [target.api] exclusively.

If you forked the Leptos UI, you’ll want to wait for Phase 2 — cratestack studio eject --out ./fork will then copy Studio’s own sources into a workspace you can customize. In Phase 0 / 1 the eject subcommand returns NotImplemented.

Phase roadmap

Phase	Scope	Status
0	Skeleton: CLI, config loader, target validation, health endpoint	Shipped
1a	Read API: six JSON endpoints + Postgres source + `env:`/`file:` secrets + typed snippet generator	Shipped
1b	SQLite via `rusqlite`, relation follow, API-backed list/get, Leptos+Trunk UI, dev CORS	Shipped
1c	Typed relation picker in the UI, drawer polish, JSON viewer	Shipped
2	`studio eject` (writable fork of the UI) + `embed-ui` cargo feature (single-binary distribution)	Shipped
3	Write API: POST / PATCH / DELETE, validator pass-through, mode gate, inline create/edit/delete UI	Shipped
1d	Typed pickers for enums, rich editors for JSON / DateTime / Decimal in the create + edit forms	Shipped
4	SQL preview, drift, CSV/JSON export, schema search, audit log, SQLSTATE → VALIDATION_ERROR mapping	Shipped

Overview

Get Started

Guides

Banking Readiness

Architecture

Tooling

Studio

Reference

Internals

Studio Quickstart

Studio Quickstart

1. Install The CLI

2. Seed `studio.toml`

3. Run It

4. Multiple Schemas

SQLite targets

Direct DB vs deployed service

Read-only vs read/write

Migration from `generate-studio`

Phase roadmap

​Studio Quickstart

​1. Install The CLI

​2. Seed studio.toml

​3. Run It

​4. Multiple Schemas

​SQLite targets

​Direct DB vs deployed service

​Read-only vs read/write

​Migration from generate-studio

​Phase roadmap

Studio Quickstart

1. Install The CLI

2. Seed `studio.toml`

3. Run It

4. Multiple Schemas

SQLite targets

Direct DB vs deployed service

Read-only vs read/write

Migration from `generate-studio`

Phase roadmap