Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
374 lines (275 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

374 lines (275 loc) · 11.3 KB
Raw

Contributing to db-studio

Thanks for your interest in contributing to db-studio! Whether you want to fix a bug, add a new database engine, improve the UI, or help with documentation, we welcome your contributions.

This guide will walk you through setting up your environment, running the app locally, running tests, and submitting your pull request.

Table of Contents

Prerequisites

Before starting, install the following tools:

  • Bun (version 1.2.19 or higher): db-studio uses Bun as its package manager and runtime across the monorepo.
  • Node.js (version 20 or higher): required by certain toolchains and CLI utilities.
  • Git: for version control.
  • OrbStack (macOS): runs the containers behind the init-db:* seed scripts. On Linux and Windows, any Docker engine works.

Monorepo Overview

db-studio is organized as a Bun and Turborepo monorepo with the following structure:

Package Location Description
db-studio packages/server Elysia API server and the CLI tool
@db-studio/web packages/web React 19 web application (Vite, TanStack Router, TanStack Table)
@db-studio/shared packages/shared Shared TypeScript types, Zod schemas, and constants
@db-studio/ui packages/ui Reusable UI components and design tokens
@db-studio/proxy packages/proxy Cloudflare Workers proxy for AI assistant rate limiting
www www Documentation and marketing website

Getting Started

  1. Fork the db-studio repository on GitHub.

  2. Clone your fork locally:

    git clone https://github.com/<your-username>/db-studio.git
cd db-studio

  3. Install dependencies:

    bun install

  4. Build all packages once:

    bun run build

Running Locally

1. Configure Environment Variables

Copy the checked-in environment template, then set your database connection string in DATABASE_URL:

cp .env.example .env

Here are examples for different databases:

# PostgreSQL
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/dbstudio"

# CockroachDB (uses the PostgreSQL adapter)
DATABASE_URL="cockroachdb://root@localhost:26257/dbstudio"

# MySQL
DATABASE_URL="mysql://root@localhost:3306/dbstudio"

# MariaDB (uses the MySQL adapter)
DATABASE_URL="mariadb://root@localhost:3307/dbstudio"

# TiDB (uses the MySQL adapter)
DATABASE_URL="tidb://root@localhost:4000/dbstudio"

# SQL Server (MSSQL)
DATABASE_URL="mssql://sa:YourPassword1!@localhost:1433/dbstudio"

# MongoDB
DATABASE_URL="mongodb://localhost:27017/dbstudio"

# SQLite (relative or absolute file path)
DATABASE_URL="sqlite://./db/dbstudio.sqlite"

# libSQL / Turso (local sqld needs ?tls=0 and an explicit port)
DATABASE_URL="libsql://my-db-my-org.turso.io?authToken=YOUR_TOKEN"

# Redis (database index 0 to N)
DATABASE_URL="redis://localhost:6379/0"

# DuckDB (relative or absolute file path)
DATABASE_URL="duckdb://./db/dbstudio.duckdb"

# Oracle (service name as the path)
DATABASE_URL="oracle://dbstudio:dbstudio@localhost:1521/FREEPDB1"

# ClickHouse (HTTP interface; clickhouses:// for TLS)
DATABASE_URL="clickhouse://dbstudio:dbstudio@localhost:8123/dbstudio"

2. Initialize Test Data (Optional)

If you want ready-to-use sample tables and data, we provide database seed scripts:

bun run init-db:pgsql   # PostgreSQL
bun run init-db:mysql   # MySQL
bun run init-db:mssql   # SQL Server
bun run init-db:mongo   # MongoDB
bun run init-db:sqlite  # SQLite
bun run init-db:libsql  # libSQL server (sqld) in a container
bun run init-db:redis   # Redis
bun run init-db:mariadb # MariaDB
bun run init-db:cockroach # CockroachDB
bun run init-db:tidb    # TiDB
bun run init-db:duckdb  # DuckDB
bun run init-db:oracle  # Oracle
bun run init-db:clickhouse # ClickHouse

On macOS the scripts run their containers on OrbStack: they start it if it is stopped and use its orbstack Docker context without changing your global one. DuckDB needs no container.

Running one of these commands loads database-specific sample data — for SQL engines this generally includes contributors/projects/contributions tables plus engine-specific data, while MongoDB seeds collections and Redis seeds keys — so you can test features with real data immediately.

3. Start the Development Stack

db-studio uses Portless to provide stable local HTTPS addresses instead of raw port numbers.

Before your first run, trust the local Portless certificate authority:

bunx portless trust

Start the full stack with:

bun run dev

Once running, access the services in your browser:

Service Address
Web App https://web.db-studio.localhost
API Server https://api.db-studio.localhost
AI Proxy https://proxy.db-studio.localhost
Docs Site https://www.db-studio.localhost

4. Running on a Custom Port (No Sudo)

By default, Portless binds to port 443, which may prompt for administrator permissions (sudo). If you want to run completely unprivileged without any sudo prompts, start Portless on an unprivileged port such as 1355:

  1. Start the Portless proxy on port 1355:

    bunx portless proxy start -p 1355

  2. Run the dev stack with matching URLs:

    VITE_API_URL=https://api.db-studio.localhost:1355 \
VITE_API_PROXY_TARGET=https://api.db-studio.localhost:1355 \
DB_STUDIO_PROXY_URL=https://proxy.db-studio.localhost:1355 \
bun run dev

  3. Open https://web.db-studio.localhost:1355 in your browser.

5. Work on a Single Package

If you only need to work on one part of the codebase, you do not have to run the entire stack:

bun run dev:web     # React frontend only
bun run dev:server  # Elysia API server only
bun run dev:proxy   # Cloudflare AI proxy only
bun run dev:www     # Documentation site only

6. Useful Portless Commands

  • List active routes and their internal ports: 
    bunx portless list
  • Stop the background proxy: 
    bunx portless proxy stop

Testing and Quality Checks

Running Tests

We use Vitest to run our test suite through Turborepo. Please avoid running bare bun test, as Vitest handles our path aliases and mocking setup.

  • Run all tests across the repository:

    bun run test

  • Run only server tests from the root directory:

    bun run test:server

  • Run a single test file (great for focused development):

    cd packages/server
bunx vitest run tests/adapters/pg.adapter.test.ts

  • Run tests in watch mode while editing code:

    cd packages/server
bun run test:watch

Formatting and Linting

We use Biome for fast, consistent formatting and linting:

bun run format

This checks configured files (as specified in biome.json) and automatically formats them according to project rules.

Type Checking

Verify that TypeScript compiles across all configured packages without errors:

bun run typecheck

Our pre-commit hooks run Biome formatting, type checking, tests, and the project build (bun run format && bun run typecheck && bun run test && bun run build) automatically before every commit, so checking these locally helps your commits pass on the first try.

Development Workflow

Issues

We track work via GitHub issues. Pick an open issue or create one using this naming format:

[<type>]: <short-description>

Examples:

  • [FIX]: Fix auth flow
  • [FEATURE]: Support custom table filters
  • [STYLE]: Improve sidebar responsiveness

Branching

Always create your branch from the stage branch (active development lives on stage, not main):

git checkout stage
git pull origin stage
git checkout -b <type>/<issue-number>/<short-description>

Branch naming convention:

<type>/<issue-number>/<short-description>

Examples:

  • fix/142/fix-auth-flow
  • feat/156/support-custom-filters
  • docs/168/update-setup-guide

Commit Messages

We follow Conventional Commits format:

<type>(<scope>): <short-description>

Common types:

  • feat: new feature
  • fix: bug fix
  • style: design or UI adjustments
  • refactor: code improvements without functional changes
  • docs: documentation updates
  • test: adding or fixing tests
  • chore: maintenance or dependency updates

Common scopes:

  • front: web frontend
  • back: API server or CLI
  • shared: types and schemas
  • ui: shared UI components
  • proxy: Cloudflare proxy
  • docs: documentation website

Examples:

  • feat(back): add support for json array filtering
  • fix(front): prevent layout shift on table reload
  • docs(docs): update setup and testing instructions

Submitting a Pull Request

  1. Push your branch to your fork: 
    git push origin <your-branch-name>
  2. Open a Pull Request targeting the stage branch.
  3. Keep your PR title clear and descriptive, matching your commit format or branch name.
  4. Fill in the PR template: describe your changes, why they are needed, link any related issues (such as Closes #142), and add before/after screenshots or recordings.
  5. Automated CI checks will run project build, Biome formatting checks, TypeScript type checking, and tests on pull requests targeting stage or main (and on pushes to stage). Maintainers will review your PR and provide feedback.

First-Time Contributors

If this is your first contribution to db-studio, welcome aboard! Please add your name and email to the AUTHORS file in the root directory:

Your Name <your-email@example.com>

Quick Reference

Action Command
Install dependencies bun install
Build all packages bun run build
Start all services bun run dev
Start frontend only bun run dev:web
Start server only bun run dev:server
Start docs site only bun run dev:www
Format and lint bun run format
Type check bun run typecheck
Run all tests bun run test
Run server tests bun run test:server
Seed sample database bun run init-db:<engine>
Trust local SSL bunx portless trust
List active routes bunx portless list
Stop Portless proxy bunx portless proxy stop

Thank you for helping make db-studio better! If you ever have questions or need a hand, feel free to ask in GitHub Discussions or open an issue.