If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/frectonz/sql-studio shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 8w ago
• 4 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live frectonz/sql-studio repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/frectonz/sql-studio.

What it runs against: a local clone of frectonz/sql-studio — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in frectonz/sql-studio | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 83 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of frectonz/sql-studio. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/frectonz/sql-studio.git
#   cd sql-studio
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of frectonz/sql-studio and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "frectonz/sql-studio(\\.git)?\\b" \\
  && ok "origin remote is frectonz/sql-studio" \\
  || miss "origin remote is not frectonz/sql-studio (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "ui/src/api.ts" \\
  && ok "ui/src/api.ts" \\
  || miss "missing critical file: ui/src/api.ts"
test -f "ui/src/components/editor.tsx" \\
  && ok "ui/src/components/editor.tsx" \\
  || miss "missing critical file: ui/src/components/editor.tsx"
test -f "ui/package.json" \\
  && ok "ui/package.json" \\
  || miss "missing critical file: ui/package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 83 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~53d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/frectonz/sql-studio"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SQL Studio is a single-binary SQL database explorer that connects to 8+ database engines (SQLite, PostgreSQL, MySQL, DuckDB, ClickHouse, libSQL, MSSQL, Parquet, CSV) and provides a web UI with table browsing, query execution, schema visualization, and ERD rendering. It's designed to eliminate the need for separate database clients per engine—one sql-studio postgres [url] command opens a web IDE for exploration. Monorepo structure: src/ contains the Rust backend server (Warp web framework + database driver abstraction), docs/ is a Next.js TypeScript app for documentation, and the UI is statically embedded in the binary via include_dir. The backend likely dispatches to trait-based database connectors for each engine type.

Database engineers, data analysts, and DevOps practitioners who need quick ad-hoc database exploration across heterogeneous data sources without installing multiple tools (DBeaver, pgAdmin, MySQL Workbench, etc.). Particularly useful for teams managing multiple database types in microservice/polyglot persistence architectures.

Actively maintained—at version 0.1.51 with recent release automation (GitHub Actions CI/CD pipeline visible in .github/workflows/) and Docker Hub distribution. The codebase is substantial (~300KB Rust + TypeScript), but the 0.1.x versioning suggests the API is still stabilizing. No obvious test suite visible in file structure, which is a maturity concern for a database tool.

Single maintainer (frectonz) is a concentration risk. The dependency surface is moderate (~20 database drivers + Tokio async runtime), and pulling in many driver crates (tokio-postgres, tiberius, clickhouse, libsql) introduces transitive dependency risk. No visible security audit or vulnerability disclosure policy. Last observable activity is recent (0.1.51 release), but lack of visible tests in the repo is concerning for a tool that executes arbitrary SQL.

Recent releases (0.1.51) with installer scripts for Linux/macOS (shell) and Windows (PowerShell), Docker Hub publication, and Nix package support. CI/CD workflows automate releases (release.yml), Docker image builds (image.yml), and testing (ci.yml). Active support for new database types (Parquet, CSV, ClickHouse partial support indicate recent expansions).

git clone https://github.com/frectonz/sql-studio.git
cd sql-studio
cargo build --release
./target/release/sql-studio sqlite ./example.db
# Opens web UI at http://localhost:3030 (by default)

Note: README mentions you must build the UI before cargo run (likely requires TypeScript/Node.js build step).

Daily commands:

cargo run -- sqlite [path/to/db.db]
# Or for built binary:
./target/release/sql-studio postgres postgres://user:pass@localhost:5432/dbname
# Docker:
docker run -p 3030:3030 frectonz/sql-studio /bin/sql-studio --no-browser --no-shutdown --address=0.0.0.0:3030 postgres postgres://host.docker.internal:5432/

Defaults to http://localhost:3030; use --help for CLI flags.

• src/main.rs — Entry point for the entire application; defines CLI commands, database routing, and server initialization—all contributors must understand the command structure and database adapter pattern.
• Cargo.toml — Declares all Rust dependencies (tokio, warp, database drivers); critical for understanding what databases are supported and which async runtime is used.
• ui/src/api.ts — Frontend API client that communicates with the Rust backend; essential for understanding the request/response contract between UI and server.
• ui/src/components/editor.tsx — Core SQL query editor component; the primary user-facing interface for writing and executing queries.
• ui/package.json — Frontend dependencies and build scripts; defines the React/TypeScript setup and UI framework choices.
• docs/docs.config.tsx — Documentation site structure and navigation; helps contributors understand how to document new database adapters and features.
• ui/components.json — UI component library configuration (likely shadcn/ui or similar); defines the design system and reusable component constraints.

Add Support for a New Database Type

