sqlew 3.6.10 → 3.7.1

package/CHANGELOG.md

@@ -7,6 +7,194 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.7.1] - 2025-11-05
+
+### Fixed - Error Message Visibility
+
+**Fixed validation error messages being hidden by error wrapper**
+
+#### Problem
+- Validation errors (JSON-structured responses) were being wrapped with stack traces
+- Wrong-usage messages were hidden from MCP clients
+- Users received generic error messages instead of helpful validation details
+
+#### Solution
+- **Error Handler Enhancement** - Detect and unwrap JSON validation errors
+  - Validation errors now returned directly to MCP client without wrapping
+  - Stack traces written to logs only (not returned to client)
+  - Token-efficient responses without exposing internal stack details
+- **Parameter Validator Enhancement** - Detect unexpected/invalid parameters
+  - Added validation for parameters that don't match valid list and have no typo suggestion
+  - Improved error messages: "Unexpected params: X. Valid params: Y, Z"
+
+#### Impact
+- ✅ **Better UX** - Validation errors are now visible and actionable
+- ✅ **Token efficiency** - No stack traces in MCP responses
+- ✅ **Clearer feedback** - Users see helpful error messages immediately
+- ✅ **Security** - Internal stack details not exposed to clients
+
+---
+
+## [3.7.0] - 2025-11-05
+
+### Added - Runtime Database Reconnection
+
+**Automatic connection recovery with exponential backoff retry logic**
+
+#### Features
+- **ConnectionManager** - Singleton wrapper for all database operations
+- **Exponential Backoff** - Retry delays: 1s → 2s → 4s → 8s → 16s (31 seconds total)
+- **Smart Error Detection** - Recognizes connection errors across SQLite, MySQL, PostgreSQL
+- **Process.exit on Exhaustion** - Exits cleanly after 5 failed retries
+- **27 Operations Wrapped** - All transactional operations protected:
+  - context.ts: 5 operations
+  - tasks.ts: 9 operations
+  - files.ts: 3 operations
+  - constraints.ts: 3 operations
+  - config.ts: 2 operations
+  - utils.ts: 5 operations
+
+#### Connection Error Patterns Detected
+- **Network Errors**: ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET, EPIPE
+- **SQLite**: "database is locked", "unable to open database"
+- **MySQL/MariaDB**: "server has gone away", "lost connection to mysql server"
+- **PostgreSQL**: "connection to server was lost", "could not connect to server"
+- **Knex-specific**: "timeout acquiring a connection", "pool is destroyed"
+
+#### Test Coverage
+- **41 tests passing** (22 unit + 19 integration)
+- Retry behavior verification
+- Production scenario simulation (server restart, network failures)
+- Tool integration testing
+
+#### Impact
+- ✅ **Resilient operations** - Automatic recovery from transient connection failures
+- ✅ **Production ready** - Handles server restarts, network issues
+- ✅ **Zero regressions** - All existing tests pass
+- ✅ **Token efficient** - No manual retry logic needed in agent code
+
+---
+
+### Changed - Validation Error Messages
+
+**70-85% token reduction in error message size**
+
+#### Token Efficiency
+- **Before**: ~1000+ characters (~300+ tokens) with full examples embedded
+- **After**: ~200 characters (~50 tokens) with reference IDs
+- **Reduction**: 70-85% token savings
+
+#### New Error Format
+```json
+{
+  "error": "Missing: key, value",
+  "action": "set",
+  "reference": "decision.set",
+  "missing": ["key", "value"],
+  "hint": "Use 'quick_set' for simpler usage..."
+}
+```
+
+#### Features
+- **Reference IDs** - Compact `{tool}.{action}` format (e.g., "decision.set")
+- **Concise Messages** - Essential information only
+- **Conditional Fields** - Only include fields when present
+- **Self-Documenting** - AI can query `action: "help"` for full docs if needed
+
+#### Error Types
+- Missing params: `"Missing: key, value"`
+- Typos: `"Invalid params: val → value"`
+- Unknown action: `"Unknown action 'sett'. Did you mean: set?"`
+
+#### Impact
+- ✅ **Token efficiency** - 70-85% reduction in error size
+- ✅ **Cost reduction** - Lower API costs for AI agents
+- ✅ **Better UX** - Quick, scannable errors
+- ✅ **Backward compatible** - Error structure unchanged
+
+---
+
+### Changed - Debug Log Format
+
+**Single-line log entries for easier parsing**
+
+#### Problem
+Multi-line log messages broke standard text processing tools (grep, awk, log rotation).
+
+#### Solution
+- **Sanitization Function** - Replaces newlines with spaces, collapses whitespace
+- **Applied To**: All log messages, data values, JSON output
+- **Result**: Every log entry is exactly one line
+
+#### Benefits
+- ✅ **Easier parsing** - Line-based tools work correctly
+- ✅ **Better grep** - Search across entire messages
+- ✅ **Simpler analysis** - Standard text processing
+- ✅ **Cleaner output** - No unexpected line breaks
+
+#### Example
+**Before:**
+```
+[2025-11-05T02:00:00.000Z] [ERROR] Error details:
+Stack trace line 1
+Stack trace line 2
+```
+
+**After:**
+```
+[2025-11-05T02:00:00.000Z] [ERROR] Error details: Stack trace line 1 Stack trace line 2
+```
+
+---
+
+### Fixed - Multi-Project Migration (Critical)
+
+**Fixed migration for ALL users upgrading from v3.6.10 to v3.7.0**
+
+#### Problem
+- SQLite's `ALTER TABLE` silently failed for 4 tables with complex foreign keys
+- Migration reported success but columns weren't added
+- Task creation would fail: `"table t_task_details has no column named project_id"`
+
+#### Root Cause
+SQLite cannot modify tables with `ON DELETE CASCADE` constraints using ALTER TABLE.
+
+#### Solution
+- **Table Recreation Strategy** - Backup → Drop → Recreate → Restore
+- **4 Tables Fixed**:
+  - `t_task_details` (STEP 4.7)
+  - `t_task_file_links` (STEP 4.8)
+  - `t_task_decision_links` (STEP 4.9)
+  - `t_task_tags` (composite PRIMARY KEY)
+
+#### Idempotency
+All recreation steps check if `project_id` exists before executing:
+```typescript
+const hasProjectId = await knex.schema.hasColumn('table_name', 'project_id');
+if (!hasProjectId) {
+  // Recreation logic
+}
+```
+
+#### Data Preservation Verified
+- ✅ 223 task detail rows preserved
+- ✅ 632 task tag rows preserved
+- ✅ All task links preserved
+- ✅ 100% data integrity maintained
+
+#### Testing
+- ✅ Fresh installation works
+- ✅ v3.6.10 → v3.7.0 upgrade works
+- ✅ Migration can be re-run safely (idempotent)
+- ✅ TypeScript compiles without errors
+
+#### Impact
+- ✅ **Production ready** - Safe for all v3.6.10 users to upgrade
+- ✅ **No data loss** - All existing data preserved
+- ✅ **Idempotent** - Can re-run without errors
+
+---
+
 ## [3.6.10] - 2025-10-30
 
 ### Added - Environment Variable Support for Project Root
