@mohxmd/dbstudio 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# dbstudio
+
+> Spin up Drizzle Studio instantly from any database URL — no project setup needed.
+
+## Install
+
+### Global
+```bash
+npm i -g dbstudio
+# or
+bun add -g dbstudio
+```
+
+### Without installing
+```bash
+bunx dbstudio <url>
+# or
+bun x dbstudio <url>
+```
+
+### Standalone binaries
+Download prebuilt binaries from GitHub Releases (Linux/macOS/Windows).
+
+## Usage
+
+```bash
+# PostgreSQL
+dbstudio postgresql://user:pass@localhost:5432/mydb
+
+# MySQL
+dbstudio mysql://user:pass@localhost:3306/mydb
+
+# SQLite
+dbstudio sqlite:./local.db
+
+# Custom port
+dbstudio postgresql://... --port 8080
+
+# Auto-open browser
+dbstudio postgresql://... --open
+
+# Quick share with a temporary public URL
+dbstudio postgresql://... --share
+
+# Named tunnel with your hostname
+dbstudio postgresql://... --share --tunnel dbstudio --hostname db.yourteam.com
+```
+
+## How it works
+
+1. Detects dialect from your URL (postgresql / mysql / sqlite)
+2. Writes a temporary `drizzle.config.ts` in your OS temp directory
+3. Spins up `drizzle-kit studio`
+4. Cleans up the temp file when the process exits (including Ctrl+C)
+
+No project config directory. No project setup. Just pass a URL.
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port` | `4983` | Port to run studio on |
+| `--host` | `127.0.0.1` | Host to bind to (`0.0.0.0` is used automatically with `--share` unless explicitly set) |
+| `--open` | false | Auto-open in browser |
+| `--share` | false | Expose Studio through Cloudflare Tunnel |
+| `--tunnel` | | Named Cloudflare tunnel (requires `--hostname`) |
+| `--hostname` | | Public hostname for named tunnel |
+| `--help` | | Show help |
+| `--version` | | Show version |
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.0
+- `cloudflared` if you use `--share`
+
+## License
+
+MIT

package/lib/commands/studio.ts

@@ -0,0 +1,98 @@
+import type { StudioOptions } from "../utils/args";
+import { detectDialect } from "../utils/dialect";
+import { createDrizzleConfig, cleanupAll } from "../utils/config";
+import { launchTunnel } from "./tunnel";
+import type { ChildProcess } from "child_process";
+
+const procs: ChildProcess[] = [];
+
+function killAll() {
+  for (const p of procs) {
+    if (!p.killed) p.kill("SIGTERM");
+  }
+}
+
+function registerCleanup() {
+  process.on("exit", cleanupAll);
+  process.on("SIGINT", () => {
+    console.log("\n\n👋 Shutting down dbstudio...");
+    killAll();
+    cleanupAll();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    killAll();
+    cleanupAll();
+    process.exit(0);
+  });
+}
+
+export async function runStudioCommand(options: StudioOptions): Promise<number> {
+  const { dbUrl, port, host, shouldOpen, shouldShare, tunnelName, publicHostname } = options;
+
+  const dialect       = detectDialect(dbUrl);
+  const drizzleConfig = createDrizzleConfig(dbUrl, dialect);
+  const safeUrl       = dbUrl.replace(/:\/\/.*@/, "://<credentials>@");
+
+  registerCleanup();
+
+  // Print startup info
+
+  console.log(`\n🚀 dbstudio`);
+  console.log(`   Dialect : ${dialect}`);
+  console.log(`   URL     : ${safeUrl}`);
+  console.log(`   Studio  : https://local.drizzle.studio`);
+
+  if (shouldShare && !tunnelName) {
+    console.log(`   Tunnel  : starting... public URL coming shortly`);
+  }
+  if (tunnelName && publicHostname) {
+    console.log(`   Tunnel  : https://${publicHostname}`);
+  }
+  console.log();
+
+  // Spawn drizzle-kit studio via bunx
+  // bunx is used so the binary works after `bun build --compile`
+  // without needing a local node_modules at runtime
+
+  const studioArgs = [
+    "drizzle-kit",
+    "studio",
+    `--config=${drizzleConfig}`,
+    `--port=${port}`,
+    `--host=${host}`,
+  ];
+
+  if (shouldOpen && !shouldShare) studioArgs.push("--open");
+
+  const studio = Bun.spawn(["bunx", ...studioArgs], {
+    stdin:  "ignore",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  // Launch tunnel after studio boots
+
+  if (shouldShare) {
+    // give drizzle-kit studio a moment to start before tunnel connects
+    await Bun.sleep(2000);
+
+    const tunnel = launchTunnel({ port, tunnelName, publicHostname, shouldOpen });
+    // cast needed since launchTunnel returns node ChildProcess
+    procs.push(tunnel as unknown as ChildProcess);
+
+    if (shouldOpen && tunnelName && publicHostname) {
+      spawn("xdg-open", [`https://${publicHostname}`], { stdio: "ignore" });
+    }
+  }
+
+  // Wait for studio to exit
+
+  const exitCode = await studio.exited;
+  killAll();
+  cleanupAll();
+  return exitCode ?? 0;
+}
+
+// node spawn needed for tunnel (pipe stdio support)
+import { spawn } from "child_process";

package/lib/commands/tunnel.ts

@@ -0,0 +1,60 @@
+import { spawn } from "child_process";
+import { createTunnelConfig } from "../utils/config";
+
+export function launchTunnel(options: {
+  port: string;
+  tunnelName: string | null;
+  publicHostname: string | null;
+  shouldOpen: boolean;
+}) {
+  const { port, tunnelName, publicHostname, shouldOpen } = options;
+
+  let tunnelArgs: string[];
+
+  if (tunnelName && publicHostname) {
+    // named tunnel — generate temp config.yml, never touches ~/.cloudflared/config.yml
+    const tunnelConfigPath = createTunnelConfig(
+      tunnelName,
+      publicHostname,
+      port,
+    );
+    tunnelArgs = ["tunnel", "--config", tunnelConfigPath, "run", tunnelName];
+  } else {
+    // quick share — zero setup, temporary trycloudflare.com URL
+    tunnelArgs = ["tunnel", "--url", `http://localhost:${port}`];
+  }
+
+  const tunnel = spawn("cloudflared", tunnelArgs, {
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+  });
+
+  // cloudflared prints the public URL to stderr
+  tunnel.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString();
+    process.stderr.write(data);
+
+    // quick share: extract and highlight the URL when cloudflared prints it
+    if (!tunnelName) {
+      const match = line.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
+      if (match) {
+        console.log(`\n✅ Public URL: ${match[0]}`);
+        console.log(`   Share this link with your team\n`);
+        if (shouldOpen) {
+          spawn("xdg-open", [match[0]], { stdio: "ignore" });
+        }
+      }
+    }
+  });
+
+  tunnel.on("error", (err) => {
+    console.error(`\n❌ Failed to start cloudflared: ${err.message}`);
+    console.error(`   Install it with: yay -S cloudflared`);
+  });
+
+  tunnel.on("exit", (code) => {
+    if (code !== 0) console.error(`\n⚠️  Tunnel exited with code ${code}`);
+  });
+
+  return tunnel;
+}

