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.

The rewrite is complete. Studio today gives you typed create + edit forms (enum dropdowns, JSON textarea, datetime-local, numeric inputs), plus SQL preview and query plans, drift detection, CSV/JSON export, schema search, an audit log that can persist across restarts, 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`
# audit_file = ".cratestack-studio/audit.jsonl"   # optional; see below

[[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)
                                 # "mysql" parses but isn't supported yet — it
                                 # fails at workspace-load time with an
                                 # `UnsupportedDriver` error
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. The optional audit_file key persists Studio’s own writes to an append-only JSONL file, replayed on boot. Left unset, the audit log lives in process memory only and Studio writes nothing to your filesystem — see persisting the log.

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	Behavior
`GET /`	The Studio UI, when the binary was built with the default `embed-ui` feature. Otherwise a stub page pointing at `/api/health`.
`GET /api/health`	Liveness JSON: `ok`, the workspace name, and how many targets loaded.
`GET /api/targets`	The per-target detail (`key`, `mode`, `has_db`, `has_api`) — see the read API.

Quick smoke test:

curl http://127.0.0.1:7878/api/health
# {"ok":true,"workspace":"acme","target_count":3}

Open http://127.0.0.1:7878 and you get the browser UI against those targets:

CrateStack Studio records table showing the Post model with five rows — Studio browsing a `rw` target. Sidebar = models in the schema; the RW badge and `+ New` only appear on read/write targets.

Want to see this without wiring up a database first? The framework repo ships a dev harness that boots Studio against an in-memory SQLite workspace with seeded rows — see Try it with demo data.

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. Note that “bypass” is literal: no @@allow/@@deny and no @@internal(...) suppression is enforced on this channel.
[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 — the target is a [target.db] target for every read and write. The workspace loader takes [target.db] whenever the target declares one and falls back to [target.api] only when there is no [target.db] block at all, so adding [target.api] alongside buys no policy or route-suppression enforcement. See [target.db] is a direct database connection.
[target.api].prefer_for is parsed but not consulted by anything today — it does not redirect procedures, reads or writes to the API. Don’t configure it expecting a split channel.

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.

cratestack studio eject --out ./fork gives you a standalone, runnable Studio project with the UI already bundled in; add --with-ui if you also want the Leptos UI sources to customize — see Studio Eject.

Phase roadmap

Every phase of the rewrite has shipped; the table is kept as a record of what landed where.

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
4.1	Query plans (`explain=true`), persistent audit log (`audit_file`)	Shipped

Get Started

API

Extending

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