@@ -88,6 +276,164 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+### Added - Environment Variable Support for Project Root
+
+**New `SQLEW_PROJECT_ROOT` environment variable for project-relative databases**
+
+#### Problem
+- Junie AI and other MCP clients require absolute paths in configuration
+- Users had to hardcode project-specific paths in MCP server config
+- No easy way to use project-relative database paths
+
+#### Solution
+- Added `SQLEW_PROJECT_ROOT` environment variable support (inspired by serena-mcp pattern)
+- MCP clients can now pass project directory via environment variable
+- Database automatically created at `$SQLEW_PROJECT_ROOT/.sqlew/sqlew.db`
+
+#### Priority Order
+1. `SQLEW_PROJECT_ROOT` environment variable (NEW - highest priority)
+2. `--db-path` CLI argument (absolute path)
+3. `--config-path` CLI argument (absolute path)
+4. `database.path` in config file (absolute path)
+5. `process.cwd()` fallback
+
+#### Junie AI Configuration Example
+```json
+{
+  "mcpServers": {
+    "sqlew": {
+      "command": "npx",
+      "args": ["sqlew"],
+      "env": {
+        "SQLEW_PROJECT_ROOT": "{projectDir}"
+      }
+    }
+  }
+}
+```
+
+**Note:** Junie AI uses `{projectDir}` variable which expands to the current project's absolute path. This ensures each project gets its own isolated database without hardcoded paths. Other MCP clients may use different variable names like `${workspaceFolder}` (VS Code/Cline) - check your client's documentation.
+
+#### Impact
+- ✅ **Project-relative databases** without hardcoded absolute paths
+- ✅ **Cleaner MCP configuration** (no per-project path updates needed)
+- ✅ **Compatible with Junie AI, Claude Desktop, and other MCP clients**
+- ✅ **No breaking changes** (environment variable is optional)
+
+---
+
+### Fixed - MCP Protocol Compliance (EPIPE Fix)
+
+**Eliminated console output for strict JSON-RPC protocol compliance**
+
+#### Problem
+- EPIPE (broken pipe) errors when running with Junie AI on Windows
+- Console output to stdout/stderr violated MCP JSON-RPC protocol requirements
+- Strict MCP clients (like Junie AI) expect pure JSON-RPC on stdio streams
+
+#### Changes
+- **Redirected all diagnostic output to debug log file** - stdout/stderr reserved exclusively for JSON-RPC
+- Modified `safeConsoleError()` to write to debug log instead of stderr
+- Replaced 50+ console.log/console.error calls across codebase:
+  - `src/database.ts` - Database initialization messages
+  - `src/watcher/file-watcher.ts` - File watcher status and events
+  - `src/watcher/gitignore-parser.ts` - .gitignore loading warnings
+  - `src/tools/tasks.ts` - Task file registration warnings
+  - `src/config/example-generator.ts` - First launch messages
+
+#### Technical Details
+- **MCP Protocol Requirement**: stdin/stdout/stderr must carry only JSON-RPC messages
+- **Debug Logging**: All diagnostic messages now use `debugLog()` with appropriate levels (INFO, WARN, ERROR)
+- **Zero stdout pollution**: Server starts silently, waits for JSON-RPC requests
+- **Tested with Junie AI**: Confirmed no EPIPE errors on Windows
+
+#### Impact
+- ✅ **Works with strict MCP clients** (Junie AI, etc.)
+- ✅ **Maintains full diagnostics** via debug log file
+- ✅ **Pure JSON-RPC protocol** compliance
+- ✅ **No breaking changes** to MCP tool functionality
+
+---
+
+### Added - Environment Variable Support for Project Root
+
+**New `SQLEW_PROJECT_ROOT` environment variable for project-relative databases**
+
+#### Problem
+- Junie AI and other MCP clients require absolute paths in configuration
+- Users had to hardcode project-specific paths in MCP server config
+- No easy way to use project-relative database paths
+
+#### Solution
+- Added `SQLEW_PROJECT_ROOT` environment variable support (inspired by serena-mcp pattern)
+- MCP clients can now pass project directory via environment variable
+- Database automatically created at `$SQLEW_PROJECT_ROOT/.sqlew/sqlew.db`
+
+#### Priority Order
+1. `SQLEW_PROJECT_ROOT` environment variable (NEW - highest priority)
+2. `--db-path` CLI argument (absolute path)
+3. `--config-path` CLI argument (absolute path)
+4. `database.path` in config file (absolute path)
+5. `process.cwd()` fallback
+
+#### Junie AI Configuration Example
+```json
+{
+  "mcpServers": {
+    "sqlew": {
+      "command": "npx",
+      "args": ["sqlew"],
+      "env": {
+        "SQLEW_PROJECT_ROOT": "{projectDir}"
+      }
+    }
+  }
+}
+```
+
+**Note:** Junie AI uses `{projectDir}` variable which expands to the current project's absolute path. This ensures each project gets its own isolated database without hardcoded paths. Other MCP clients may use different variable names like `${workspaceFolder}` (VS Code/Cline) - check your client's documentation.
+
+#### Impact
+- ✅ **Project-relative databases** without hardcoded absolute paths
+- ✅ **Cleaner MCP configuration** (no per-project path updates needed)
+- ✅ **Compatible with Junie AI, Claude Desktop, and other MCP clients**
+- ✅ **No breaking changes** (environment variable is optional)
+
+---
+
+### Fixed - MCP Protocol Compliance (EPIPE Fix)
+
+**Eliminated console output for strict JSON-RPC protocol compliance**
+
+#### Problem
+- EPIPE (broken pipe) errors when running with Junie AI on Windows
+- Console output to stdout/stderr violated MCP JSON-RPC protocol requirements
+- Strict MCP clients (like Junie AI) expect pure JSON-RPC on stdio streams
+
+#### Changes
+- **Redirected all diagnostic output to debug log file** - stdout/stderr reserved exclusively for JSON-RPC
+- Modified `safeConsoleError()` to write to debug log instead of stderr
+- Replaced 50+ console.log/console.error calls across codebase:
+  - `src/database.ts` - Database initialization messages
+  - `src/watcher/file-watcher.ts` - File watcher status and events
+  - `src/watcher/gitignore-parser.ts` - .gitignore loading warnings
+  - `src/tools/tasks.ts` - Task file registration warnings
+  - `src/config/example-generator.ts` - First launch messages
+
+#### Technical Details
+- **MCP Protocol Requirement**: stdin/stdout/stderr must carry only JSON-RPC messages
+- **Debug Logging**: All diagnostic messages now use `debugLog()` with appropriate levels (INFO, WARN, ERROR)
+- **Zero stdout pollution**: Server starts silently, waits for JSON-RPC requests
+- **Tested with Junie AI**: Confirmed no EPIPE errors on Windows
+
+#### Impact
+- ✅ **Works with strict MCP clients** (Junie AI, etc.)
+- ✅ **Maintains full diagnostics** via debug log file
+- ✅ **Pure JSON-RPC protocol** compliance
+- ✅ **No breaking changes** to MCP tool functionality
+
+---
+
 ### Fixed - Windows Absolute Path Handling
 
 **Fixed path normalization for Windows environments**