package/lib/constants/help.ts

@@ -0,0 +1,33 @@
+export const HELP = `
+dbstudio — spin up Drizzle Studio from any database URL
+
+Usage:
+  dbstudio <database-url> [options]
+
+Examples:
+  dbstudio postgresql://user:pass@localhost:5432/mydb
+  dbstudio mysql://user:pass@localhost:3306/mydb
+  dbstudio sqlite:./local.db
+
+  # Quick share (no CF account needed, temporary URL)
+  dbstudio postgresql://... --share
+
+  # Named tunnel (persistent URL, needs CF account + domain)
+  dbstudio postgresql://... --share --tunnel dbstudio --hostname db.yourteam.com
+
+Options:
+  --port <number>        Port to run studio on (default: 4983)
+  --host <string>        Host to bind to (default: 127.0.0.1, or 0.0.0.0 with --share)
+  --open                 Auto-open in browser
+  --share                Expose via Cloudflare Tunnel
+  --tunnel <name>        Named CF tunnel (requires --hostname)
+  --hostname <domain>    Public hostname for named tunnel
+  -h, --help             Show this help
+  -v, --version          Show version
+
+Tunnel setup (one time):
+  yay -S cloudflared
+  cloudflared tunnel login
+  cloudflared tunnel create <name>
+  # add CNAME in Cloudflare dashboard → <tunnel-id>.cfargotunnel.com
+`;

