Bun SQL Studio

A modern, zero-config SQL database studio for Bun

Bun SQL Studio is a fast, professional database interface for SQLite, PostgreSQL, and MySQL. It lets you browse tables, run queries, and inspect data with minimal setup—designed for developers who want tooling that just works.

---

Why Bun SQL Studio?

Most database tools fall into two extremes:

• Heavy GUI apps that are slow, bloated, and painful to install
• CLI-based tools that are powerful but hard to navigate and visualize

On top of that, many “simple” database UIs quietly depend on extra system binaries.

The problems Bun SQL Studio solves

• CLI fatigue – remembering commands, flags, and parsing raw output
• Poor data visualization – tables, relations, and JSON are hard to inspect
• Hidden dependencies – tools that require Python, Java, system SQLite, or native DB clients
• Context switching – bouncing between terminal, editor, and browser

---

What makes Bun SQL Studio different

• Single runtime – requires only Bun 1.3.14 or newer
• No extra binaries – no Python, Java, sqlite3, psql, or mysql clients
• Visual-first UI – inspect tables, JSON, and query results with ease
• Instant setup – auto-detects Drizzle configs or uses a single config file
• Consistent experience – same workflow for SQLite, PostgreSQL, and MySQL

If Bun runs, Bun SQL Studio runs.

---

Quick Start

Bun SQL Studio uses one configuration file for all databases.

Create bun-sql-studio.json in your project root and define either a SQLite file path or a database connection string.

bunx bun-sql-studio

The studio starts at:

http://localhost:4987

---

How it looks

Configuration

bun-sql-studio.json

For local SQLite projects, bun-sql-studio.json is supported but ignored by Git by default. For databases with credentials, prefer environment variables so passwords do not enter source control:

BUN_SQL_STUDIO_DIALECT=postgresql \
BUN_SQL_STUDIO_DB_URL='postgresql://user:password@localhost:5432/database' \
bunx bun-sql-studio

{
	"dialect": "sqlite",
	"dbUrl": "./database.sqlite",
	"port": 4987
}

• Use a file path for SQLite
• Use BUN_SQL_STUDIO_DB_URL for PostgreSQL or MySQL credentials
• If a Drizzle config is present, it will be auto-detected and used instead

---

Database examples

SQLite

{
	"dialect": "sqlite",
	"dbUrl": "./database.sqlite"
}

PostgreSQL

{
	"dialect": "postgresql",
	"dbUrl": "postgresql://user:password@localhost:5432/database"
}

MySQL

{
	"dialect": "mysql",
	"dbUrl": "mysql://user:password@localhost:3306/database"
}

---

Features

• Visual Table Browser – Explore tables and columns without writing SQL
• SQL Query Editor – Execute queries with readable, paginated results
• JSON Viewer – Inspect nested JSON in a clean modal UI
• Column Resizing – Smooth drag-to-resize interactions
• Pagination – Efficient browsing of large datasets
• Cross-Database Support – One UI for all supported databases

---

Supported Databases

Database	Status	Notes
SQLite	✅ Full	No system SQLite or Python required
PostgreSQL	✅ Full	No psql binary needed
MySQL	✅ Full	No mysql client required

---

Configuration Options

Option	Type	Default	Description
dialect	string	sqlite	sqlite, postgresql, or mysql
dbUrl	string	—	SQLite file path or DB connection string
port	number	4987	Server port

---

Requirements

• Bun 1.3.14 or newer

No Node.js runtime or database client binaries are required to run the published CLI. Contributors running npm package checks or releases also need Node.js 24 with npm 11; CI uses the same versions for publishing.

---

Development

This repository is a Bun workspace containing the root CLI package, frontend, and server.

bun install --frozen-lockfile
bun run test
bun run build
npm pack --dry-run

bun run test performs strict root CLI/server type-checking and runs the Bun tests in the workspace. The frontend and server bundles are also validated by bun run build. Build output is recreated in dist/ and is not committed.

To run the development processes, use the workspace scripts:

bun run --cwd frontend dev
bun run --cwd server dev

Do not commit database credentials. Local configuration and environment files should remain untracked; CI and publishing require no checked-in secrets.

Contributing

1. Create a focused branch and make the smallest relevant change.
2. Add user-visible changes under Unreleased in CHANGELOG.md.
3. Run bun install --frozen-lockfile, bun run test, bun run build, and npm pack --dry-run before opening a pull request.
4. Open a pull request; CI repeats the locked install, test, build, and package checks.

Releases

Maintainers prepare CHANGELOG.md in a normal reviewed commit, ensure the tree is clean, then run one of:

bun run release patch
bun run release minor
bun run release major

The script validates the locked install, tests, build, and package contents before creating a version commit and annotated vX.Y.Z tag. It does not publish or push. After reviewing the commit and tag, push them using the exact commands printed by the script.

Pushing the tag triggers .github/workflows/publish.yml, which verifies the tag, repeats all checks, publishes to npm through OIDC trusted publishing, and then creates a GitHub Release with generated notes. Configure the npm package's trusted publisher for repository Nnadivictory25/bun-sql-studio, workflow publish.yml, and the npm publish action. No NPM_TOKEN secret is needed.

The curated changelog records notable user-facing changes; generated GitHub release notes provide the complete pull request and contributor history.

---

Troubleshooting

Studio doesn’t start

• Ensure bun-sql-studio.json exists and contains valid JSON
• Confirm the database path or connection string is correct

Database connection errors

• Check credentials and permissions
• Ensure SQLite files exist and are readable

Port already in use

• Change the port value in the config file

---

License

MIT