Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (106 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

141 lines (106 loc) · 11.3 KB
Raw

⚙️ Contributing

How to build, test and find your way around BarSQL. Packaging, releases and the updater are in RELEASING.md.

Requirements

  • Rust - rustup installs the toolchain pinned in rust-toolchain.toml on first use
  • Linux also needs GPUI's libraries: clang libfontconfig-dev libfreetype-dev libwayland-dev libx11-xcb-dev libxkbcommon-dev libxkbcommon-x11-dev libvulkan-dev
  • Docker or Podman, only for the test databases (PostgreSQL, MySQL, MariaDB, ClickHouse, libSQL and, optionally, SQL Server)

Run

cargo run -p barsql

Build

cargo build -p barsql --release   # or: cargo xtask package  (this OS's packages, in target/package/dist)

Tests

cargo test --workspace   # unit, SQLite and whole-window UI tests
cargo xtask lint         # rustfmt and clippy, as CI runs them
cargo xtask e2e up       # PostgreSQL, MySQL, MariaDB, ClickHouse and libSQL from docker-compose.yml
cargo xtask e2e          # the suites that need them
cargo xtask e2e down
cargo xtask screenshots  # the README's and landing page's screenshots, against the PostgreSQL above
cargo xtask demo-video   # the demo video, against every engine above
cargo xtask docs-images  # their smaller copies and link preview

cargo xtask is this repository's task runner (the xtask/ crate); run it alone to list its commands. COMPOSE="podman compose" makes it use Podman.

The databases listen on 55432 (PostgreSQL), 33306 (MySQL), 33307 (MariaDB), 38123 (ClickHouse) and 38080 (libSQL's sqld). SQL Server is opt-in: BARSQL_E2E_MSSQL=1 with cargo xtask e2e up adds it on 31433 (Azure SQL Edge on Apple silicon, where SQL Server itself doesn't run), and the same variable turns its tests on.

  • The UI tests in crates/barsql-ui run on GPUI's TestAppContext against a SQLite database, with real keystrokes, clicks, file drops and window resizes. src/scenarios drives the whole window.
  • --features e2e adds the per-engine scenarios and the fixtures in fixtures/golden, which pin down value display, DDL, EXPLAIN plans and errors for each engine. BARSQL_GOLDEN_WRITE=1 rewrites them when an engine's output changes on purpose; review the diff before keeping it.

CI (.github/workflows/test.yml) runs the Linux checks and the E2E suites, SQL Server 2022 included, on every pull request and push to master. macOS and Windows run before a release and when you start the workflow by hand (Actions → Tests → Run workflow). Starting it by hand with regenerate goldens ticked rewrites the SQL Server fixtures on the real server and uploads them as an artifact to review.

Screenshots

cargo xtask screenshots takes the screenshots again. It restores fixtures/screenshots/forum.sql into the PostgreSQL from docker-compose.yml, starts from the connections, tabs and settings in fixtures/screenshots/data, and plays the scenes in crates/barsql-ui/src/screenshots.rs in a snapshot build. The window is 1920 × 1080 points and stays hidden: each shot renders offscreen at the display's scale and is scaled to 1920 × 1080 pixels, so a Retina Mac and a 125% Windows display give the same size. Windows still needs a display at least that many points across, since it keeps even a hidden window within it. Each is kept as a lossless WebP in docs/screenshots, which the README and the landing page share. It finishes with cargo xtask docs-images, which makes the 640, 800 and 1280px copies, the link preview and the README's video poster.

For a single screenshot, build with cargo build -p barsql --features snapshot, then point BARSQL_SNAPSHOT=out.png at a data folder in BARSQL_DATA_DIR. The app draws its window headless, saves it and quits. BARSQL_SNAPSHOT_SIZE sets the window's size in points (1920x1080), BARSQL_SNAPSHOT_RUN=1 runs the active tab first, and BARSQL_SNAPSHOT_PANEL chooses what the screenshot shows:

  • the sidebar panels: saved, recent, connections
  • the grid: cell, export, json
  • dialogs: connection-dialog, import, about, shortcuts, tips
  • the update dialog: update, update-current, update-downloading, update-ready, update-failed
  • other screens: plan, quick, quick=<query>, suggest=<text>, toasts, palette (the command palette), chart (the first result as a chart, with BARSQL_SNAPSHOT_RUN=1), er (the main schema's ER diagram), structure (a table's Structure tab: the first in main, or structure=<table>)

Demo video

cargo xtask demo-video records the two-minute demo into target/demo-video/BarSQL-demo.mp4 (1080p, 30 fps, H.264) and copies it to docs/demo.mp4, which the landing page plays. It needs ffmpeg (brew install ffmpeg, winget install ffmpeg, or FFMPEG pointing at one) and starts PostgreSQL, MySQL, ClickHouse, libSQL and SQL Server from docker-compose.yml, which stay up afterwards. The forum database gets a staging schema to compare against and a trigger for the schema tree to show, both from fixtures/demo-video/staging.sql, and the other engines get a sample table each, created off camera.

The tour itself is crates/barsql-ui/src/screenshots/video.rs, in the screenshots' hidden 1920 × 1080 point window at zoom 15, with a drawn pointer, typing at a human pace and a caption for each step. It opens on the editor of a forum connection saved off camera, and adds the MySQL connection on camera before the six engines. The camera skips loads and crossfades over changes made off camera. Every frame is rendered offscreen; only the frames that changed are saved, as PNGs in target/demo-video/frames with an ffconcat list of how long each shows, which ffmpeg turns into the video. Change a caption or a step there and run it again; a run takes about 20 minutes, mostly recording.

The README plays a GitHub upload of the video, as GitHub plays only its own uploads there. After a new recording, drag docs/demo.mp4 into the README in GitHub's editor and replace the old upload's link with the new one.

Translations

BarSQL speaks English, Deutsch, Български and Español. A new language is mostly JSON and needs little of the rest of the code; #25 added Spanish and touches every step below.

  1. Copy crates/barsql-ui/locales/base/en.json and crates/barsql-ui/locales/en.json to the language's code, such as fr.json, and translate the values. Keep the keys and placeholders like {count} as they are. Terms developers know in English, such as Commit or Rollback, can stay in English.
  2. Add the language's own name under language in every locales/base/*.json.
  3. Register it in crates/barsql-ui/src:
    • i18n.rs: LANGUAGES, its two include_str! constants and source, plus its digit grouping in format_number
    • actions.rs: a Language… action and its item in View → Language
    • command_palette.rs and workspace.rs: the same action
    • relative_time.rs: phrases such as "yesterday" and "in 3 days"
  4. Add the language to locales in fixtures/golden/ui/relative_time.json, with a column for it in each row.
  5. Run cargo test -p barsql-ui. It names any key the new files miss.
  6. List the language in guide/app.md and on the landing page's "Instant and polished" card.

Plurals have only two forms, key_one and key_other. A language that needs more, such as Polish or Russian, needs a change to t_count first, so open an issue before translating it.

Docs

  • README.md - the front page on GitHub: the pitch, downloads, screenshots and the engines table
  • guide/ - the user guide, one page per area
  • docs/ - the landing page at barsql.bare7a.eu, served by GitHub Pages

A change users can see updates its guide page; the README and the landing page follow headline features only. Preview the landing page over HTTP, since Chrome doesn't load its icons and logos on a file:// page:

python3 -m http.server 8765 --directory docs   # then open http://localhost:8765

Project Structure

├── .github/               # test and release workflows, PR and issue templates
├── Cargo.toml             # the workspace; GPUI Kit pinned to an exact version
├── rust-toolchain.toml    # the Rust version rustup installs
├── docker-compose.yml     # PostgreSQL / MySQL / MariaDB / ClickHouse / libSQL / SQL Server for the E2E suites
├── crates/
│   ├── barsql/            # the binary: startup, single instance, file arguments, --mcp
│   ├── barsql-app/        # orchestration without GPUI: connections, runs, transactions, edits, structure changes, import, backups, updater, MCP server
│   ├── barsql-core/       # domain types, settings, the data folder
│   ├── barsql-db/         # the engines: PostgreSQL, MySQL / MariaDB, SQLite, SQL Server, ClickHouse, Turso / libSQL, SSH tunnels
│   ├── barsql-io/         # CSV and .sql import, export formats, SQL formatting
│   ├── barsql-sql/        # statement splitting, quoting, the read-only check, DDL and ALTER scripts, schema diffs, the SQL language service
│   ├── barsql-storage/    # the JSON files in BarSQL-data
│   └── barsql-ui/         # the GPUI views, locales and whole-window scenarios
├── xtask/                 # cargo xtask: lint, e2e, screenshots, docs-images, icons, package, bump-version
├── docs/                  # the landing page at barsql.bare7a.eu (GitHub Pages) and the README's images
├── guide/                 # the user guide, one page per area
├── fixtures/
│   ├── golden/            # per-engine expectations for the E2E suites
│   └── screenshots/       # the README screenshots' forum database, CSV and data folder
├── packaging/             # the icon and the macOS / Windows / Linux packaging
└── scripts/               # package-macos.sh / package-windows.sh / package-linux.sh

Tech Stack

BarSQL's interface is drawn with GPUI, the UI framework the Zed editor is built on, and the components of GPUI Kit.

  • One Rust codebase from the database drivers to the window
  • The whole window is rendered on the GPU
  • A background runtime (Tokio) talks to the databases, so the UI thread only draws
Layer Technology
Language Rust
UI GPUI + GPUI Kit
Async Tokio
PostgreSQL tokio-postgres
MySQL mysql_async
SQLite rusqlite (bundled SQLite)
SQL Server tiberius
ClickHouse & Turso BarSQL's own HTTP client, on httparse
SSH russh
TLS rustls
Formatting sqlformat
Icons Lucide