DataGripe

A web-based database IDE inspired by DataGrip. Bun + React 19 + TypeScript.

datagripe.com · downloads · changelog

Quickstart

No install at all:

bunx @datagripe/cli personal     # or: npx @datagripe/cli personal

DataGripe on http://localhost:3001, with its own PostgreSQL under ~/.local/share/datagripe, no accounts to create, and loopback only. personal pins that shape rather than defaulting to it — without the word, an APP_DATABASE_URL already in your shell is taken as an instruction to run a shared deployment instead.

From a checkout — same thing, with the web app on Vite:

bun install
bun run dev                     # web on :5173, api on :3001

The server starts its own embedded PostgreSQL cluster (data in ./data/pg), migrates it automatically, and runs direct-in without login. Open http://localhost:5173 and you're in.

Shared/external PostgreSQL (e.g. the compose setup):

bun install
docker compose up -d postgres   # or any local Postgres; see .env.example
cp .env.example .env            # sets APP_DATABASE_URL + the two secrets
bun run db:migrate       # optional pre-rollout step; app startup also applies migrations
bun run dev                     # web on :5173, api on :3001, login enabled

Setting APP_DATABASE_URL selects external mode: account auth is on and CONNECTION_ENCRYPTION_KEY/SESSION_SECRET are required. See .env.example for every knob (DATABASE_MODE, AUTH_DISABLED, EMBEDDED_PG_*, WEB_STATIC_DIR).

Accounts sign in with a password, a security key, or Google — set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for the last one, and PASSWORD_AUTH_DISABLED / PASSKEY_AUTH_DISABLED to lock the deployment to the methods you want. The four steps for Google, and every other setting, are on datagripe.com/docs/authentication; the design is in docs/spec/auth-and-hardening.md.

Requires Bun 1.4 (packageManager is pinned). External mode expects PostgreSQL 17.

Deploying it

docker run -p 3001:3001 -v datagripe:/data \
  ghcr.io/datagripe/datagripe

The same zero-config DataGripe in a container. For a shared deployment — a real PostgreSQL, accounts, a hostname — deploy/ has a compose stack, plain Kubernetes manifests, and a Helm chart, all running that image.

The one setting no default can guess is WEB_ORIGIN: the exact origin browsers use. DataGripe compares it against the Origin header on every WebSocket upgrade, and everything in the app runs over that socket.

The image and the npm package are both built from bun run build:dist, which stages the bundled server, its migrations and the built web app into dist/ — see scripts/packaging/build.ts.

Desktop app

An Electrobun shell lives in apps/desktop: it spawns the server in embedded, direct-in mode (data under the OS app-data dir) and loads it in a frameless window — the web app's header is the drag region.

bun run --cwd apps/web build    # the dev shell serves apps/web/dist
cd apps/desktop
hutch electrobun dev            # dev build, runs the server from the checkout
bun run build                   # packaged build under build/

A dev build runs the server straight out of the checkout. A packaged one has no checkout to run, so bun run build first stages the backend — the bundled server, its migrations, the built web app and the PostgreSQL binaries — into apps/desktop/staged/, which Electrobun copies into the app. Running electrobun build on its own skips that step and produces an app that cannot start.

The web app is also an installable PWA (bun run --cwd apps/web build + any static host, or WEB_STATIC_DIR on the server): frameless via window-controls-overlay, with an update-available refresh button in the status bar.

Pushing a v* tag publishes everything: @datagripe/cli to npm, the container image and the Helm chart to GHCR, and the web bundle and desktop builds to a GitHub release. See docs/releasing.md for the steps and the one-time registry setup.

Documentation

• brand/ — the shipped brand assets (app icon, mascot), copied into apps/ and site/ by bun run sync:brand
• AGENTS.md — conventions for changing this repository, including the rule that a change to behaviour is a change to datagripe.com in the same commit
• site/ — datagripe.com: the landing page and the user documentation, deployed to GitHub Pages. User-facing; docs/ below is for people building DataGripe. Four of its pages — the rules, the roadmap, the release notes and the adapter capability table — are rendered from this repository rather than written, so they cannot describe a version that does not exist. Every page is also served as Markdown for agents, indexed in /llms.txt
• deploy/ — compose, Kubernetes manifests, Helm chart
• roadmap.md — phases, progress, scheduling
• docs/initial_idea.md — original engineering handoff
• docs/adr/ — architecture decision records
• docs/moving-a-datasource.md — export a datasource to git and import it elsewhere, without a password in the repo
• docs/operations.md — backups, the audit log, the production checklist
• docs/releasing.md — how a tag becomes a release
• docs/spec/ — feature/subsystem specifications

Documentation is updated in the same change as the behavior it describes; see docs/README.md for conventions and AGENTS.md for what else that change has to touch.