package/README.md

@@ -10,25 +10,39 @@
 
 **sqlew** is a Model Context Protocol (MCP) server that gives AI agents organizational memory across sessions.
 
-**The Problem:** Without sqlew, every Claude session starts with zero context. You must re-explain decisions, agents can reintroduce bugs, and there's no way to track WHY decisions were made.
+### The Problem
+Without sqlew, every Claude session starts with zero context. You must re-explain decisions, agents can reintroduce bugs, and there's no way to track WHY decisions were made.
 
-**The Solution:** sqlew lets agents remember decisions, query past context, prevent regressions with constraints, and coordinate via messaging and tasks.
+It has been possible to keep records using Markdown files. However, large-scale projects or long-term maintenance records tend to generate massive amounts of documentation. This has become a problem, as it causes context rot in AI systems, leading to declining performance.
 
-**Example:** Session 1 records "API v1 deprecated". Session 2 (days later) queries and automatically uses v2.
+### The Solution
+sqlew builds efficient external memory for AI by using relational databases.
+- Records the reasoning behind decisions
+- Enables querying past context
+- Prevents anti-patterns through constraints
+- Eliminates duplicate work via task management
+
+**Example:**
+- Session 1 records "API v1 deprecated".
+- Session 2 (days later) queries and automatically uses v2.
+
+> *This software does not send any data to external networks. We NEVER collect any data or usage statistics. Please use it with complete security.*
 
 ## Why Use sqlew?
 
 ### 🧠 Organizational Memory
