name: pg-copilot description: "PostgreSQL AI 助手 - 自然語言轉 SQL、SQL 轉自然語言、ERD、效能最佳化、分割槽管理、即時同步。一個技能搞定 PostgreSQL 所有需求。"

pg-copilot 🐘

PostgreSQL AI 助手 | 自然語言轉 SQL | SQL 轉自然語言 | 效能最佳化 | 即時同步

功能概覽

Quick Reference

核心功能

1. 自然語言查詢

使用者：幫我查每個使用者的訂單總金額

技能：
## 生成的 SQL
```sql
SELECT 
    u.name AS 使用者名稱,
    SUM(o.amount) AS 訂單總金額
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id, u.name
ORDER BY 訂單總金額 DESC;

### 2. SQL 轉自然語言

使用者：解釋這個查詢結果 SELECT u.name, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id, u.name

技能：

查詢結果解釋

查詢型別：分組統計

結果摘要：共 5 條記錄

詳細分析： | 使用者名稱 | 訂單數 | |--------|--------| | 李四 | 4 | | 張三 | 4 | | 王五 | 2 |

統計： - 總訂單數：10 - 平均訂單數：2 - 最多訂單：4 - 最少訂單：0

**方式一：LLM 智慧解釋（推薦）**

需要配置 LLM API：

```bash
# 配置 LLM（支援 OpenAI/Claude 等相容 API）
python scripts/pg_copilot.py config-llm <api_url> <api_key> [model]

# 示例
python scripts/pg_copilot.py config-llm https://api.openai.com/v1/chat/completions sk-xxx

方式二：簡單解析（預設）

未配置 LLM 時自動使用。

3. ERD 視覺化

使用者：畫出使用者表和訂單表的關係

技能：
```mermaid
erDiagram
    USERS ||--o{ ORDERS : places
    USERS { int id PK, varchar name, varchar email }
    ORDERS { int id PK, int user_id FK, numeric amount }

---

## 即時同步功能 ⚡

### 前置條件

**重要：使用同步功能前必須滿足：**

1. **源表必須有主鍵** - 同步依賴主鍵定位記錄
   ```sql
   -- 如果表沒有主鍵，新增：
   ALTER TABLE my_table ADD COLUMN id SERIAL PRIMARY KEY;
   ```

2. **安裝依賴** - 需要 pymysql 支援 MySQL 目標
   ```bash
   pip install pymysql
   ```

3. **目標資料庫可訪問** - 網路連通

---

### 同步表結構

#### _sync_config（配置表）

儲存同步任務配置：

| 欄位 | 型別 | 說明 | 必填 |
|------|------|------|------|
| source_table | VARCHAR(255) | 源表名 | ✅ |
| target_host | VARCHAR(255) | 目標資料庫地址 | ✅ |
| target_port | INTEGER | 目標埠（PG預設5432，MySQL預設3306） | ✅ |
| target_user | VARCHAR(255) | 目標資料庫使用者名稱 | ✅ |
| target_password | VARCHAR(255) | 目標資料庫密碼（Base64加密儲存） | ✅ |
| target_database | VARCHAR(255) | 目標資料庫名 | ✅ |
| target_table | VARCHAR(255) | 目標表名（預設=源表名） | |
| target_type | VARCHAR(20) | 目標型別：**postgresql** 或 **mysql** | ✅ |
| sync_mode | VARCHAR(20) | 同步模式：realtime/batch | |
| enabled | BOOLEAN | 是否啟用 | |
| **max_retries** | INTEGER | **失敗重試次數（預設3）** | |
| **webhook_url** | TEXT | **告警 Webhook URL** | |
| **sync_batch_size** | INTEGER | **批次大小（預設100）** | |

#### _sync_changes（變更隊列表）

自動記錄所有變更（由觸發器填充）：

| 欄位 | 型別 | 說明 |
|------|------|------|
| id | BIGSERIAL | 主鍵 |
| table_name | VARCHAR(255) | 表名 |
| operation | VARCHAR(10) | 操作：INSERT/UPDATE/DELETE |
| record_id | INTEGER | 記錄ID（主鍵值） |
| old_data | JSONB | 舊資料（UPDATE/DELETE） |
| new_data | JSONB | 新資料（INSERT/UPDATE） |
| synced | BOOLEAN | 是否已同步 |
| created_at | TIMESTAMP | 變更時間 |

#### _sync_log（同步日誌表）

記錄所有同步操作：

| 欄位 | 型別 | 說明 |
|------|------|------|
| id | SERIAL | 主鍵 |
| table_name | VARCHAR(255) | 表名 |
| operation | VARCHAR(20) | 操作型別 |
| record_id | INTEGER | 記錄ID |
| target_db | VARCHAR(255) | 目標資料庫 |
| status | VARCHAR(20) | 狀態：success/failed |
| error_message | TEXT | 錯誤資訊 |
| created_at | TIMESTAMP | 執行時間 |

---

### 配置示例

**初始化同步表：**
```bash
python scripts/pg_copilot.py sync-init

