sql-talk/examples/README.md

SQL Talk - 自然言語をSQLに変換するMCPサーバー（安全性保護・SSHトンネル対応） / SQL Talk - MCP Server for Natural Language to SQL conversion with safety guards and SSH tunnel support

# 設定ファイルサンプル集 / Configuration Samples

このディレクトリには、様々な環境向けの設定ファイルサンプルが含まれています。

*This directory contains configuration file samples for various environments.*

## データベース設定ファイル / Database Configuration Files

### 基本的な設定 / Basic Configuration

- **`sql-talk.config.minimal.yaml`** - 最小限の設定（クイックスタート用）
- **`sql-talk.config.postgres.yaml`** - PostgreSQL用の詳細設定
- **`sql-talk.config.mysql.yaml`** - MySQL用の詳細設定
- **`sql-talk.config.production.yaml`** - 本番環境用設定
- **`sql-talk.config.ssh-tunnel.yaml`** - SSHトンネル接続用設定

### 設定ファイルの使い方 / How to Use Configuration Files

1. **ワークスペースにコピー** / Copy to workspace:
   ```bash
   cp examples/sql-talk.config.postgres.yaml ./sql-talk.config.yaml
   ```

2. **データベース接続情報を編集** / Edit database connection info:
   ```yaml
   connections:
     read_only:
       host: your-db-host
       user: your-username
       password: your-password
       database: your-database
       # SSHトンネル設定（オプション）
       ssh_tunnel:
         enabled: true
         host: ssh-server.example.com
         username: ssh_user
         private_key_path: ~/.ssh/id_rsa
         remote_host: db-server.internal
         remote_port: 5432
   ```

3. **環境変数を設定** / Set environment variables:
   ```bash
   export DB_RO_PASSWORD="your_readonly_password"
   export DB_COMMENT_PASSWORD="your_comment_password"
   export SSH_PASSWORD="your_ssh_password"  # SSHトンネル用
   export SSH_KEY_PASSPHRASE="your_key_passphrase"  # 鍵のパスフレーズ用
   ```

## Cursor MCP設定ファイル / Cursor MCP Configuration Files

### 基本的な設定 / Basic Configuration

- **`cursor-mcp-config.json`** - シンプルな設定（推奨）
- **`cursor-mcp-config-with-env.json`** - 環境変数付き設定

### Cursor設定の使い方 / How to Use Cursor Configuration

1. **Cursor設定ファイルをコピー** / Copy Cursor configuration:
   ```bash
   cp examples/cursor-mcp-config.json ~/.cursor/mcp_servers.json
   ```

2. **設定をカスタマイズ** / Customize configuration:
   ```json
   {
     "mcpServers": {
       "nl-to-sql": {
         "command": "mcp-nl-to-sql",
         "env": {
           "DB_HOST": "your-db-host",
           "DB_RO_PASSWORD": "your-password"
         }
       }
     }
   }
   ```

## 環境別設定の推奨事項 / Environment-Specific Recommendations

### 開発環境 / Development Environment
- `sql-talk.config.minimal.yaml` を使用
- SSL無効、ローカルホスト接続
- デバッグログ有効
- SSHトンネルは通常不要

### ステージング環境 / Staging Environment
- `sql-talk.config.postgres.yaml` または `sql-talk.config.mysql.yaml` を使用
- 環境変数で接続情報を管理
- 適度な制限設定
- SSHトンネル使用を検討

### 本番環境 / Production Environment
- `sql-talk.config.production.yaml` を使用
- SSL有効、厳しい制限設定
- ハッシュ化マスキング推奨
- 手動スキーマ更新
- **SSHトンネル必須**（`sql-talk.config.ssh-tunnel.yaml`を参考）

## セキュリティ考慮事項 / Security Considerations

### パスワード管理 / Password Management
- 設定ファイルにパスワードを直接記載しない
- 環境変数を使用する
- `.env` ファイルやシークレット管理ツールを活用

### SSHトンネルセキュリティ / SSH Tunnel Security
- **パスフレーズ付き秘密鍵を使用**
- **秘密鍵ファイルの権限を600に設定**
- **本番環境では秘密鍵を環境変数で管理**
- **SSH接続のテストを定期的に実行**

### PII保護 / PII Protection
- 本番環境では `strategy: hash` を推奨
- カラムパターンを環境に応じて調整
- 監査ログを適切に管理

### アクセス制御 / Access Control
- 読み取り専用ユーザーとDDLユーザーを分離
- 最小権限の原則を適用
- 承認トークンを安全に管理

## トラブルシューティング / Troubleshooting

### よくある問題 / Common Issues

**設定ファイルが見つからない** / Configuration file not found:
```bash
# 設定ファイルの場所を確認
ls -la mcp-db.config.yaml
```

**データベース接続エラー** / Database connection error:
```bash
# 接続テストを実行
npx mcp-db test-connection
```

**Cursorで認識されない** / Not recognized by Cursor:
```bash
# Cursor設定を確認
cat ~/.cursor/mcp_servers.json
```

### ログの確認 / Check Logs

```bash
# 監査ログを確認
tail -f logs/audit.ndjson

# エラーログを確認
tail -f logs/error.log
```