How frectonz/sql-studio works
1. Repo shape
- This is a two-runtime product: a Rust command-line backend plus a TypeScript/React frontend.
- The production app is the single binary sql-studio; the UI is built separately and then statically embedded into the Rust executable.
2. Primary execution model
- A user launches sql-studio with a database-specific subcommand such as sqlite, libsql, postgres, mysql, duckdb, parquet, csv, clickhouse, or mssql.
- Those arguments determine the connection target and driver mode, and the backend becomes a local database explorer for that datasource.
3. Rust backend boundary
- src/main.rs is the backend entrypoint and likely owns:
- CLI parsing / startup
- choosing the database connector
- serving the embedded web UI
- exposing the API used by the frontend
- The backend is the authority for database access; the frontend does not talk to databases directly.
4. Database connectivity layer
- The application supports multiple database/file backends with different connection styles:
- local files: SQLite, DuckDB, Parquet, CSV
- remote servers: libSQL, PostgreSQL, MySQL, ClickHouse, MSSQL
- Architecture-wise, this implies a driver abstraction layer in Rust that normalizes schema inspection, table listing, row paging, and query execution across engines.
5. Browser UI as a separate client
- ui/ is a standalone Vite + React app.
- It behaves like a client shell for the backend API and is organized around a routed SPA, not server-rendered pages.
- The frontend is built to be packaged into the binary, but during development it remains its own Node toolchain.
6. Frontend state and API flow
- ui/src/api.ts and ui/src/provider/sql.provider.tsx suggest a central SQL/session state layer that manages:
- current connection context
- query execution
- metadata fetching
- result pagination/infinite scroll
- Data flows from backend API → React state/provider → route-specific views.
7. Main user-facing views
- The UI is split into route-level screens:
- overview / schema-style metadata view
- tables explorer
- query editor and results
- schema diagram view
- These are the core “exploration” surfaces and likely share the same backend metadata/query endpoints.
8. Querying and visualization subsystem
- ui/src/components/editor.tsx and editor.config.ts indicate a rich SQL editor with IntelliSense/formatting support.
- ui/src/components/erd/* implements the ERD visualization, with layout logic separated from rendering.
- ui/src/components/ui/* is a reusable UI kit for dialogs, tables, tabs, sheets, etc., supporting the explorer workflow.
9. Documentation site is a separate app
- docs/ is its own Next.js documentation site, not part of the runtime product.
- It contains MDX content for installation, configuration, and database-specific guidance, plus an /api/docs route and OG image generation script.
- In architecture diagrams, this should be shown as a separate marketing/docs system connected to the project, not to the app’s runtime data path.
10. Build, packaging, and release pipeline
- The repo uses Cargo, npm/pnpm, Nix, and GitHub Actions.
- CI/release workflows build the Rust binary, the embedded UI, docs assets, and release artifacts; Docker is also supported.
- dist-workspace.toml, flake.nix, and the release/image workflows indicate the project is packaged as a cross-platform distributable desktop-style CLI/web hybrid.
11. Important architectural boundary to capture
- The most important boundary is:
- Database engines and files on one side
- Rust backend API in the middle
- React browser UI on the other side
- The backend translates heterogeneous database capabilities into a uniform exploration experience, while the frontend focuses on interaction, rendering, and navigation.
12. Net result
- SQL Studio is best diagrammed as a local server application: one binary, one UI, many database adapters, and a browser-based client.
- The system is optimized for interactive inspection and ad hoc querying, not for long-running multi-user service orchestration.
Main entry points: sql.provider.tsx SQL state · release.yml Build pipeline · page.tsx Docs site · main.rs Rust backend
Components 17
Runtime
Single-binary Rust backend plus embedded browser client.
- Databases · Supported local files and remote database backends exposed through one explorer model.
- Rust backend · Binary entrypoint that parses subcommands, opens connections, serves the embedded UI, and exposes the database API.
src/main.rs
Frontend
Standalone Vite/React SPA that becomes the embedded UI.
- UI shell · Browser client that is built separately and embedded into the Rust executable.
ui/src/main.tsx - API client · Central frontend API layer for session, metadata, queries, and paging.
ui/src/api.ts - SQL state · Shared SQL session and connection state used by the route screens.
ui/src/provider/sql.provider.tsx - Overview · Metadata and summary view for the current connection.
ui/src/routes/index.tsx - Tables · Table explorer for browsing database objects and rows.
ui/src/routes/tables.tsx - Query · Interactive SQL editor and result view.
ui/src/routes/query.tsx - Schema · ERD-focused schema visualization screen.
ui/src/routes/schema.tsx - SQL editor · Rich query editor with formatting and IntelliSense support.
ui/src/components/editor.tsx - ERD view · Diagram renderer and layout logic for schema relationships.
ui/src/components/erd/erd-diagram.tsx - UI kit · Reusable dialogs, tables, tabs, sheets, inputs, and related primitives.
ui/src/components/ui
Docs
Separate Next.js documentation site and content.
- Docs site · Standalone documentation app with installation, configuration, feature, and database guides.
docs/app/page.tsx - Docs content · Feature and database guide pages for the product documentation.
docs/app/docs/page.mdx - Docs API · Documentation route used by the docs site.
docs/app/api/docs/route.ts
Delivery
Build, packaging, and release automation.
- Build pipeline · Cross-platform build, packaging, image, and release automation for Rust, UI, and docs artifacts.
.github/workflows/release.yml - Nix flake · Reproducible development and build environment for the project.
flake.nix
Connections 18
- Databases → Rust backend: connects to · Database engines and files are accessed only through the Rust backend.
- Rust backend → UI shell: serves · The Rust binary embeds and serves the browser UI.
- UI shell → API client: uses · The SPA talks to the backend through a central API layer.
- API client → SQL state: hydrates · API responses feed the shared SQL/session store.
- SQL state → Overview: drives · Connection state powers the overview screen.
- SQL state → Tables: drives · Connection state powers the table explorer.
- SQL state → Query: drives · Connection state powers query execution and results.
- SQL state → Schema: drives · Connection state powers schema visualization.
- Query → SQL editor: contains · The query screen embeds the SQL editor.
- Schema → ERD view: renders · The schema screen renders the ERD subsystem.
- SQL editor → UI kit: composes · Editor UI relies on shared interface primitives.
- ERD view → UI kit: composes · Diagram views use shared UI components.
- Docs site → Docs content: contains · The docs app is composed of MDX content pages.
- Docs site → Docs API: uses · The docs app includes a docs API route.
- Build pipeline → Rust backend: builds · CI and release workflows compile the Rust binary.
- Build pipeline → UI shell: packages · CI and release workflows build the frontend bundle for embedding.
- Build pipeline → Docs site: publishes · Documentation assets are built and released separately.
- Build pipeline → Nix flake: uses · Reproducible build inputs are defined through Nix.