package/lib/utils/args.ts

@@ -0,0 +1,50 @@
+export type StudioOptions = {
+  dbUrl: string;
+  port: string;
+  host: string;
+  shouldOpen: boolean;
+  shouldShare: boolean;
+  tunnelName: string | null;
+  publicHostname: string | null;
+};
+
+/** Read a flag value in the form `--flag <value>`. */
+function getFlag(args: string[], flag: string): string | null {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return null;
+  const val = args[idx + 1];
+  return val && !val.startsWith("--") ? val : null;
+}
+
+/** Parse and validate CLI arguments into studio runtime options. */
+export function parseStudioOptions(args: string[]): StudioOptions {
+  const dbUrl = args[0];
+
+  if (!dbUrl || dbUrl.startsWith("--")) {
+    throw new Error("Please provide a database URL as the first argument.");
+  }
+
+  const shouldShare = args.includes("--share");
+  const tunnelName = getFlag(args, "--tunnel");
+  const publicHostname = getFlag(args, "--hostname");
+
+  if (tunnelName && !publicHostname) {
+    throw new Error(
+      "--tunnel requires --hostname <your-domain>\n   Example: --tunnel dbstudio --hostname db.yourteam.com",
+    );
+  }
+
+  // when sharing, bind to all interfaces so cloudflared can reach studio
+  const explicitHost = getFlag(args, "--host");
+  const host = explicitHost ?? (shouldShare ? "0.0.0.0" : "127.0.0.1");
+
+  return {
+    dbUrl,
+    port: getFlag(args, "--port") ?? "4983",
+    host,
+    shouldOpen: args.includes("--open"),
+    shouldShare,
+    tunnelName,
+    publicHostname,
+  };
+}

package/lib/utils/config.ts

