dbcat 0.0.1

package/README.md

@@ -0,0 +1,61 @@
+# dbcat
+
+A simple CLI to view database tables. Supports PostgreSQL, MySQL, and SQLite.
+
+```sh
+bunx dbcat ./data.db
+```
+
+## Usage
+
+Connect to a database to browse all tables:
+
+```sh
+# SQLite file
+bunx dbcat ./database.sqlite
+
+# PostgreSQL
+bunx dbcat postgres://user:pass@localhost:5432/mydb
+
+# MySQL
+bunx dbcat mysql://user:pass@localhost:3306/mydb
+
+# No argument - uses DATABASE_URL environment variable
+bunx dbcat
+```
+
+Run a query by piping SQL:
+
+```sh
+echo "SELECT * FROM users WHERE active = true" | bunx dbcat ./data.db
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--full`, `-f` | Show all rows when browsing tables (default: 100) |
+| `--json` | Output as JSON (indented if TTY) |
+| `--json=color` | Output as normal object console.log |
+
+Piped queries always return all rows.
+
+## Example
+
+```sh
+$ bunx dbcat ./demo.sqlite
+Connected to demo.sqlite
+
+╭─ users ────────────┬───────────────────┬─────────────────────╮
+│ id │ name          │ email             │ created_at          │
+├────┼───────────────┼───────────────────┼─────────────────────┤
+│  1 │ Alice Johnson │ alice@example.com │ 2025-12-08 05:25:21 │
+│  2 │ Bob Smith     │ bob@example.com   │ 2025-12-08 05:25:21 │
+│  3 │ Carol White   │ carol@example.com │ 2025-12-08 05:25:21 │
+│ ... 47 more rows                                             │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+## Requirements
+
+[Bun](https://bun.sh) v1.3+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dbcat",
+  "version": "0.0.1",
+  "description": "A simple CLI to view database tables. Supports PostgreSQL, MySQL, and SQLite.",
+  "author": "RiskyMH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RiskyMH/dbcat"
+  },
+  "homepage": "https://github.com/RiskyMH/dbcat#readme",
+  "bugs": {
+    "url": "https://github.com/RiskyMH/dbcat/issues"
+  },
+  "keywords": [
+    "database",
+    "cli",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "sql",
+    "bun"
+  ],
+  "module": "src/index.ts",
+  "bin": "src/index.ts",
+  "type": "module",
+  "files": [
+    "src/*"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,340 @@
+#!/usr/bin/env bun
+
+import { SQL } from "bun";
+import { printTable } from "./table.ts";
+
+if (typeof Bun !== "object") throw new Error("Please install & use bun!");
+
+export function createConnection(input?: string): InstanceType<typeof SQL> {
+  if (!input) {
+    return new SQL();
+  }
+
+  if (
+    !input.includes("://") &&
+    (input.endsWith(".db") ||
+      input.endsWith(".sqlite") ||
+      input.endsWith(".sqlite3"))
+  ) {
+    return new SQL(`sqlite://${input}`);
+  }
+
+  return new SQL(input);
+}
+
+export async function getDatabaseName(
+  sql: InstanceType<typeof SQL>
+): Promise<string | null> {
+  const adapter = sql.options.adapter;
+
+  switch (adapter) {
+    case "postgres": {
+      const result = await sql`SELECT current_database() as name`;
+      return result[0]?.name ?? null;
+    }
+    case "mysql":
+    case "mariadb": {
+      const result = await sql`SELECT DATABASE() as name`;
+      return result[0]?.name ?? null;
+    }
+    case "sqlite": {
+      const filename = (sql.options as { filename?: string }).filename;
+      if (!filename || filename === ":memory:") return null;
+
+      return filename.split("/").pop() ?? null;
+    }
+    default:
+      return null;
+  }
+}
+
+export function getAllTables(sql: InstanceType<typeof SQL>) {
+  const adapter = sql.options.adapter;
+
+  switch (adapter) {
+    case "postgres":
+      return sql`
+        SELECT table_name as name 
+        FROM information_schema.tables 
+        WHERE table_schema = 'public' 
+        AND table_type = 'BASE TABLE'
+        ORDER BY table_name
+      ` as Promise<{ name: string }[]>;
+    case "mysql":
+    case "mariadb":
+      return sql`
+        SELECT table_name as name 
+        FROM information_schema.tables 
+        WHERE table_schema = DATABASE()
+        AND table_type = 'BASE TABLE'
+        ORDER BY table_name
+      ` as Promise<{ name: string }[]>;
+    case "sqlite":
+      return sql`
+        SELECT name 
+        FROM sqlite_master 
+        WHERE type = 'table' 
+        AND name NOT LIKE 'sqlite_%'
+        ORDER BY name
+      ` as Promise<{ name: string }[]>;
+    default:
+      throw new Error(`Unsupported adapter: ${adapter}`);
+  }
+}
+
+export async function getTableCount(
+  sql: InstanceType<typeof SQL>,
+  tableName: string
+): Promise<number> {
+  const result = await sql`SELECT COUNT(*) as count FROM ${sql(tableName)}`;
+  return Number(result[0]?.count ?? 0);
+}
+
+export function getTableData(
+  sql: InstanceType<typeof SQL>,
+  tableName: string,
+  limit?: number
+) {
+  if (limit === undefined) {
+    return sql`SELECT * FROM ${sql(tableName)}` as Promise<
+      Record<string, unknown>[]
+    >;
+  }
+  return sql`SELECT * FROM ${sql(tableName)} LIMIT ${limit}` as Promise<
+    Record<string, unknown>[]
+  >;
+}
+
+export function runQuery(sql: InstanceType<typeof SQL>, query: string) {
+  return sql.unsafe(query) as Promise<Record<string, unknown>[]>;
+}
+
+export function formatTableOutput(
+  tableName: string,
+  rows: Record<string, unknown>[]
+): string {
+  const lines: string[] = [];
+  lines.push(`\n=== ${tableName} ===`);
+
+  if (rows.length === 0) {
+    lines.push("(empty table)");
+    return lines.join("\n");
+  }
+
+  const maxRows = 100;
+  const displayRows = rows.slice(0, maxRows);
+
+  if (displayRows.length > 0) {
+    const keys = Object.keys(displayRows[0]!);
+    lines.push(keys.join(" | "));
+    lines.push("-".repeat(keys.join(" | ").length));
+    for (const row of displayRows) {
+      lines.push(keys.map((k) => String(row[k] ?? "NULL")).join(" | "));
+    }
+  }
+
+  if (rows.length > maxRows) {
+    lines.push(`... and ${rows.length - maxRows} more rows`);
+  }
+
+  return lines.join("\n");
+}
+
+export function formatQueryResult(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) {
+    return "(no results)";
+  }
+
+  const lines: string[] = [];
+  const keys = Object.keys(rows[0]!);
+  lines.push(keys.join(" | "));
+  lines.push("-".repeat(keys.join(" | ").length));
+  for (const row of rows) {
+    lines.push(keys.map((k) => String(row[k] ?? "NULL")).join(" | "));
+  }
+  lines.push(`\n${rows.length} row(s)`);
+
+  return lines.join("\n");
+}
+
+function displayTable(
+  tableName: string,
+  rows: Record<string, unknown>[],
+  totalRows?: number,
+  maxRows?: number
+) {
+  console.log();
+  printTable(rows, { title: tableName, totalRows, maxRows });
+}
+
+function displayQueryResult(rows: Record<string, unknown>[]) {
+  printTable(rows, { title: "Result", maxRows: Infinity });
+}
+
+async function readStdin(): Promise<string | null> {
+  if (process.stdin.isTTY) {
+    return null;
+  }
+
+  try {
+    const text = await Bun.stdin.text();
+    return text.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+type JsonMode = false | "plain" | "color";
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let input: string | undefined;
+  let full = false;
+  let json: JsonMode = false;
+
+  for (const arg of args) {
+    if (arg === "--full" || arg === "-f") {
+      full = true;
+    } else if (arg === "--json") {
+      json = "plain";
+    } else if (arg === "--json=color") {
+      json = "color";
+    } else if (!arg.startsWith("-")) {
+      input = arg;
+    }
+  }
+
+  return { input, full, json };
+}
+
+const DEFAULT_LIMIT = 100;
+
+function showUsageAndExit(): never {
+  console.error("Usage: dbcli <database>");
+  console.error("");
+  console.error("Examples:");
+  console.error("  dbcli ./data.db");
+  console.error("  dbcli postgres://user:pass@localhost/mydb");
+  console.error("  dbcli mysql://user:pass@localhost/mydb");
+  console.error("");
+  console.error("Or set DATABASE_URL environment variable.");
+  process.exit(1);
+}
+
+function outputJson(data: unknown, color: boolean) {
+  if (color) {
+    console.log(Bun.inspect(data, { colors: true, depth: Infinity }));
+  } else {
+    const indent = process.stdout.isTTY ? 2 : undefined;
+    console.log(JSON.stringify(data, null, indent));
+  }
+}
+
+async function main() {
+  const { input, full, json } = parseArgs();
+
+  if (!input && !process.env.DATABASE_URL) {
+    showUsageAndExit();
+  }
+
+  let sql: InstanceType<typeof SQL>;
+  try {
+    sql = createConnection(input);
+  } catch (error) {
+    console.error("Failed to connect:");
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+
+  const isTTY = process.stdout.isTTY;
+  const dim = Bun.enableANSIColors ? "\x1b[2m" : "";
+  const reset = Bun.enableANSIColors ? "\x1b[0m" : "";
+  const bold = Bun.enableANSIColors ? "\x1b[1m" : "";
+  const clearLine = "\x1b[2K\r";
+
+  try {
+    const stdinQuery = await readStdin();
+
+    if (stdinQuery) {
+      const results = await runQuery(sql, stdinQuery);
+      if (json) {
+        outputJson(results, json === "color");
+      } else {
+        displayQueryResult(results);
+      }
+    } else {
+      if (isTTY && !json) {
+        process.stdout.write(
+          `${dim}Connecting to ${sql.options.adapter}...${reset}`
+        );
+      }
+
+      const [dbName, tables] = await Promise.all([
+        getDatabaseName(sql),
+        getAllTables(sql),
+      ]);
+
+      if (json) {
+        const result: Record<string, unknown[]> = {};
+        for (const table of tables) {
+          const data = full
+            ? await getTableData(sql, table.name)
+            : await getTableData(sql, table.name, DEFAULT_LIMIT);
+          result[table.name] = data;
+        }
+        outputJson(result, json === "color");
+      } else {
+        const dbDisplay = dbName
+          ? `${bold}${dbName}${reset}`
+          : `${bold}${sql.options.adapter}${reset} ${dim}database${reset}`;
+        if (isTTY) {
+          process.stdout.write(
+            `${clearLine}${dim}Connected to${reset} ${dbDisplay}\n`
+          );
+        } else {
+          console.log(`Connected to ${dbName || sql.options.adapter}`);
+        }
+
+        if (tables.length === 0) {
+          console.log(`${dim}No tables found.${reset}`);
+        } else {
+          for (const table of tables) {
+            if (full) {
+              const data = await getTableData(sql, table.name);
+              displayTable(table.name, data, undefined, Infinity);
+            } else {
+              const [count, data] = await Promise.all([
+                getTableCount(sql, table.name),
+                getTableData(sql, table.name, DEFAULT_LIMIT),
+              ]);
+              displayTable(table.name, data, count, DEFAULT_LIMIT);
+            }
+          }
+        }
+      }
+    }
+  } catch (error) {
+    if (isTTY && !json) {
+      process.stdout.write(clearLine);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (
+      message.includes("Connection") ||
+      message.includes("connect") ||
+      message.includes("ECONNREFUSED")
+    ) {
+      console.error(`Failed to connect to ${sql.options.adapter}:`);
+    } else {
+      console.error("Error:");
+    }
+    console.error(message);
+    process.exit(1);
+  } finally {
+    await sql.close();
+  }
+}
+
+if (import.meta.main) {
+  main();
+}

package/src/table.ts

@@ -0,0 +1,297 @@
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+
+const BOX = {
+  topLeft: "╭",
+  topRight: "╮",
+  bottomLeft: "╰",
+  bottomRight: "╯",
+  horizontal: "─",
+  vertical: "│",
+  headerLeft: "├",
+  headerRight: "┤",
+  headerCross: "┼",
+  topCross: "┬",
+  bottomCross: "┴",
+};
+
+function getTerminalWidth(): number {
+  return process.stdout.columns || 120;
+}
+
+function formatValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    const dim = Bun.enableANSIColors ? DIM : "";
+    const reset = Bun.enableANSIColors ? RESET : "";
+    return `${dim}NULL${reset}`;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return Bun.inspect(value, { colors: Bun.enableANSIColors, depth: 2 });
+}
+
+function truncate(str: string, maxWidth: number): string {
+  const width = Bun.stringWidth(str);
+  if (width <= maxWidth) {
+    return str;
+  }
+
+  let low = 0;
+  let high = str.length;
+
+  while (low < high) {
+    const mid = Math.floor((low + high + 1) / 2);
+    if (Bun.stringWidth(str.slice(0, mid)) + 1 <= maxWidth) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  const truncated = str.slice(0, low) + "…";
+  return Bun.enableANSIColors ? truncated + RESET : truncated;
+}
+
+function padRight(str: string, width: number): string {
+  const strWidth = Bun.stringWidth(str);
+  if (strWidth >= width) {
+    return str;
+  }
+  return str + " ".repeat(width - strWidth);
+}
+
+function padLeft(str: string, width: number): string {
+  const strWidth = Bun.stringWidth(str);
+  if (strWidth >= width) {
+    return str;
+  }
+  return " ".repeat(width - strWidth) + str;
+}
+
+export interface TableOptions {
+  maxRows?: number;
+  title?: string;
+  totalRows?: number;
+}
+
+export function printTable(
+  rows: Record<string, unknown>[],
+  options: TableOptions = {}
+): void {
+  const { maxRows = 100, title, totalRows } = options;
+  const dim = Bun.enableANSIColors ? DIM : "";
+  const reset = Bun.enableANSIColors ? RESET : "";
+  const bold = Bun.enableANSIColors ? BOLD : "";
+
+  if (rows.length === 0) {
+    if (title) {
+      const contentWidth = Math.max(
+        Bun.stringWidth("(empty)"),
+        Bun.stringWidth(title)
+      );
+      const innerWidth = contentWidth + 2;
+      const titleDisplay = ` ${title} `;
+      const titleWidth = Bun.stringWidth(titleDisplay);
+      const remainingWidth = innerWidth - titleWidth;
+      console.log(
+        `${dim}${BOX.topLeft}${
+          BOX.horizontal
+        }${reset}${bold}${titleDisplay}${reset}${dim}${BOX.horizontal.repeat(
+          Math.max(0, remainingWidth)
+        )}${BOX.topRight}${reset}`
+      );
+      console.log(
+        `${dim}${BOX.vertical}${reset} ${padRight(
+          "(empty)",
+          contentWidth
+        )} ${dim}${BOX.vertical}${reset}`
+      );
+      console.log(
+        `${dim}${BOX.bottomLeft}${BOX.horizontal.repeat(innerWidth)}${
+          BOX.bottomRight
+        }${reset}`
+      );
+    } else {
+      console.log("(empty)");
+    }
+    return;
+  }
+
+  const rowCount = rows.length;
+  const displayRows = maxRows === Infinity ? rows : rows.slice(0, maxRows);
+  const allColumns = Object.keys(displayRows[0]!);
+  const termWidth = getTerminalWidth();
+
+  const isNumericCol: boolean[] = allColumns.map((col) => {
+    return displayRows.every((row) => {
+      const val = row[col];
+      return (
+        val === null ||
+        val === undefined ||
+        typeof val === "number" ||
+        typeof val === "bigint"
+      );
+    });
+  });
+
+  const colWidths: number[] = allColumns.map((col) => Bun.stringWidth(col));
+  const formattedRows: string[][] = displayRows.map((row) =>
+    allColumns.map((col, i) => {
+      const formatted = formatValue(row[col]).replace(/\n/g, " ");
+      colWidths[i] = Math.max(colWidths[i]!, Bun.stringWidth(formatted));
+      return formatted;
+    })
+  );
+
+  const minColWidth = 3;
+  const borderOverhead = 4 + (allColumns.length - 1) * 3;
+  let availableForColumns = termWidth - borderOverhead;
+
+  let columns = allColumns;
+  let hiddenCols = 0;
+
+  while (
+    columns.length * minColWidth > availableForColumns &&
+    columns.length > 1
+  ) {
+    columns = columns.slice(0, -1);
+    hiddenCols++;
+    availableForColumns = termWidth - (4 + (columns.length - 1) * 3);
+  }
+
+  const visibleColWidths = colWidths.slice(0, columns.length);
+  const visibleFormattedRows = formattedRows.map((row) =>
+    row.slice(0, columns.length)
+  );
+  const visibleIsNumeric = isNumericCol.slice(0, columns.length);
+
+  let totalWidth = visibleColWidths.reduce((a, b) => a + b, 0);
+
+  if (totalWidth > availableForColumns) {
+    const headerWidths = columns.map((col) =>
+      Math.max(minColWidth, Bun.stringWidth(col))
+    );
+    const sqrtWidths = visibleColWidths.map((w) => Math.sqrt(w));
+    const sqrtTotal = sqrtWidths.reduce((a, b) => a + b, 0);
+
+    for (let i = 0; i < visibleColWidths.length; i++) {
+      const fair = Math.floor(
+        (sqrtWidths[i]! / sqrtTotal) * availableForColumns
+      );
+      visibleColWidths[i] = Math.max(headerWidths[i]!, fair);
+    }
+
+    totalWidth = visibleColWidths.reduce((a, b) => a + b, 0);
+    while (
+      totalWidth > availableForColumns &&
+      visibleColWidths.some((w) => w > minColWidth)
+    ) {
+      let maxIdx = 0;
+      for (let i = 1; i < visibleColWidths.length; i++) {
+        if (visibleColWidths[i]! > visibleColWidths[maxIdx]!) maxIdx = i;
+      }
+      visibleColWidths[maxIdx]!--;
+      totalWidth--;
+    }
+  }
+
+  const actualTotal = totalRows ?? rowCount;
+  const truncatedRows =
+    actualTotal > displayRows.length ? actualTotal - displayRows.length : 0;
+  let infoText = "";
+  if (truncatedRows > 0 || hiddenCols > 0) {
+    const parts: string[] = [];
+    if (truncatedRows > 0)
+      parts.push(`${truncatedRows} more row${truncatedRows > 1 ? "s" : ""}`);
+    if (hiddenCols > 0)
+      parts.push(`${hiddenCols} more column${hiddenCols > 1 ? "s" : ""}`);
+    infoText = `... ${parts.join(", ")}`;
+  }
+
+  const contentWidth =
+    visibleColWidths.reduce((a, b) => a + b, 0) + (columns.length - 1) * 3;
+
+  const titleWidth = title ? Bun.stringWidth(title) + 4 : 0;
+  const maxInnerWidth = termWidth - 4;
+  const innerWidth = Math.min(
+    Math.max(contentWidth, titleWidth),
+    maxInnerWidth
+  );
+
+  const totalInnerWidth = innerWidth + 2;
+
+  if (innerWidth > contentWidth && visibleColWidths.length > 0) {
+    visibleColWidths[visibleColWidths.length - 1]! += innerWidth - contentWidth;
+  }
+
+  const topBorder = visibleColWidths
+    .map((w) => BOX.horizontal.repeat(w))
+    .join(`${BOX.horizontal}${BOX.topCross}${BOX.horizontal}`);
+  const fullTopBorder = `${BOX.topLeft}${BOX.horizontal}${topBorder}${BOX.horizontal}${BOX.topRight}`;
+  if (title) {
+    const titleDisplay = ` ${title} `;
+    const titleDisplayWidth = Bun.stringWidth(titleDisplay);
+
+    const beforeTitle = fullTopBorder.slice(0, 2);
+    const afterTitle = fullTopBorder.slice(2 + titleDisplayWidth);
+    console.log(
+      `${dim}${beforeTitle}${reset}${bold}${titleDisplay}${reset}${dim}${afterTitle}${reset}`
+    );
+  } else {
+    console.log(`${dim}${fullTopBorder}${reset}`);
+  }
+
+  const header = columns
+    .map((col, i) => {
+      const truncated = truncate(col, visibleColWidths[i]!);
+      return visibleIsNumeric[i]
+        ? padLeft(truncated, visibleColWidths[i]!)
+        : padRight(truncated, visibleColWidths[i]!);
+    })
+    .join(` ${dim}${BOX.vertical}${reset} `);
+  console.log(
+    `${dim}${BOX.vertical}${reset} ${header} ${dim}${BOX.vertical}${reset}`
+  );
+
+  const headerSep = visibleColWidths
+    .map((w) => BOX.horizontal.repeat(w))
+    .join(`${BOX.horizontal}${BOX.headerCross}${BOX.horizontal}`);
+  console.log(
+    `${dim}${BOX.headerLeft}${BOX.horizontal}${headerSep}${BOX.horizontal}${BOX.headerRight}${reset}`
+  );
+
+  for (const row of visibleFormattedRows) {
+    const line = row
+      .map((val, i) => {
+        const truncated = truncate(val, visibleColWidths[i]!);
+        return visibleIsNumeric[i]
+          ? padLeft(truncated, visibleColWidths[i]!)
+          : padRight(truncated, visibleColWidths[i]!);
+      })
+      .join(` ${dim}${BOX.vertical}${reset} `);
+    console.log(
+      `${dim}${BOX.vertical}${reset} ${line} ${dim}${BOX.vertical}${reset}`
+    );
+  }
+
+  if (infoText) {
+    const truncatedInfo = truncate(infoText, innerWidth);
+    const infoLine = padRight(truncatedInfo, innerWidth);
+    console.log(`${dim}${BOX.vertical} ${infoLine} ${BOX.vertical}${reset}`);
+
+    console.log(
+      `${dim}${BOX.bottomLeft}${BOX.horizontal.repeat(totalInnerWidth)}${
+        BOX.bottomRight
+      }${reset}`
+    );
+  } else {
+    const bottomBorder = visibleColWidths
+      .map((w) => BOX.horizontal.repeat(w))
+      .join(`${BOX.horizontal}${BOX.bottomCross}${BOX.horizontal}`);
+    console.log(
+      `${dim}${BOX.bottomLeft}${BOX.horizontal}${bottomBorder}${BOX.horizontal}${BOX.bottomRight}${reset}`
+    );
+  }
+}