@hienlh/ppm 0.6.3 → 0.6.4

package/docs/codebase-summary.md

@@ -9,7 +9,7 @@ ppm/
 ├── src/
 │   ├── index.ts                     # CLI entry point (Commander.js program)
 │   ├── cli/
-│   │   ├── commands/                # CLI command implementations (13 files, 1541 LOC)
+│   │   ├── commands/                # CLI command implementations (14 files, 1700 LOC)
 │   │   │   ├── start.ts             # Start server (background by default, --foreground/-f, --share/-s for tunnel)
 │   │   │   ├── stop.ts              # Stop daemon (reads status.json or ppm.pid, graceful shutdown)
 │   │   │   ├── restart.ts           # Restart daemon (keeps tunnel alive)
@@ -21,7 +21,8 @@ ppm/
 │   │   │   ├── projects.ts          # Add/remove/list/scan projects
 │   │   │   ├── config-cmd.ts        # View/set config values
 │   │   │   ├── git-cmd.ts           # Git operations (status, diff, log, commit)
-│   │   │   └── chat-cmd.ts          # Chat CLI (send messages, manage sessions)
+│   │   │   ├── chat-cmd.ts          # Chat CLI (send messages, manage sessions)
+│   │   │   └── db-cmd.ts            # Database CLI (list, query, manage connections)
 │   │   └── utils/
 │   │       └── project-resolver.ts  # Resolve project name -> path
 │   ├── server/
@@ -35,6 +36,7 @@ ppm/
 │   │   │   ├── chat.ts              # GET/POST/DELETE sessions, GET messages, usage, slash-items
 │   │   │   ├── git.ts               # GET status, diff, log, graph; POST commit, stage, discard
 │   │   │   ├── files.ts             # GET tree, read, diff; PUT write; POST mkdir, delete
+│   │   │   ├── database.ts          # GET/POST/PUT/DELETE /api/db/connections (CRUD), query execution
 │   │   │   └── static.ts            # Serve dist/web/index.html (frontend)
 │   │   ├── helpers/
 │   │   │   └── resolve-project.ts   # Helper to resolve project from request params
@@ -46,10 +48,10 @@ ppm/
 │   │   ├── claude-agent-sdk.ts      # Primary: SDK integration, tool approval, Windows CLI fallback, .env poisoning mitigation
 │   │   ├── mock-provider.ts         # Test provider (ignores config)
 │   │   └── registry.ts              # ProviderRegistry (singleton, router to active provider)
-│   ├── services/                    # Business logic (14 files, 2502 LOC)
+│   ├── services/                    # Business logic (18 files, 3100 LOC)
 │   │   ├── chat.service.ts          # Session lifecycle, message streaming
 │   │   ├── config.service.ts        # Config loading (YAML→SQLite migration)
-│   │   ├── db.service.ts            # SQLite persistence (schema v1, WAL mode, 6 tables)
+│   │   ├── db.service.ts            # SQLite persistence (schema v3, WAL mode, 8 tables, connection CRUD)
 │   │   ├── project.service.ts       # Project CRUD, scanning, resolution
 │   │   ├── file.service.ts          # File ops with path validation
 │   │   ├── git.service.ts           # Git operations (status, diff, log, graph)
@@ -60,11 +62,19 @@ ppm/
 │   │   ├── slash-items.service.ts   # /slash command detection & completion
 │   │   ├── git-dirs.service.ts      # Cached git directory discovery
 │   │   ├── cloudflared.service.ts   # Download cloudflared binary (platform-specific)