@@ -0,0 +1,70 @@
+import { writeFileSync, unlinkSync, existsSync } from "fs";
+import { tmpdir, homedir } from "os";
+import { join } from "path";
+import type { Dialect } from "./dialect";
+
+// Temp file registry
+
+const tempFiles: string[] = [];
+
+/** Remove all temporary files created by this process. */
+export function cleanupAll() {
+  for (const f of tempFiles) {
+    if (existsSync(f)) unlinkSync(f);
+  }
+}
+
+/** Write content to a uniquely named file in the OS temp directory. */
+function writeTempFile(name: string, content: string): string {
+  const path = join(tmpdir(), `${name}-${Date.now()}`);
+  writeFileSync(path, content, "utf8");
+  tempFiles.push(path);
+  return path;
+}
+
+// Drizzle config
+
+/** Build a minimal drizzle.config.ts string for the provided database URL. */
+function generateDrizzleConfig(url: string, dialect: Dialect): string {
+  if (dialect === "sqlite") {
+    const filePath = url
+      .replace(/^sqlite:\/\//, "")
+      .replace(/^sqlite:/, "")
+      .replace(/^file:\/\//, "")
+      .replace(/^file:/, "");
+    return `export default {
+  dialect: "sqlite",
+  dbCredentials: { url: "${filePath}" },
+};`;
+  }
+
+  return `export default {
+  dialect: "${dialect}",
+  dbCredentials: { url: "${url}" },
+};`;
+}
+
+/** Create a temp drizzle config file and return its path. */
+export function createDrizzleConfig(url: string, dialect: Dialect): string {
+  return writeTempFile("dbstudio.config.ts", generateDrizzleConfig(url, dialect));
+}
+
+// Cloudflare tunnel config
+
+/** Build a temporary cloudflared config for a named tunnel run. */
+function generateTunnelConfig(tunnelName: string, hostname: string, port: string): string {
+  const credPath = join(homedir(), ".cloudflared");
+  return `tunnel: ${tunnelName}
+credentials-file: ${credPath}/${tunnelName}.json
+
+ingress:
+  - hostname: ${hostname}
+    service: http://localhost:${port}
+  - service: http_status:404
+`;
+}
+
+/** Create a temp cloudflared config file for a named tunnel and return its path. */
+export function createTunnelConfig(tunnelName: string, hostname: string, port: string): string {
+  return writeTempFile("dbstudio-tunnel.yml", generateTunnelConfig(tunnelName, hostname, port));
+}

package/lib/utils/dialect.ts

@@ -0,0 +1,20 @@
+export type Dialect = "postgresql" | "mysql" | "sqlite";
+
+/** Detect Drizzle dialect from a database URL or SQLite-style path. */
+export function detectDialect(url: string): Dialect {
+  if (url.startsWith("postgresql://") || url.startsWith("postgres://"))
+    return "postgresql";
+  if (url.startsWith("mysql://") || url.startsWith("mysql2://")) return "mysql";
+  if (
+    url.startsWith("sqlite:") ||
+    url.startsWith("file:") ||
+    url === ":memory:" ||
+    url.endsWith(".db") ||
+    url.endsWith(".sqlite")
+  )
+    return "sqlite";
+
+  throw new Error(
+    `Could not detect dialect from URL: ${url}\nSupported: postgresql://, mysql://, sqlite:, file:`,
+  );
+}

package/main.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+
+import { HELP } from "./lib/constants/help";
+import { parseStudioOptions } from "./lib/utils/args";
+import { runStudioCommand } from "./lib/commands/studio";
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (args.includes("-v") || args.includes("--version")) {
+  const pkg = await Bun.file(
+    new URL("../package.json", import.meta.url),
+  ).json();
+  console.log(`dbstudio v${pkg.version}`);
+  process.exit(0);
+}
+
+try {
+  const options = parseStudioOptions(args);
+  const code = await runStudioCommand(options);
+  process.exit(code);
+} catch (error) {
+  const msg = error instanceof Error ? error.message : String(error);
+
+  if (msg.startsWith("Please provide")) {
+    console.error(`❌ ${msg}`);
+    console.error("   Run dbstudio --help for usage.");
+  } else if (msg.startsWith("Could not detect")) {
+    console.error(`❌ ${msg}`);
+  } else if (msg.startsWith("--tunnel requires")) {
+    console.error(`❌ ${msg}`);
+  } else {
+    console.error(`❌ Unexpected error: ${msg}`);
+  }
+
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mohxmd/dbstudio",
+  "version": "0.1.0",
+  "description": "Spin up Drizzle Studio from any database URL",
+  "license": "MIT",
+  "type": "module",
+  "module": "main.ts",
+  "bin": {
+    "dbstudio": "./bin/dbstudio"
+  },
+  "scripts": {
+    "start": "bun main.ts",
+    "dev": "bun --watch main.ts",
+    "compile": "bun build main.ts --compile --outfile bin/dbstudio",
+    "compile:linux": "bun build main.ts --compile --target=bun-linux-x64 --outfile bin/dbstudio-linux",
+    "compile:mac": "bun build main.ts --compile --target=bun-darwin-arm64 --outfile bin/dbstudio-mac"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "main.ts",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "drizzle-kit": "latest",
+    "pg": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "latest"
+  }
+}