@hienlh/ppm 0.6.2 → 0.6.4

package/docs/system-architecture.md

@@ -18,16 +18,18 @@
 │  │              Hono HTTP Framework (Port 8080)                   │   │
 │  ├────────────────────────────────────────────────────────────────┤   │
 │  │  Routes (src/server/routes/)                                   │   │
-│  │  ┌──────────────────┐  ┌──────────────────┐  ┌─────────────┐  │   │
-│  │  │ /api/projects    │  │ /api/project/:n/ │  │ /api/health │  │   │
-│  │  │ (CRUD projects)  │  │ (scoped routes)  │  │   (status)  │  │   │
-│  │  └──────────────────┘  └──────────────────┘  └─────────────┘  │   │
+│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │   │
+│  │  │ /api/projects    │  │ /api/project/:n/ │  │ /api/db/*    │  │   │
+│  │  │ (CRUD projects)  │  │ (scoped routes)  │  │ (connections)│  │   │
+│  │  └──────────────────┘  └──────────────────┘  └──────────────┘  │   │
 │  ├────────────────────────────────────────────────────────────────┤   │
 │  │  Services (src/services/)                                      │   │
 │  │  ┌───────────────────────────────────────────────────────────┐│   │
 │  │  │ ChatService │ GitService │ FileService │ TerminalService ││   │
 │  │  │ (streaming  │ (simple-   │ (read/write │ (PTY/shell)     ││   │
 │  │  │  messages)  │  git)      │  files)     │ (Bun.spawn)     ││   │
+│  │  │ TableCache  │ DbService  │ DatabaseAdapterRegistry         ││   │
+│  │  │ (metadata)  │ (SQLite)   │ (SQLite, PostgreSQL adapters)   ││   │
 │  │  └───────────────────────────────────────────────────────────┘│   │
 │  ├────────────────────────────────────────────────────────────────┤   │
 │  │  Providers (src/providers/)                                    │   │
@@ -45,8 +47,10 @@
 │  │ SQLite DB        │  │ Git Repos        │  │ Session Storage │    │
 │  │ (config, projs)  │  │ (local disk)     │  │ (SQLite + SDK)  │    │
 │  │ (session map)    │  │                  │  │ (session_map,   │    │
-│  │ (push subs,      │  │                  │  │  session_logs,  │    │
-│  │  usage, logs)    │  │                  │  │  usage_history) │    │
+│  │ (push subs,      │  │ Connections:     │  │  session_logs,  │    │
+│  │  usage, logs)    │  │ • SQLite files   │  │  usage_history) │    │
+│  │ (connections)    │  │ • PostgreSQL svr │  │  (connections)  │    │
+│  │ (table metadata) │  │   via connStr    │  │                 │    │
 │  └──────────────────┘  └──────────────────┘  └─────────────────┘    │
 └──────────────────────────────────────────────────────────────────────┘
         ↓↑
@@ -119,6 +123,15 @@ POST   /api/project/:name/git/commit              → Commit
 GET    /api/project/:name/files/tree              → Directory tree
 GET    /api/project/:name/files/raw               → File content
 PUT    /api/project/:name/files/write             → Write file
+GET    /api/db/connections                        → List all connections
+POST   /api/db/connections                        → Create connection (SQLite/PostgreSQL)
+GET    /api/db/connections/:id                    → Get connection (sanitized)
+PUT    /api/db/connections/:id                    → Update connection (toggle readonly, UI-only)
+DELETE /api/db/connections/:id                    → Delete connection
+GET    /api/db/connections/:id/tables             → List tables (with sync)
+GET    /api/db/connections/:id/tables/:table      → Get table schema + data
+POST   /api/db/connections/:id/query              → Execute query (readonly checked)
+PATCH  /api/db/connections/:id/cell               → Update cell value (single)
 WS     /ws/project/:name/chat/:sessionId          → Chat streaming
 WS     /ws/project/:name/terminal/:id             → Terminal I/O
 ```
@@ -140,7 +153,8 @@ WS     /ws/project/:name/terminal/:id             → Terminal I/O
 |---------|---------|-------------|
 | **ChatService** | Session management, message streaming | createSession, streamMessage, getHistory |
 | **ConfigService** | Config loading (YAML→SQLite migration) | load, save, getToken |
-| **DbService** | SQLite persistence (6 tables, WAL) | getDb, openTestDb, schema migrations |
+| **DbService** | SQLite persistence (8 tables, WAL, connections CRUD) | getDb, openTestDb, getConnections, insertConnection, updateConnection, deleteConnection, getTableCache |
+| **TableCacheService** | Cache table metadata, search tables | syncTables, searchTables, invalidateCache |
 | **GitService** | Git command execution | status, diff, commit, stage, branch |
 | **FileService** | File operations with validation | read, write, tree, delete, mkdir |
 | **TerminalService** | PTY lifecycle, shell spawning | spawn, write, kill |
@@ -151,6 +165,9 @@ WS     /ws/project/:name/terminal/:id             → Terminal I/O
 | **ProviderRegistry** | AI provider routing | getDefault, send (delegates) |
 | **CloudflaredService** | Download cloudflared binary | ensureCloudflared, getCloudflaredPath |
 | **TunnelService** | Cloudflare Quick Tunnel lifecycle | startTunnel, stopTunnel, getTunnelUrl |
+| **DatabaseAdapterRegistry** | Register/retrieve DB adapters (extensible) | registerAdapter, getAdapter |
+| **SQLiteAdapter** | SQLite connection, query execution, readonly checks | testConnection, getTables, getTableSchema, getTableData, executeQuery, updateCell |
+| **PostgresAdapter** | PostgreSQL connection, query execution, readonly checks | testConnection, getTables, getTableSchema, getTableData, executeQuery, updateCell |
 
 **Key Files:** `src/services/*.service.ts`
 
@@ -544,6 +561,204 @@ UI updates: "src/index.ts" moves from "Unstaged" to "Staged"
 
 ---
 
+## Database Management (v2.0+)
+
+### Architecture Overview
+
+PPM now supports managing external databases (SQLite & PostgreSQL) through a unified adapter pattern:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Web UI (React)                               │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ Database Sidebar                                         │   │
+│  │ • Connection List (with color badges)                    │   │
+│  │ • Create/Edit Connection Form                            │   │
+│  │ • Color Picker (WCAG contrast-aware)                     │   │
+│  │ • Query Execution UI                                     │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────┬───────────────────────────────────────────────┘
+                  │ HTTP REST / WebSocket
+┌─────────────────┴───────────────────────────────────────────────┐
+│                    PPM Server (Hono)                            │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ /api/db Routes                                           │   │
+│  │ • GET  /connections        → List all connections        │   │
+│  │ • POST /connections        → Create connection           │   │
+│  │ • GET  /connections/:id    → Get connection (sanitized)  │   │
+│  │ • PUT  /connections/:id    → Update (readonly toggle)    │   │
+│  │ • DELETE /connections/:id  → Remove connection           │   │
+│  │ • GET  /connections/:id/tables      → List + sync tables │   │
+│  │ • GET  /connections/:id/tables/:tbl → Schema + data      │   │
+│  │ • POST /connections/:id/query       → Execute query      │   │
+│  │ • PATCH /connections/:id/cell       → Update cell        │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ Service Layer                                            │   │
+│  │ • DbService (connection CRUD, caching)                   │   │
+│  │ • TableCacheService (metadata cache, search)             │   │
+│  │ • DatabaseAdapterRegistry (extensible)                   │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ Adapters (Pluggable Pattern)                             │   │
+│  │ • SQLiteAdapter → Uses `bun:sqlite` for local files      │   │
+│  │ • PostgresAdapter → Uses postgres driver for servers     │   │
+│  │ • isReadOnlyQuery() → Safety check (CTE-safe regex)      │   │
+│  │ • readonly=1 by default (safe-by-default)               │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────┘
+        ↓↑
+   ┌────────────────────────────────────────────┐
+   │  External Databases                         │
+   │  • SQLite files (path: /path/to/db.db)      │
+   │  • PostgreSQL servers (connStr: postgres://)│
+   └────────────────────────────────────────────┘
+```
+
+### DatabaseAdapter Pattern (Extensible)
+
+**Interface** (`src/types/database.ts`):
+```typescript
+interface DatabaseAdapter {
+  testConnection(config: DbConnectionConfig): Promise<{ ok: boolean; error?: string }>;
+  getTables(config: DbConnectionConfig): Promise<DbTableInfo[]>;
+  getTableSchema(config: DbConnectionConfig, table: string, schema?: string): Promise<DbColumnInfo[]>;
+  getTableData(config: DbConnectionConfig, table: string, opts: {...}): Promise<DbPagedData>;
+  executeQuery(config: DbConnectionConfig, sql: string): Promise<DbQueryResult>;
+  updateCell(config: DbConnectionConfig, table: string, opts: {...}): Promise<void>;
+}
+```
+
+**Implementations:**
+1. **SQLiteAdapter** — Local file-based SQLite via `bun:sqlite`
+   - testConnection: Opens file, runs pragma check
+   - Supports: SELECT, INSERT, UPDATE, DELETE (if writable), CREATE TABLE
+
+2. **PostgresAdapter** — Remote PostgreSQL servers via postgres driver
+   - testConnection: Attempts connection with credentials
+   - Supports: Full SQL except DDL on readonly connections
+
+**Registry Pattern** (`src/services/database/adapter-registry.ts`):
+```typescript
+registerAdapter("sqlite", new SQLiteAdapter());
+registerAdapter("postgres", new PostgresAdapter());
+// Can be extended: registerAdapter("mysql", new MysqlAdapter());
+```
+
+### Security Design
+
+**Readonly by Default:**
+- All connections created with `readonly = true` in database
+- Default: read-only query execution (safe-by-default)
+- Web UI toggle: Switch to writable (admin decision only)
+- CLI: Cannot disable readonly via command-line (browser only)
+
+**Readonly Query Detection:**
+```typescript
+// isReadOnlyQuery() in src/services/database/readonly-check.ts
+// Checks for: SELECT, PRAGMA, EXPLAIN, WITH (CTE)
+// Rejects: INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, etc.
+// CTE-safe: Handles "WITH AS SELECT" (wraps CTE result check)
+```
+
+**Credential Handling:**
+- Connection credentials stored in SQLite `connections` table as `connection_config` JSON
+- **NEVER** returned in API responses (stripped by `sanitizeConn()` in routes)
+- Only used internally by adapters when executing queries
+- Frontend never sees passwords/connection strings
+
+**API Security:**
+- All `/api/db` requests require valid auth token (middleware checked)
+- Connection IDs are numeric (no enumeration risk)
+- Connection color is user-specific (cosmetic only, not sensitive)
+
+### Data Flow: Query Execution
+
+```
+User opens Database tab
+    ↓
+DatabaseSidebar fetches: GET /api/db/connections
+    ↓
+ConnectionList displays (sanitized, no credentials)
+    ↓
+User clicks connection → GET /api/db/connections/:id/tables
+    ↓
+DbService.getConnections() reads from SQLite
+    ↓
+TableCacheService.syncTables() calls adapter.getTables()
+    ↓
+SQLiteAdapter/PostgresAdapter queries database
+    ↓
+Results cached in table_metadata table
+    ↓
+UI displays table list + schema
+    ↓
+User selects table → GET /api/db/connections/:id/tables/:table
+    ↓
+Adapter.getTableData() executes paginated query
+    ↓
+Results returned: { columns, rows, total, page, limit }
+    ↓
+UI renders table grid with pagination
+    ↓
+User executes custom query → POST /api/db/connections/:id/query
+    ↓
+isReadOnlyQuery() checks SQL (rejects writes if readonly=true)
+    ↓
+Adapter.executeQuery() runs SQL
+    ↓
+Results returned: { columns, rows, rowsAffected, changeType }
+    ↓
+UI displays results (read-only highlight if mutation was blocked)
+```
+
+### Connection Storage
+
+**SQLite Schema** (in `~/.ppm/ppm.db`):
+```sql
+CREATE TABLE connections (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  type TEXT NOT NULL, -- 'sqlite' | 'postgres'
+  name TEXT NOT NULL,
+  connection_config TEXT NOT NULL, -- JSON: { path, connectionString, ... }
+  readonly INTEGER DEFAULT 1, -- 1 = readonly, 0 = writable (UI-only toggle)
+  group_name TEXT,
+  color TEXT, -- Optional hex color (#3b82f6)
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE table_metadata (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  connection_id INTEGER NOT NULL REFERENCES connections(id) ON DELETE CASCADE,
+  table_name TEXT NOT NULL,
+  schema_name TEXT DEFAULT 'public',
+  row_count INTEGER,
+  last_synced TEXT,
+  UNIQUE(connection_id, table_name, schema_name)
+);
+```
+
+### CLI Support (ppm db)
+
+**Commands** (`src/cli/commands/db-cmd.ts`):
+```bash
+ppm db connections           # List all connections
+ppm db connect               # Add new connection (interactive)
+ppm db remove <name>         # Delete connection
+ppm db query <name> <sql>    # Execute query (respects readonly)
+ppm db tables <name>         # List tables
+ppm db schema <name> <table> # Show table schema
+ppm db data <name> <table>   # Show table data (paginated)
+```
+
+**CLI Safety:**
+- Always respects readonly flag (cannot override via CLI)
+- Uses same adapter/validation as web UI
+- Table formatting for terminal output
+
+---
+
 ## Deployment Architecture
 
 ### Single-Machine Deployment (Current)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "module": "src/index.ts",
   "type": "module",

package/src/cli/commands/db-cmd.ts

@@ -0,0 +1,355 @@
+import { Command } from "commander";
+import { isReadOnlyQuery } from "../../services/database/readonly-check.ts";
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+  magenta: "\x1b[35m",
+};
+
+function printTable(headers: string[], rows: string[][]): void {
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)),
+  );
+  const sep = colWidths.map((w) => "-".repeat(w + 2)).join("+");
+  const headerLine = headers.map((h, i) => ` ${h.padEnd(colWidths[i]!)} `).join("|");
+  console.log(`+${sep}+`);
+  console.log(`|${C.bold}${headerLine}${C.reset}|`);
+  console.log(`+${sep}+`);
+  for (const row of rows) {
+    const line = row.map((cell, i) => ` ${(cell ?? "").padEnd(colWidths[i]!)} `).join("|");
+    console.log(`|${line}|`);
+  }
+  console.log(`+${sep}+`);
+}
+
+function formatRows(columns: string[], rows: Record<string, unknown>[], limit = 50): void {
+  if (rows.length === 0) {
+    console.log(`${C.dim}(no rows)${C.reset}`);
+    return;
+  }
+  const displayRows = rows.slice(0, limit);
+  const strRows = displayRows.map((r) =>
+    columns.map((c) => {
+      const v = r[c];
+      if (v === null || v === undefined) return `${C.dim}NULL${C.reset}`;
+      const s = String(v);
+      return s.length > 60 ? s.slice(0, 57) + "..." : s;
+    }),
+  );
+  printTable(columns, strRows);
+  if (rows.length > limit) {
+    console.log(`${C.dim}... and ${rows.length - limit} more rows${C.reset}`);
+  }
+}
+
+/** Parse connection_config JSON and return the connection string or path */
+function parseConfig(row: { type: string; connection_config: string }): { type: string; path?: string; connectionString?: string } {
+  const cfg = JSON.parse(row.connection_config);
+  return { type: row.type, ...cfg };
+}
+
+/** Mask password in postgres connection string: postgresql://user:pass@host → postgresql://user:***@host */
+function maskPassword(connectionString: string): string {
+  return connectionString.replace(/(:\/\/[^:]+:)[^@]+(@)/, "$1***$2");
+}
+
+
+export function registerDbCommands(program: Command): void {
+  const db = program.command("db").description("Manage database connections and execute queries");
+
+  // ── ppm db list ──────────────────────────────────────────────────────
+  db.command("list")
+    .description("List all saved database connections")
+    .action(async () => {
+      try {
+        const { getConnections } = await import("../../services/db.service.ts");
+        const conns = getConnections();
+        if (conns.length === 0) {
+          console.log(`${C.yellow}No connections saved.${C.reset} Run: ppm db add`);
+          return;
+        }
+        const rows = conns.map((c) => {
+          const cfg = parseConfig(c);
+          let target = cfg.connectionString ?? cfg.path ?? "-";
+          // Mask password in postgres connection strings
+          if (cfg.connectionString) target = maskPassword(target);
+          const display = target.length > 70 ? target.slice(0, 67) + "..." : target;
+          const ro = c.readonly ? `${C.yellow}RO${C.reset}` : `${C.green}RW${C.reset}`;
+          return [String(c.id), c.name, c.type, c.group_name ?? "-", ro, display];
+        });
+        printTable(["ID", "Name", "Type", "Group", "RO", "Connection"], rows);
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db add ───────────────────────────────────────────────────────
+  db.command("add")
+    .description("Add a new database connection")
+    .requiredOption("-n, --name <name>", "Connection name (unique)")
+    .requiredOption("-t, --type <type>", "Database type: sqlite | postgres")
+    .option("-c, --connection-string <url>", "PostgreSQL connection string")
+    .option("-f, --file <path>", "SQLite file path (absolute)")
+    .option("-g, --group <group>", "Group name")
+    .option("--color <color>", "Tab color (hex, e.g. #3b82f6)")
+    .action(async (options) => {
+      try {
+        const { insertConnection } = await import("../../services/db.service.ts");
+        const type = options.type as "sqlite" | "postgres";
+
+        if (!["sqlite", "postgres"].includes(type)) {
+          console.error(`${C.red}Error:${C.reset} --type must be 'sqlite' or 'postgres'`);
+          process.exit(1);
+        }
+
+        let config: import("../../services/db.service.ts").ConnectionConfig;
+        if (type === "postgres") {
+          if (!options.connectionString) {
+            console.error(`${C.red}Error:${C.reset} PostgreSQL requires --connection-string`);
+            process.exit(1);
+          }
+          config = { type: "postgres", connectionString: options.connectionString };
+        } else {
+          if (!options.file) {
+            console.error(`${C.red}Error:${C.reset} SQLite requires --file (absolute path)`);
+            process.exit(1);
+          }
+          const { resolve } = await import("node:path");
+          config = { type: "sqlite", path: resolve(options.file) };
+        }
+
+        const conn = insertConnection(type, options.name, config, options.group, options.color);
+        console.log(`${C.green}Added connection:${C.reset} ${conn.name} (${conn.type}) #${conn.id}`);
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db remove ────────────────────────────────────────────────────
+  db.command("remove <name>")
+    .description("Remove a saved connection (by name or ID)")
+    .action(async (nameOrId: string) => {
+      try {
+        const { deleteConnection } = await import("../../services/db.service.ts");
+        if (deleteConnection(nameOrId)) {
+          console.log(`${C.green}Removed connection:${C.reset} ${nameOrId}`);
+        } else {
+          console.error(`${C.red}Connection not found:${C.reset} ${nameOrId}`);
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db test ──────────────────────────────────────────────────────
+  db.command("test <name>")
+    .description("Test a saved connection")
+    .action(async (nameOrId: string) => {
+      try {
+        const { resolveConnection } = await import("../../services/db.service.ts");
+        const conn = resolveConnection(nameOrId);
+        if (!conn) {
+          console.error(`${C.red}Connection not found:${C.reset} ${nameOrId}`);
+          process.exit(1);
+        }
+        const cfg = parseConfig(conn);
+
+        if (conn.type === "postgres") {
+          const { postgresService } = await import("../../services/postgres.service.ts");
+          const result = await postgresService.testConnection(cfg.connectionString!);
+          if (result.ok) {
+            console.log(`${C.green}✓${C.reset} Connection successful: ${conn.name}`);
+          } else {
+            console.error(`${C.red}✗${C.reset} Connection failed: ${result.error}`);
+            process.exit(1);
+          }
+        } else {
+          const { existsSync } = await import("node:fs");
+          if (existsSync(cfg.path!)) {
+            // Try opening the file
+            const { sqliteService } = await import("../../services/sqlite.service.ts");
+            sqliteService.getTables(cfg.path!, cfg.path!);
+            console.log(`${C.green}✓${C.reset} SQLite file accessible: ${conn.name}`);
+          } else {
+            console.error(`${C.red}✗${C.reset} File not found: ${cfg.path}`);
+            process.exit(1);
+          }
+        }
+      } catch (err) {
+        console.error(`${C.red}✗${C.reset} Test failed:`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db tables ────────────────────────────────────────────────────
+  db.command("tables <name>")
+    .description("List tables in a database connection")
+    .action(async (nameOrId: string) => {
+      try {
+        const { resolveConnection } = await import("../../services/db.service.ts");
+        const conn = resolveConnection(nameOrId);
+        if (!conn) {
+          console.error(`${C.red}Connection not found:${C.reset} ${nameOrId}`);
+          process.exit(1);
+        }
+        const cfg = parseConfig(conn);
+
+        if (conn.type === "postgres") {
+          const { postgresService } = await import("../../services/postgres.service.ts");
+          const tables = await postgresService.getTables(cfg.connectionString!);
+          if (tables.length === 0) {
+            console.log(`${C.dim}No tables found.${C.reset}`);
+            return;
+          }
+          printTable(
+            ["Schema", "Table", "Rows (est.)"],
+            tables.map((t) => [t.schema, t.name, String(t.rowCount)]),
+          );
+        } else {
+          const { sqliteService } = await import("../../services/sqlite.service.ts");
+          const tables = sqliteService.getTables(cfg.path!, cfg.path!);
+          if (tables.length === 0) {
+            console.log(`${C.dim}No tables found.${C.reset}`);
+            return;
+          }
+          printTable(
+            ["Table", "Rows"],
+            tables.map((t) => [t.name, String(t.rowCount)]),
+          );
+        }
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db schema ────────────────────────────────────────────────────
+  db.command("schema <name> <table>")
+    .description("Show table schema (columns, types, constraints)")
+    .option("-s, --schema <schema>", "PostgreSQL schema name", "public")
+    .action(async (nameOrId: string, table: string, options: { schema: string }) => {
+      try {
+        const { resolveConnection } = await import("../../services/db.service.ts");
+        const conn = resolveConnection(nameOrId);
+        if (!conn) {
+          console.error(`${C.red}Connection not found:${C.reset} ${nameOrId}`);
+          process.exit(1);
+        }
+        const cfg = parseConfig(conn);
+
+        if (conn.type === "postgres") {
+          const { postgresService } = await import("../../services/postgres.service.ts");
+          const cols = await postgresService.getTableSchema(cfg.connectionString!, table, options.schema);
+          printTable(
+            ["Column", "Type", "Nullable", "PK", "Default"],
+            cols.map((c) => [c.name, c.type, c.nullable ? "YES" : "NO", c.pk ? "PK" : "", c.defaultValue ?? ""]),
+          );
+        } else {
+          const { sqliteService } = await import("../../services/sqlite.service.ts");
+          const cols = sqliteService.getTableSchema(cfg.path!, cfg.path!, table);
+          printTable(
+            ["Column", "Type", "Not Null", "PK", "Default"],
+            cols.map((c) => [c.name, c.type, c.notnull ? "YES" : "NO", c.pk ? "PK" : "", c.dflt_value ?? ""]),
+          );
+        }
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db data ──────────────────────────────────────────────────────
+  db.command("data <name> <table>")
+    .description("View table data (paginated)")
+    .option("-p, --page <page>", "Page number", "1")
+    .option("-l, --limit <limit>", "Rows per page", "50")
+    .option("--order <column>", "Order by column")
+    .option("--desc", "Descending order")
+    .option("-s, --schema <schema>", "PostgreSQL schema name", "public")
+    .action(async (nameOrId: string, table: string, options) => {
+      try {
+        const { resolveConnection } = await import("../../services/db.service.ts");
+        const conn = resolveConnection(nameOrId);
+        if (!conn) {
+          console.error(`${C.red}Connection not found:${C.reset} ${nameOrId}`);
+          process.exit(1);
+        }
+        const cfg = parseConfig(conn);
+        const page = parseInt(options.page, 10);
+        const limit = parseInt(options.limit, 10);
+        const orderDir = options.desc ? "DESC" as const : "ASC" as const;
+
+        if (conn.type === "postgres") {
+          const { postgresService } = await import("../../services/postgres.service.ts");
+          const result = await postgresService.getTableData(
+            cfg.connectionString!, table, options.schema, page, limit, options.order, orderDir,
+          );
+          console.log(`${C.cyan}${table}${C.reset} — page ${result.page}, ${result.total} total rows\n`);
+          formatRows(result.columns, result.rows, limit);
+        } else {
+          const { sqliteService } = await import("../../services/sqlite.service.ts");
+          const result = sqliteService.getTableData(
+            cfg.path!, cfg.path!, table, page, limit, options.order, orderDir,
+          );
+          console.log(`${C.cyan}${table}${C.reset} — page ${result.page}, ${result.total} total rows\n`);
+          formatRows(result.columns, result.rows, limit);
+        }
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+
+  // ── ppm db query ─────────────────────────────────────────────────────
+  db.command("query <name> <sql>")
+    .description("Execute a SQL query against a saved connection")
+    .action(async (nameOrId: string, sql: string) => {
+      try {
+        const { resolveConnection } = await import("../../services/db.service.ts");
+        const conn = resolveConnection(nameOrId);
+        if (!conn) {
+          console.error(`${C.red}Connection not found:${C.reset} ${nameOrId}`);
+          process.exit(1);
+        }
+        const cfg = parseConfig(conn);
+
+        // Enforce readonly — CLI cannot disable this, only the web UI can toggle it
+        if (conn.readonly && !isReadOnlyQuery(sql)) {
+          console.error(`${C.red}Error:${C.reset} Connection "${conn.name}" is readonly — only SELECT queries allowed.`);
+          console.error(`  To allow writes, toggle the readonly switch in the PPM web UI.`);
+          process.exit(1);
+        }
+
+        if (conn.type === "postgres") {
+          const { postgresService } = await import("../../services/postgres.service.ts");
+          const result = await postgresService.executeQuery(cfg.connectionString!, sql);
+          if (result.changeType === "select") {
+            formatRows(result.columns, result.rows);
+          } else {
+            console.log(`${C.green}OK${C.reset} — ${result.rowsAffected} row(s) affected`);
+          }
+        } else {
+          const { sqliteService } = await import("../../services/sqlite.service.ts");
+          const result = sqliteService.executeQuery(cfg.path!, cfg.path!, sql);
+          if (result.changeType === "select") {
+            formatRows(result.columns, result.rows);
+          } else {
+            console.log(`${C.green}OK${C.reset} — ${result.rowsAffected} row(s) affected`);
+          }
+        }
+      } catch (err) {
+        console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
+        process.exit(1);
+      }
+    });
+}

package/src/server/index.ts

@@ -10,6 +10,8 @@ import { tunnelRoutes } from "./routes/tunnel.ts";
 import { staticRoutes } from "./routes/static.ts";
 import { projectScopedRouter } from "./routes/project-scoped.ts";
 import { postgresRoutes } from "./routes/postgres.ts";
+import { databaseRoutes } from "./routes/database.ts";
+import { initAdapters } from "../services/database/init-adapters.ts";
 import { terminalWebSocket } from "./ws/terminal.ts";
 import { chatWebSocket } from "./ws/chat.ts";
 import { ok, err } from "../types/api.ts";
@@ -57,6 +59,9 @@ async function setupLogFile() {
   });
 }
 
+// Register database adapters at module load time
+initAdapters();
+
 export const app = new Hono();
 
 // CORS for dev
@@ -185,6 +190,7 @@ app.route("/api/push", pushRoutes);
 app.route("/api/projects", projectRoutes);
 app.route("/api/project/:projectName", projectScopedRouter);
 app.route("/api/postgres", postgresRoutes);
+app.route("/api/db", databaseRoutes);
 
 // Static files / SPA fallback (non-API routes)
 app.route("/", staticRoutes);