-│   │   └── tunnel.service.ts        # Cloudflare Quick Tunnel lifecycle
-│   ├── types/                       # TypeScript interfaces (6 files, 357 LOC)
+│   │   ├── tunnel.service.ts        # Cloudflare Quick Tunnel lifecycle
+│   │   ├── table-cache.service.ts   # Table metadata cache & search for DB connections
+│   │   └── database/                # Database adapters & registry
+│   │       ├── adapter-registry.ts  # DatabaseAdapter registry (extensible)
+│   │       ├── sqlite-adapter.ts    # SQLite connection, query execution
+│   │       ├── postgres-adapter.ts  # PostgreSQL connection, query execution
+│   │       ├── init-adapters.ts     # Initialize adapters at server start
+│   │       └── readonly-check.ts    # isReadOnlyQuery() safety regex (CTE-safe)
+│   ├── types/                       # TypeScript interfaces (7 files, 450 LOC)
 │   │   ├── api.ts                   # ApiResponse envelope, WebSocket message types
 │   │   ├── chat.ts                  # Session, Message, ChatEvent types
 │   │   ├── config.ts                # Config schema
+│   │   ├── database.ts              # DatabaseAdapter, DbConnectionConfig, DbTableInfo, etc.
 │   │   ├── git.ts                   # GitStatus, GitDiff, GitCommit types
 │   │   ├── project.ts               # Project interface
 │   │   └── terminal.ts              # Terminal types
@@ -88,7 +98,7 @@ ppm/
 │       │   ├── use-health-check.ts  # Detect server crashes/restarts via health endpoint
 │       │   ├── use-usage.ts         # Fetch token usage from backend
 │       │   └── use-push-notification.ts # Web push notifications via Service Worker
-│       ├── lib/                     # Utilities (10 files)
+│       ├── lib/                     # Utilities (11 files)
 │       │   ├── api-client.ts        # Fetch wrapper with auth token, envelope unwrapping
 │       │   ├── api-settings.ts      # AI settings API client (GET/PUT /api/settings/ai)
 │       │   ├── ws-client.ts         # WebSocket with exponential backoff + Cloudflare handshake
@@ -96,6 +106,7 @@ ppm/
 │       │   ├── project-avatar.ts    # Smart project initials (collision resolution)
 │       │   ├── project-palette.ts   # 12-color palette for project avatars
 │       │   ├── use-monaco-theme.ts  # Sync Monaco Editor theme with app theme
+│       │   ├── color-utils.ts       # WCAG color contrast helper
 │       │   └── utils.ts             # Helpers (cn, randomId, basename, etc.)
 │       ├── styles/
 │       │   └── globals.css          # Tailwind directives, custom CSS
@@ -130,21 +141,33 @@ ppm/
 │           │   ├── editor-panel.tsx  # Wrapper for tab content within a panel
 │           │   ├── project-bar.tsx   # 52px sidebar with project avatars, share popover
 │           │   ├── project-bottom-sheet.tsx # Mobile project switcher
-│           │   ├── sidebar.tsx       # Left sidebar (Explorer/Git/Settings tabs)
-│           │   ├── tab-bar.tsx       # Tab bar with icons
-│           │   ├── draggable-tab.tsx  # Draggable tab with context menu, rename
+│           │   ├── sidebar.tsx       # Left sidebar (Explorer/Git/Database/Settings tabs)
+│           │   ├── tab-bar.tsx       # Tab bar with icons, connection color display
+│           │   ├── draggable-tab.tsx  # Draggable tab with context menu, rename, connection color
 │           │   ├── tab-content.tsx    # Router for tab content
 │           │   ├── split-drop-overlay.tsx # Drop zone for tab splitting
-│           │   ├── command-palette.tsx # Global command palette (Shift+Shift)
+│           │   ├── command-palette.tsx # Global command palette (Shift+Shift, DB table search)
 │           │   ├── add-project-form.tsx # Modal form to add projects
 │           │   ├── mobile-nav.tsx    # Bottom navigation for mobile
 │           │   └── mobile-drawer.tsx # Mobile overlay drawer