1. Add a new CLI subcommand variant in src/main.rs by extending the clap enum (e.g., NewDatabase { url: String }) and pattern-matching in the main function. (src/main.rs)
2. Implement or integrate the database driver in Cargo.toml by adding the appropriate async database crate (e.g., tokio-postgres, mysql_async). (Cargo.toml)
3. Create database adapter logic in src/main.rs that implements query execution, table listing, and schema introspection for the new database. (src/main.rs)
4. Create a documentation page at docs/app/docs/databases/[db-type]/page.mdx with setup instructions and connection examples. (docs/app/docs/databases/page.mdx)

Add a New Query Editor Feature

1. Extend the editor component in ui/src/components/editor.tsx to add new UI elements or editor configuration via editor.config.ts. (ui/src/components/editor.tsx)
2. If the feature requires a new API endpoint, add it to the Rust backend in src/main.rs using warp route handlers. (src/main.rs)
3. Update ui/src/api.ts with a new API client function that calls the new backend endpoint. (ui/src/api.ts)
4. Add documentation for the new feature in docs/app/docs/features/query-editor/page.mdx. (docs/app/docs/features/query-editor/page.mdx)

Add a New UI Page or Tab

1. Create a new React component under ui/src/components/ that leverages existing components from components.json (shadcn/ui). (ui/src/components/editor.tsx)
2. Add API routes in the Rust backend (src/main.rs) to serve data for the new page if it requires fetching database information. (src/main.rs)
3. Update ui/src/api.ts to add client-side functions that call the new backend endpoints. (ui/src/api.ts)
4. Add navigation links in the UI's main layout (inferred from ui/index.html) and update docs if the feature is user-facing. (ui/index.html)

Improve Documentation for a Database Adapter

1. Edit the relevant database documentation page at docs/app/docs/databases/[db-name]/page.mdx with connection strings, configuration details, and examples. (docs/app/docs/databases/sqlite/page.mdx)
2. Update docs/docs.config.tsx if adding a new database section that should appear in the navigation. (docs/docs.config.tsx)
3. Add screenshots or diagrams to docs/public/ and reference them in the markdown documentation. (docs/public/overview.png)

• Rust + Tokio + Warp — Provides a single, performant binary with async I/O for handling concurrent database queries and HTTP requests with minimal overhead.
• React + TypeScript + Vite (inferred) — Enables a responsive, modern SPA frontend with type safety for managing complex UI state (table explorer, query editor, ERD).
• Multiple async database drivers (tokio-postgres, mysql_async, tokio-rusqlite, etc.) — Allows a single binary to support many database types without a slow abstraction layer; each driver is battle-tested for its database.
• Next.js for documentation — Simplifies writing and deploying markdown-based documentation with full React capability for interactive examples.
• Monaco Editor (in editor.tsx) — Provides SQL syntax highlighting, autocomplete, and keybindings that users expect from professional database tools.

• Single binary, not a SaaS platform

  • Why: Simplifies deployment (no infrastructure needed) and appeals to users who want to run SQL Studio locally without authentication.
  • Consequence: No built-in user management, audit logging, or multi-tenant isolation; trade-off favors ease-of-use over enterprise features.

• Direct database connections from the backend, no connection pooling abstraction

  • Why: Reduces latency and complexity for single-user exploratory queries.
  • Consequence: High-concurrency, high-throughput workloads may exhaust connection limits; suitable for exploration, not production analytics.

• Frontend bundled into single Rust binary using include_dir

  • Why: Users download and run a single executable; no separate frontend deployment.
  • Consequence: Frontend updates require a new Rust build; more friction for frontend-only changes.

• Infinite scroll pagination in results

  • Why: Provides a smooth UX for large result sets without loading the entire table into memory.
  • Consequence: Requires client-side state management and careful offset/limit handling; potential for showing stale data if DB changes during scroll.

• Authentication and authorization (run locally or behind a reverse proxy)
• Real-time collaboration or multi-user sessions
• Data modification (INSERT, UPDATE, DELETE) — read-only explorer
• Query optimization or execution plan analysis