同步到 MySQL（生產環境）：

# sync-add 引數說明
# <table> <host> <port> <user> <password> <db> <target_table> [type] [retries] [webhook] [batch]

python scripts/pg_copilot.py sync-add \
    users \
    <target_host> \
    <port> \
    <username> \
    <password> \
    <database> \
    users \
    mysql \
    3 \
    https://your-webhook-url \
    100

同步到 PostgreSQL：

INSERT INTO _sync_config 
    (source_table, target_host, target_port, target_user, target_password, target_database, target_table, target_type, max_retries, webhook_url)
VALUES 
    ('orders', '<target_host>', <port>, '<username>', '<password>', '<database>', 'orders', 'postgresql', 3, 'https://your-webhook-url');

生產環境特性

檢視同步狀態

python scripts/pg_copilot.py sync-status
7w4.net小蔥技能。

分割槽管理

範圍分割槽（按時間）

CREATE TABLE orders_partitioned (
    LIKE orders INCLUDING ALL
) PARTITION BY RANGE (created_at);

CREATE TABLE orders_2024_01 PARTITION OF orders_partitioned
    FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');

列表分割槽（按狀態）

CREATE TABLE orders_by_status (
    LIKE orders INCLUDING ALL
) PARTITION BY LIST (status);

CREATE TABLE orders_pending PARTITION OF orders_by_status
    FOR VALUES IN ('pending');

雜湊分割槽（按 ID）

CREATE TABLE users_partitioned (
    LIKE users INCLUDING ALL
) PARTITION BY HASH (user_id);

CREATE TABLE users_p0 PARTITION OF users_partitioned
    FOR VALUES WITH (MODULUS 4, REMAINDER 0);

CLI 命令

# 配置資料庫
python scripts/pg_copilot.py config <host> <port> <user> <password> <database>

# 基本操作
python scripts/pg_copilot.py test                    # 測試連線
python scripts/pg_copilot.py schema                  # 獲取 Schema
python scripts/pg_copilot.py execute "SELECT..."   # 執行 SQL
python scripts/pg_copilot.py narrate "SELECT..."   # SQL 轉自然語言
python scripts/pg_copilot.py explain "SELECT..."    # 效能分析

# 同步功能
python scripts/pg_copilot.py sync-init              # 初始化同步表
python scripts/pg_copilot.py sync-add <table> <host> ...  # 新增同步任務
python scripts/pg_copilot.py sync-status            # 檢視狀態
python scripts/pg_copilot.py sync-watch             # 監聽同步

依賴

• Python 3.8+
• psycopg2-binary
• pymysql（用於 MySQL 目標同步）

pg-copilot - 讓 PostgreSQL 管理和同步像說話一樣簡單

這個 Skill 質量不錯，功能非常豐富，文件寫得清楚明白。核心亮點是即時同步功能，支援把資料同步到其他 PostgreSQL 或 MySQL 資料庫，還有重試、告警等貼心設計。不足之處是密碼加密比較簡單（只是 Base64 編碼），如果用於正式生產環境，建議額外保護好配置檔案。總體來說，這是一個實用性強、誠意十足的資料庫管理工具。