+│           ├── database/            # Database management (5 files, 300+ LOC)
+│           │   ├── database-sidebar.tsx # Sidebar tab container (connection list, form)
+│           │   ├── connection-list.tsx # Connections list with actions, color badges
+│           │   ├── connection-form-dialog.tsx # Create/edit connection form (SQLite/Postgres)
+│           │   ├── connection-color-picker.tsx # WCAG contrast-aware color picker
+│           │   └── use-connections.ts # Hook for connection CRUD operations
 │           ├── projects/            # Project management (339 LOC, 2 files)
 │           ├── settings/            # Settings panel (theme + AI provider config UI)
 │           ├── terminal/            # xterm.js wrapper (143 LOC, 2 files)
 │           ├── shared/              # Shared components (2 files)
 │           │   ├── markdown-renderer.tsx # Render Markdown with syntax highlighting
 │           │   └── bug-report-popup.tsx  # Global bug report popup
+│           ├── sqlite/              # SQLite viewer (unified connectionId API mode)
+│           │   ├── sqlite-viewer.tsx # Display table data, execute queries
+│           │   └── use-sqlite.ts    # Hook for SQLite operations via /api/db routes
+│           ├── postgres/            # PostgreSQL viewer (unified connectionId API mode)
+│           │   ├── postgres-viewer.tsx # Display table data, execute queries
+│           │   └── use-postgres.ts  # Hook for Postgres operations via /api/db routes
 │           └── ui/                  # Radix + shadcn primitives (14 files)
 │               └── button, input, label, dialog, dropdown-menu, select, tabs, tooltip, etc.
 ├── tests/
@@ -201,11 +224,11 @@ ppm/
 - **Pattern:** Project-scoped routing via ProviderRegistry
 
 ### Service Layer (src/services/)
-- **Responsibility:** Business logic, data operations, infrastructure (tunneling)
+- **Responsibility:** Business logic, data operations, infrastructure (tunneling, database connections)
 - **Services:**
   - **ChatService** — Session lifecycle, message queueing, streaming
   - **ConfigService** — Config loading (YAML→SQLite migration)
-  - **DbService** — SQLite persistence (6 tables, WAL mode, schema migrations)
+  - **DbService** — SQLite persistence (8 tables, WAL mode, schema v3, connection CRUD, table cache)
   - **GitService** — Git commands via simple-git
   - **FileService** — File ops with path validation
   - **ProjectService** — Project CRUD, scanning, resolution
@@ -215,7 +238,11 @@ ppm/
   - **SessionLogService** — Audit logs with sensitive data redaction
   - **CloudflaredService** — Download/cache cloudflared binary (platform-aware)
   - **TunnelService** — Spawn tunnel, extract URL, cleanup on exit
-- **Pattern:** Singleton services, dependency injection via imports
+  - **TableCacheService** — Cache table metadata across connections, search tables by name
+  - **DatabaseAdapterRegistry** — Register/retrieve DatabaseAdapter implementations (extensible pattern)
+  - **SQLiteAdapter** — SQLite connection/query execution with readonly checks
+  - **PostgresAdapter** — PostgreSQL connection/query execution with readonly checks
+- **Pattern:** Singleton services, dependency injection via imports, adapter registry for extensibility
 
 ### Provider Layer (src/providers/)
 - **Responsibility:** AI model abstraction, config-driven initialization

package/docs/project-roadmap.md

@@ -142,7 +142,31 @@ Multi-project, project-scoped API refactor with improved UX, Monaco Editor, auto
 
 ---
 
-### Phase 9: PWA & Build ✅ Complete
+### Phase 9: Database Management ✅ Complete (260319)
+
+**Features:**
+- Unified database viewer for SQLite & PostgreSQL
+- DatabaseAdapter extensible pattern
+- Connection CRUD (create, edit, delete, color-code)
+- Query execution with readonly safety
+- Table browser with pagination & schema inspection
+- CLI support (ppm db commands)
+- Credentials stored securely in SQLite (never exposed in API)
+- readonly=true by default (safe-by-default)
+
+**Latest Work (260319):**
+- SQLiteAdapter & PostgresAdapter implementations
+- /api/db routes with connection sanitization
+- Database sidebar UI with connection form, color picker
+- TableCacheService for metadata caching & search
+- isReadOnlyQuery() CTE-safe safety checks
+- CLI db-cmd for database management
+
+**Status:** Complete, fully integrated with v0.6.3
+
+---
+
+### Phase 10: PWA & Build ✅ Complete
 - Vite build configuration
 - Service worker (vite-plugin-pwa)
 - Offline support (cached assets)