-Traditional code tells you **WHAT** and **HOW**. sqlew adds **WHY**:
+Traditional code analysis like git tells you **WHAT** is done, sqlew adds **WHY** and **HOW** on it:
 - **Decisions** → WHY it was changed
-- **Constraints** → WHY it must work this way
+- **Constraints** → HOW should it be written
+- **Tasks** → WHAT needs to be done
 
 ### ⚡ Token Efficiency
 **60-75% token reduction** in multi-session projects through structured data storage and selective querying.
 
 ### 🎯 Key Features
-- **5 Specialized Tools**: decisions, tasks, files, constraints, stats (config tool removed in dev)
-- **Parameter Validation**: Typo detection, required/optional markers, helpful error messages (NEW in dev)
+- **5 Specialized Tools**: decisions, tasks, files, constraints, stats
+- **Runtime Reconnection**: Automatic database connection recovery with exponential backoff
+- **Parameter Validation**: Typo detection, required/optional markers, 70-85% more concise error messages
 - **Metadata-Driven**: Tag, layer, scope, and version everything
 - **Decision Context**: Document WHY with rationale, alternatives, and trade-offs
 - **Task Dependencies**: Blocking relationships with circular detection
@@ -41,7 +55,7 @@ Traditional code tells you **WHAT** and **HOW**. sqlew adds **WHY**:
 See [docs/TASK_OVERVIEW.md](docs/TASK_OVERVIEW.md) and [docs/DECISION_CONTEXT.md](docs/DECISION_CONTEXT.md) for details.
 
 ### 🔖Kanban-style AI Scrum