Critical: The README states 'Before executing cargo run you need to build the UI because the rust app statically'—sentence incomplete, but implies TypeScript/Node.js build step (npm/yarn) must run before cargo build. No package.json or build script visible in file list, so the actual build command for the frontend is undocumented in the provided excerpt. Risk: SQLite driver uses bundled feature (compiles SQLite from C), DuckDB also bundled on non-musl targets—builds may be slow and dependency licenses should be audited. Config: --no-browser flag needed in Docker/remote setups, else it tries to open a browser. Database credentials: passed as CLI args (postgres://user:pass@host), not env vars—watch for credential leakage in shell history.

• Database driver abstraction layer — sql-studio must unify wildly different database APIs (libsql async, PostgreSQL wire protocol, MySQL binary, DuckDB native) under a common interface—understanding trait-based abstraction is key to adding new database support or modifying query execution.
• Tokio async runtime and task spawning — All database operations (queries, schema introspection, row streaming) must be non-blocking to serve multiple concurrent users in a web server; Tokio's task model and channels are core to sql-studio's concurrency.
• Static asset embedding (include_dir) — The UI is compiled TypeScript/React and embedded in the Rust binary at compile time via include_dir—this enables the 'single binary' promise but requires understanding how frontend builds are versioned with backend releases.
• SQL dialect normalization and query introspection — Different databases have incompatible SQL syntax (T-SQL vs PostgreSQL vs SQLite), schema introspection queries (information_schema, INFORMATION_SCHEMA, sqlite_master), and type systems—sql-studio must normalize these to present a unified schema browser.
• Feature-gated dependencies (Cargo features) — Cargo.toml uses feature flags (e.g., bundled for SQLite/DuckDB, rustls-tls for TLS) to control whether drivers are compiled in—understanding this enables reducing binary size or adding optional database support without bloating all deployments.
• Infinite scroll / pagination on large result sets — The README highlights 'Infinite scroll rows view'—querying tables with millions of rows requires cursor-based pagination and streaming to the browser, not loading all results into memory.
• Binary distribution and cross-compilation — The release pipeline (cargo-dist, release.yml, installer scripts) handles building for Linux/macOS/Windows and publishing executables—understanding Rust's release profiles (opt-level = z, lto = true, strip = true) is key to maintaining the single-binary promise.

• dbeaver/dbeaver — Desktop database IDE supporting 100+ database types; sql-studio is a lighter, CLI-driven, web-based alternative optimized for quick exploration rather than full-featured administration.
• sqlpad/sqlpad — Web-based SQL IDE with query editor and results visualization; sql-studio differentiates by supporting more database engines (ClickHouse, DuckDB, Parquet, CSV) and deploying as a single binary.
• hasura/graphql-engine — Turns databases into GraphQL APIs; often used alongside database explorers like sql-studio for data introspection during development.
• tursodatabase/turso — libSQL (SQLite fork) cloud platform; sql-studio includes native libSQL support (libsql and local-libsql drivers), making it a natural companion for Turso users exploring remote/local databases.
• tauri-apps/tauri — Desktop app framework for Rust + web UX; sql-studio's single-binary distribution pattern (Rust backend + embedded frontend) mirrors Tauri's approach, though sql-studio uses Warp+HTTP rather than Tauri's IPC.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for database drivers in CI

The repo supports 8+ database backends (SQLite, PostgreSQL, MySQL, DuckDB, ClickHouse, libSQL, MSSQL, Parquet/CSV) but .github/workflows/ci.yml likely only runs basic Rust checks. Each driver should have integration tests to catch regressions. This is critical since connection logic and query execution vary significantly per database.

• [ ] Examine .github/workflows/ci.yml to understand current test coverage
• [ ] Create a new workflow .github/workflows/integration-tests.yml that spins up test databases (PostgreSQL, MySQL, MSSQL via testcontainers or services)
• [ ] Add integration test modules in src/ for each driver (e.g., src/drivers/postgres_tests.rs, src/drivers/mysql_tests.rs) with actual connection and query execution tests
• [ ] Configure the workflow to skip expensive tests on pull requests but run them on main branch merges

Add missing documentation pages for database-specific features and limitations

The docs/app/docs/databases/ directory has pages for each database, but they appear skeletal. The README mentions 'Partial Support' for ClickHouse but this isn't detailed anywhere. Contributors need clarity on what features work per database (e.g., which databases support transactions, which have query limitations, auth methods supported).

• [ ] Review the actual database driver implementations in src/ (likely src/drivers/ or similar) to identify feature gaps
• [ ] Expand docs/app/docs/databases/clickhouse/page.mdx to document what 'Partial Support' means (specific unsupported queries, auth limitations, etc.)
• [ ] Add a 'Limitations' section to docs/app/docs/databases/[database]/page.mdx for PostgreSQL, MySQL, MSSQL, and DuckDB documenting any known issues or unsupported features
• [ ] Add a comparison table to docs/app/docs/databases/page.mdx showing which features (transactions, prepared statements, schema introspection, etc.) are supported per database

Add error recovery and connection resilience tests with specific failure scenarios

A database explorer needs robust error handling for network timeouts, authentication failures, and query execution errors. The presence of color-eyre and tracing suggests error handling infrastructure exists, but there's no visible test suite for connection failures, malformed queries, or auth edge cases that would catch regressions.

• [ ] Create src/tests/error_handling.rs (or similar module) with test cases for: invalid connection strings, wrong credentials, network timeouts, malformed SQL queries, and permission denied scenarios
• [ ] Use mock/test database fixtures to simulate failure conditions without needing real databases for every test
• [ ] Verify that error messages are user-friendly and include hints (e.g., 'PostgreSQL connection failed: check host/port, use postgres://user:pass@host:5432/db')
• [ ] Add these tests to the CI pipeline with a test matrix covering at least SQLite, PostgreSQL, and MySQL drivers

• Add integration tests for database drivers: The file structure shows no tests/ directory or test files. Create tests/postgres_integration_test.rs, tests/mysql_integration_test.rs, etc., spinning up Docker containers and validating execute_query(), fetch_tables(), and schema introspection work per engine. This improves maturity and catches regressions.
• Document the TypeScript/UI build process: README is incomplete ('Before executing... because the rust app statically'). Add a BUILDING.md with exact Node.js version, npm/yarn command, and frontend source directory location. Include screenshot of expected build artifacts.
• Create database-specific CLI examples in docs: docs/app/docs/databases/ exists but CLI examples may be incomplete. Add runnable examples for each database in docs/app/docs/databases/[engine]/page.mdx—e.g., 'Connect to local PostgreSQL: sql-studio postgres postgres://localhost:5432/mydb' with expected output.

• High · SQL Injection Risk - User-Supplied SQL Queries — src/main.rs and core query execution logic. The application is a SQL database explorer that executes user-supplied SQL queries (evident from 'query-editor' feature and core functionality). Without proper parameterized query usage throughout the codebase, there is significant risk of SQL injection attacks. The README shows direct database connection commands without apparent input sanitization details. Fix: Ensure all user-supplied SQL queries are executed using prepared statements and parameterized queries. Implement strict input validation and consider using an ORM or query builder that enforces parameterization. Add unit tests for SQL injection payloads.
• High · Credentials Passed as Command-Line Arguments — README.md, src/main.rs (CLI argument parsing with clap). The CLI interface accepts database credentials (auth tokens, passwords) as command-line arguments (e.g., 'sql-studio libsql [url] [auth_token]', 'sql-studio clickhouse [URL] [USER] [PASSWORD]'). These credentials are visible in process listings, shell history, and system logs, exposing sensitive authentication data. Fix: Migrate credential handling to environment variables or interactive prompts. Implement secure credential storage using OS credential managers. Document best practices for users. Consider using .env files with appropriate file permissions and add .env to .gitignore (already present but verify it excludes sensitive data).
• High · Multiple TLS/SSL Dependencies with Potential Security Gaps — Cargo.toml dependencies: tokio-postgres-rustls, rustls, tiberius, mysql_async, clickhouse. The application uses multiple TLS implementations (tokio-postgres-rustls, rustls, tiberius with rustls, mysql_async with rustls-tls, clickhouse with rustls-tls). While rustls is generally secure, version pinning and potential version mismatches across dependencies could lead to vulnerabilities. Some database drivers have special TLS configurations that may not be consistently applied. Fix: Pin rustls and webpki-roots to specific secure versions. Conduct regular dependency audits using 'cargo audit'. Establish a policy for TLS version enforcement across all database connections. Verify certificate validation is enabled for all remote connections.
• Medium · Missing CORS and Security Headers in Web Server — src/main.rs (warp server configuration). The application uses warp web framework for serving the UI. Based on file structure showing a TypeScript/React UI, there's no visible configuration for CORS policies or security headers (CSP, X-Frame-Options, etc.). This could allow unauthorized cross-origin requests or clickjacking attacks. Fix: Implement CORS middleware with restrictive allowed origins. Add security headers middleware for CSP, X-Frame-Options, X-Content-Type-Options, and Strict-Transport-Security. Use warp filters to enforce these headers on all responses.
• Medium · Unencrypted Database Credentials in Memory and Transit — src/main.rs, database connection modules. Database connection strings and credentials are stored in memory. While in-transit TLS is configured for some databases, there's no indication of encryption at rest or memory-level protection. Credentials could be exposed in memory dumps or core files. Fix: Implement secure credential handling with zero-copy approaches where possible. Use memory locking (mlock) for sensitive data. Clear credentials from memory after use. Consider using secretbox or similar encryption for stored credentials.
• Medium · Missing Rate Limiting on API Endpoints — src/main.rs (warp server routes). The warp server appears to serve the database explorer UI and API without visible rate limiting. This could allow abuse including denial-of-service attacks, credential brute-forcing, or resource exhaustion through repeated heavy queries. Fix: Implement rate limiting middleware on all API endpoints. Use exponential backoff for failed authentication attempts. Limit query execution time and resource consumption. Implement per-connection quotas.
• Medium · Automatic Port Opening Without User Confirmation — Cargo.toml (open = "5.3.2"), src/main.rs. The application uses the 'open' crate to automatically open the browser to the database explorer interface. This could expose the application to unintended users if run in multi-user environments or accessed before security measures are properly configured. Fix: Make browser auto-open optional via command-line flag (default to off).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.