@@ -153,7 +177,7 @@ Multi-project, project-scoped API refactor with improved UX, Monaco Editor, auto
 
 ---
 
-### Phase 10: Testing ✅ In Progress (65%)
+### Phase 11: Testing ✅ In Progress (65%)
 
 #### Unit Tests (50% complete)
 - [x] Mock provider tests
@@ -229,17 +253,18 @@ Multi-project, project-scoped API refactor with improved UX, Monaco Editor, auto
 - [x] URL sync for bookmarking/sharing
 - [x] Project Switcher Bar (52px sidebar, avatars, colors, reordering) (260317)
 - [x] Keep-alive workspace switching (preserve xterm DOM) (260317)
-- [x] Sidebar tab system (Explorer/Git/History) (260317)
+- [x] Sidebar tab system (Explorer/Git/History/Database tabs) (260317, 260319)
 - [x] Monaco Editor migration (CodeMirror → Monaco, fully removed) (260317-260319)
 - [x] Project color customization (12-color palette + custom hex) (260317)
 - [x] Auto-generate chat session titles from SDK summary (260319)
 - [x] Inline session rename UI (260319)
-- [x] SQLite migration (db.service.ts, backward YAML compat) (in progress)
+- [x] Database Management (SQLite/PostgreSQL, adapters, UI, CLI) (260319)
+- [x] SQLite migration (db.service.ts, backward YAML compat, connection tables v3) (260319)
 - [ ] Complete test coverage (65% complete)
 - [x] Documentation updates (260319)
 - [ ] Security audit (planned)
 
-**Release Status:** v0.5.21 released, v2.0 essentially complete
+**Release Status:** v0.6.3 released, v2.0 + database management complete
 
 ---
 
@@ -366,7 +391,7 @@ Multi-project, project-scoped API refactor with improved UX, Monaco Editor, auto
 | Version | Status | Features | Target Date |
 |---------|--------|----------|-------------|
 | **v1.0** | Released | Single project, basic chat, terminal | Feb 28, 2025 |
-| **v2.0** | Complete (v0.5.21) | Multi-project, project-scoped API, improved UX, Monaco Editor, auto-title | Mar 19, 2026 |
+| **v2.0** | Complete (v0.6.3) | Multi-project, project-scoped API, improved UX, Monaco Editor, auto-title, database management | Mar 19, 2026 |
 | **v2.1** | Planned | Complete test coverage, SQLite finalization, bug fixes | Apr 15, 2026 |
 | **v3.0** | Planned | Collaborative editing, custom tools, plugins | Jun 30, 2026 |
 | **v4.0** | Planned | Cloud sync, advanced git, profiling UI | Sep 30, 2026 |

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.3",
+  "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

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { isReadOnlyQuery } from "../../services/database/readonly-check.ts";
 
 const C = {
   reset: "\x1b[0m",
@@ -53,6 +54,12 @@ function parseConfig(row: { type: string; connection_config: string }): { type:
   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");
 
@@ -69,11 +76,14 @@ export function registerDbCommands(program: Command): void {
         }
         const rows = conns.map((c) => {
           const cfg = parseConfig(c);
-          const target = cfg.connectionString ?? cfg.path ?? "-";
-          const display = target.length > 60 ? target.slice(0, 57) + "..." : target;
-          return [String(c.id), c.name, c.type, c.group_name ?? "-", display];
+          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", "Connection"], rows);
+        printTable(["ID", "Name", "Type", "Group", "RO", "Connection"], rows);
       } catch (err) {
         console.error(`${C.red}Error:${C.reset}`, (err as Error).message);
         process.exit(1);
@@ -313,6 +323,13 @@ export function registerDbCommands(program: Command): void {
         }
         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);

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);