-![kanban-style task management](assets/kanban-style.png)
+![kanban-style task management](assets/kanban-visualizer.png)
 
 ## Installation
 
@@ -51,21 +65,7 @@ See [docs/TASK_OVERVIEW.md](docs/TASK_OVERVIEW.md) and [docs/DECISION_CONTEXT.md
 
 ### Quick Install
 
-**Recommended (npx):**
-```bash
-npx sqlew
-```
-
-**Or install per project:**
-```bash
-npm install sqlew
-```
-
-**Note**: Global install (`npm install -g`) is **not recommended** because sqlew requires an independent database per project. Each project should maintain its own context database in `.sqlew/sqlew.db`.
-
-### Add to Claude Desktop
-
-Edit `claude_desktop_config.json`:
+on `.mcp.json` in your project's root, add these lines:
 
 ```json
 {
@@ -77,8 +77,13 @@ Edit `claude_desktop_config.json`:
   }
 }
 ```
+**Recommend to restart claude after initialize**
+
+The first time, sqlew install custom agents and initialize database. Custom agents are not loaded in this time. Please exit claude once, and restart claude again.
+
+It's Ready!
 
-Restart Claude Desktop. Done!
+**⚠️Note**: Global install (`npm install -g`) is **not recommended** because sqlew requires an independent settings per project. Each project should maintain its own context database in `.sqlew/sqlew.db`.
 
 **Custom database path:** Add path as argument: `"args": ["sqlew", "/path/to/db.db"]`
 **Default location:** `.sqlew/sqlew.db`
@@ -91,7 +96,7 @@ Restart Claude Desktop. Done!
 
 ### Optional Config File
 
-Create `.sqlew/config.toml` for persistent settings:
+On first run, `.sqlew/config.toml` will be created for persistent settings:
 
 ```toml
 [database]
@@ -102,25 +107,31 @@ ignore_weekend = true
 message_hours = 48
 ```
 
-**Priority:** CLI args > config.toml > database defaults
+Also `.sqlew/config.example.toml` is created for reference.
+
+**Settings Priority:** CLI args > config.toml > database defaults
 
 See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options and validation rules.
 
 ## Quick Start
 
+install it, launch claude, exit claude and launch Claude again.
+
 ### Basic Usage
 
-All tools require an `action` parameter. Example:
+You'll never need to call it manually, I recommend to call this tool via prompt.
+
+```
+read sqlew usecases, and plan implementation of feature X using sqlew.
+```
 
-```javascript
-// Store a decision
-{action: "set", key: "auth_method", value: "JWT", layer: "business", tags: ["security"]}
+or invoke Specialized Agent
 
-// Query later
-{action: "get", key: "auth_method"}
+```
+plan implementation of feature X with @agent-scrum-master.
 ```
 
-For detailed examples, see [docs/TOOL_REFERENCE.md](docs/TOOL_REFERENCE.md).
+Specialized Agents use sqlew more efficiently.
 
 ## Specialized Agents
 
@@ -132,7 +143,7 @@ sqlew provides three specialized agents for efficient multi-agent coordination i
 | **Researcher** | Query decisions, analyze patterns, investigate context | 14KB/conversation | Understanding past decisions, onboarding new members, sprint retrospectives |
 | **Architect** | Document decisions, enforce constraints, maintain standards | 20KB/conversation | Making architectural choices, establishing rules, validating compliance |
 
-### Installation
+### Detailed Installation
 
 **By default, all three specialized agents are automatically installed** to your project's `.claude/agents/` directory on first run.
 
@@ -160,22 +171,25 @@ Savings: Scrum + Architect = 32KB (30%) | Scrum only = 12KB (74%)
 
 | Tool | Purpose | Example Use |
 |------|---------|------------|
-| **decision** | Record choices | "We chose PostgreSQL" |
+| **decision** | Record choices and reasons | "We chose PostgreSQL" |
+| **constraint** | Define rules | "DO NOT use raw SQL, use ORM" |
 | **task** | Track work | "Implement feature X" |
 | **file** | Track changes | "Modified auth.ts" |
-| **constraint** | Define rules | "API must be <100ms" |
 | **stats** | Database metrics | Get layer summary |
-| **config** | Retention settings | Auto-cleanup config |
 
-Each tool supports `action: "help"` for full documentation and `action: "example"` for comprehensive usage examples.
 
 ## Documentation
 
+Each tool supports `action: "help"` for full documentation and `action: "example"` for comprehensive usage examples.
+
+And `action: "use_case"` shows how to use the tool in a real-world scenario.
+
 ### On-Demand Documentation
 
 All tools support:
 - `action: "help"` - Parameter reference and descriptions
 - `action: "example"` - Usage scenarios and examples
+- `action: "use_case"` - Real-world usage examples
 
 ### For AI Agents
 
@@ -205,6 +219,7 @@ All tools support:
 ### For Developers
 
 - [Configuration Guide](docs/CONFIGURATION.md) - TOML config file setup
+- [Database Migration](docs/DATABASE_MIGRATION.md) - SQLite → MySQL/PostgreSQL migration
 - [Building from Source](docs/ARCHITECTURE.md#development) - Setup instructions
 - [Migration Guides](docs/MIGRATION_v2.md) - Version upgrade guides
 
@@ -230,7 +245,7 @@ Support development via [GitHub Sponsors](https://github.com/sponsors/sin5ddd) -
 
 ## Version
 
-Current version: **3.6.6**
+Current version: **3.7.0**
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License

package/assets/config.example.toml

@@ -8,11 +8,51 @@
 # Database Settings
 # ============================================================================
 [database]
+# SQLite Configuration (default, local development)
 # Database file path (relative to project root or absolute)
 # Default: ".sqlew/sqlew.db"
 # path = ".sqlew/custom.db"
 # path = "/absolute/path/to/database.db"
 
+# PostgreSQL/MySQL/MariaDB Configuration (multi-agent production)
+# Uncomment and configure for remote database access
+# type = "postgres"  # or "mysql" (also works with MariaDB 10.5+)
+
+# Connection settings (required for postgres/mysql/mariadb)
+# IMPORTANT: Database must already exist! User does NOT need CREATE DATABASE privilege.
+# [database.connection]
+# host = "localhost"
+# port = 5432  # PostgreSQL: 5432, MySQL/MariaDB: 3306
+# database = "sqlew"  # Must be created beforehand!
+
+# Authentication settings (required for postgres/mysql/mariadb)
+# Required user privileges: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
+# [database.auth]
+# type = "direct"  # Options: "direct", "ssh", "aws-iam", "gcp-iam"
+# user = "postgres"  # or mysql_user, etc.
+# password = "your-password"
+
+# SSL/TLS Configuration (optional, for encrypted connections)
+# [database.auth.ssl]
+# ca = "/path/to/ca-cert.pem"  # or inline certificate content
+# cert = "/path/to/client-cert.pem"  # for mutual TLS
+# key = "/path/to/client-key.pem"  # for mutual TLS
+# rejectUnauthorized = true  # set to false for self-signed certs (not recommended for production)
+
+# SSH Tunnel Configuration (when type = "ssh")
+# Used for bastion host / jump server access
+# [database.auth.ssh]
+# host = "bastion.example.com"
+# port = 22
+# username = "deploy"
+# privateKeyPath = "/home/user/.ssh/id_rsa"  # or use password
+# password = "ssh-password"  # alternative to privateKeyPath
+# passphrase = "key-passphrase"  # if private key is encrypted
+# timeout = 30000  # SSH connection timeout in ms
+# keepalive = true
+# keepaliveInterval = 10000
+# localPort = 50000  # auto-allocated from 50000-60000 if not specified
+
 # ============================================================================
 # Auto-Deletion Settings
 # ============================================================================
@@ -154,6 +194,59 @@ architect = true
 # Example Configurations
 # ============================================================================
 
+# Example 1: PostgreSQL with Direct Authentication + SSL
+# [database]
+# type = "postgres"
+# [database.connection]
+# host = "db.example.com"
+# port = 5432
+# database = "sqlew_production"
+# [database.auth]
+# type = "direct"
+# user = "postgres"
+# password = "secure-password"
+# [database.auth.ssl]
+# ca = "/path/to/ca-cert.pem"
+# rejectUnauthorized = true
+
+# Example 2: PostgreSQL through SSH Tunnel
+# [database]
+# type = "postgres"
+# [database.connection]
+# host = "db.internal.example.com"
+# port = 5432
+# database = "sqlew_production"
+# [database.auth]
+# type = "ssh"
+# user = "postgres"
+# password = "db-password"
+# [database.auth.ssh]
+# host = "bastion.example.com"
+# username = "deploy"
+# privateKeyPath = "/home/user/.ssh/id_rsa"
+
+# Example 3: MySQL with SSL and SSH
+# [database]
+# type = "mysql"
+# [database.connection]
+# host = "mysql.internal.example.com"
+# port = 3306
+# database = "sqlew_db"
+# [database.auth]
+# type = "ssh"
+# user = "mysql_user"
+# password = "db-password"
+# [database.auth.ssl]
+# ca = "-----BEGIN CERTIFICATE-----\nMIIE...\n-----END CERTIFICATE-----"
+# rejectUnauthorized = true
+# [database.auth.ssh]
+# host = "jump.example.com"
+# port = 22
+# username = "deploy"
+# privateKeyPath = "/home/user/.ssh/deploy_key"
+# passphrase = "key-passphrase"
+# localPort = 53306
+
 # Aggressive cleanup (development)
 # [autodelete]
 # message_hours = 1