@gordon.gan/specflow 1.3.3-beta → 1.4.1

package/skills/database/oracle/references/10-features.md

@@ -0,0 +1,174 @@
+# Oracle 特有特性 — 分区 / 索引 / 物化视图 / Flashback / AQ
+
+## 表空间与数据文件
+
+```sql
+-- 创建表空间
+CREATE TABLESPACE tbs_app_data
+    DATAFILE '/u01/oradata/orcl/app_data01.dbf' SIZE 10G
+    AUTOEXTEND ON NEXT 1G MAXSIZE 32G;
+
+-- 创建临时/撤销表空间
+CREATE TEMPORARY TABLESPACE tbs_app_temp TEMPFILE '/u01/oradata/orcl/app_temp01.dbf' SIZE 5G;
+CREATE UNDO TABLESPACE tbs_app_undo DATAFILE '/u01/oradata/orcl/app_undo01.dbf' SIZE 10G;
+
+-- 表空间管理
+ALTER TABLESPACE tbs_app_data ADD DATAFILE '/u01/oradata/orcl/app_data02.dbf' SIZE 10G;
+ALTER TABLESPACE tbs_app_data READ ONLY;
+ALTER TABLESPACE tbs_app_data OFFLINE NORMAL;
+
+-- 表空间使用率
+SELECT df.tablespace_name,
+       ROUND(df.bytes/1024/1024/1024,2) AS total_gb,
+       ROUND((1-fs.bytes/df.bytes)*100,2) AS used_pct
+FROM (SELECT tablespace_name, SUM(bytes) AS bytes FROM dba_data_files GROUP BY tablespace_name) df
+JOIN (SELECT tablespace_name, SUM(bytes) AS bytes FROM dba_free_space GROUP BY tablespace_name) fs
+ON df.tablespace_name = fs.tablespace_name;
+```
+
+## 分区表
+
+```sql
+-- RANGE 分区
+CREATE TABLE sales (
+    sale_id NUMBER(10), sale_date DATE, amount NUMBER(10,2)
+) PARTITION BY RANGE (sale_date) (
+    PARTITION p_2023_q1 VALUES LESS THAN (DATE '2023-04-01'),
+    PARTITION p_2023_q2 VALUES LESS THAN (DATE '2023-07-01'),
+    PARTITION p_future VALUES LESS THAN (MAXVALUE)
+);
+
+-- LIST 分区
+CREATE TABLE customers PARTITION BY LIST (region) (
+    PARTITION p_north VALUES ('北京','天津','河北'),
+    PARTITION p_east VALUES ('上海','江苏','浙江'),
+    PARTITION p_other VALUES (DEFAULT)
+);
+
+-- HASH 分区
+CREATE TABLE logs PARTITION BY HASH (log_id) PARTITIONS 8;
+
+-- 复合分区（RANGE-HASH）
+CREATE TABLE sales_comp PARTITION BY RANGE (sale_date)
+SUBPARTITION BY HASH (region) SUBPARTITIONS 4 (
+    PARTITION p_2023_q1 VALUES LESS THAN (DATE '2023-04-01')
+);
+
+-- 间隔分区（11g+ 自动建分区）
+CREATE TABLE sales_interval PARTITION BY RANGE (sale_date)
+INTERVAL(NUMTOYMINTERVAL(1,'MONTH')) (
+    PARTITION p_first VALUES LESS THAN (DATE '2023-01-01')
+);
+
+-- 分区操作
+ALTER TABLE sales ADD PARTITION p_2024_q1 VALUES LESS THAN (DATE '2024-04-01');
+ALTER TABLE sales TRUNCATE PARTITION p_future;
+ALTER TABLE sales EXCHANGE PARTITION p_2023_q1 WITH TABLE sales_2023_q1;
+ALTER TABLE sales MERGE PARTITIONS p_2023_q1, p_2023_q2 INTO PARTITION p_2023_h1;
+ALTER TABLE sales SPLIT PARTITION p_future AT (DATE '2024-04-01')
+    INTO (PARTITION p_2024_q1, PARTITION p_future);
+```
+
+## 索引
+
+```sql
+-- B-Tree 索引（默认）
+CREATE INDEX idx_emp_dept_id ON employees(department_id);
+CREATE INDEX idx_emp_dept_name ON employees(department_id, last_name);  -- 复合
+CREATE UNIQUE INDEX idx_emp_email ON employees(email);                 -- 唯一
+
+-- 位图索引（适合低基数、数据仓库）
+CREATE BITMAP INDEX idx_sales_region ON sales(region);
+
+-- 函数索引
+CREATE INDEX idx_emp_upper_name ON employees(UPPER(last_name));
+
+-- 域索引（Oracle Text 全文）
+CREATE INDEX idx_docs_content ON documents(content) INDEXTYPE IS CTXSYS.CONTEXT;
+
+-- 索引监控
+ALTER INDEX idx_emp_dept_id MONITORING USAGE;
+SELECT * FROM v$object_usage;  -- 查看未被使用的索引
+```
+
+## 物化视图
+
+```sql
+-- 基本物化视图
+CREATE MATERIALIZED VIEW mv_dept_salary_summary
+    BUILD IMMEDIATE REFRESH COMPLETE ON DEMAND ENABLE QUERY REWRITE
+AS SELECT d.department_id, d.department_name,
+          COUNT(e.employee_id) AS emp_count, SUM(e.salary) AS total_salary
+FROM departments d LEFT JOIN employees e ON d.department_id = e.department_id
+GROUP BY d.department_id, d.department_name;
+
+-- 快速刷新物化视图（需物化视图日志）
+CREATE MATERIALIZED VIEW LOG ON employees WITH PRIMARY KEY, ROWID (salary, department_id) INCLUDING NEW VALUES;
+CREATE MATERIALIZED VIEW mv_emp_fast
+    BUILD IMMEDIATE REFRESH FAST ON COMMIT
+AS SELECT department_id, COUNT(*) AS cnt, SUM(salary) AS total_sal
+FROM employees GROUP BY department_id;
+
+-- 刷新
+EXEC DBMS_MVIEW.REFRESH('mv_dept_salary_summary', 'C');  -- C=完全, F=快速
+ALTER SESSION SET QUERY_REWRITE_ENABLED = TRUE;
+```
+
+## Flashback 技术
+
+```sql
+-- Flashback Query — 见 references/09-sql-syntax.md
+
+-- Flashback Table（需启用行移动）
+ALTER TABLE employees ENABLE ROW MOVEMENT;
+FLASHBACK TABLE employees TO TIMESTAMP (SYSTIMESTAMP - INTERVAL '15' MINUTE);
+FLASHBACK TABLE employees TO SCN 1234567;
+FLASHBACK TABLE employees TO RESTORE POINT before_batch;
+
+-- Flashback Drop（回收站）
+DROP TABLE employees;
+SELECT object_name, original_name, droptime FROM recyclebin;
+FLASHBACK TABLE employees TO BEFORE DROP;
+
+-- Flashback Database（需启用闪回日志）
+-- FLASHBACK DATABASE TO TIMESTAMP (SYSTIMESTAMP - INTERVAL '1' HOUR);
+```
+
+## AQ（Advanced Queuing）— 高级队列
+
+```sql
+-- 创建类型和队列表
+CREATE OR REPLACE TYPE order_msg AS OBJECT (order_id NUMBER, customer_id NUMBER, amount NUMBER);
+/
+BEGIN
+    DBMS_AQADM.CREATE_QUEUE_TABLE(queue_table => 'order_queue_table', queue_payload_type => 'order_msg');
+    DBMS_AQADM.CREATE_QUEUE(queue_name => 'order_queue', queue_table => 'order_queue_table');
+    DBMS_AQADM.START_QUEUE(queue_name => 'order_queue');
+END;
+/
+
+-- 发送消息
+DECLARE
+    enqueue_options    DBMS_AQ.ENQUEUE_OPTIONS_T;
+    message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
+    message_handle     RAW(16);
+    msg                order_msg := order_msg(1001, 500, 1500.00);
+BEGIN
+    DBMS_AQ.ENQUEUE('order_queue', enqueue_options, message_properties, msg, message_handle);
+    COMMIT;
+END;
+/
+
+-- 接收消息
+DECLARE
+    dequeue_options    DBMS_AQ.DEQUEUE_OPTIONS_T;
+    message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
+    message_handle     RAW(16);
+    msg                order_msg;
+BEGIN
+    dequeue_options.wait := DBMS_AQ.FOREVER;
+    DBMS_AQ.DEQUEUE('order_queue', dequeue_options, message_properties, msg, message_handle);
+    COMMIT;
+END;
+/
+```

package/skills/database/postgresql/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/database/postgresql/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: postgresql
+description: Provides comprehensive guidance for PostgreSQL including SQL syntax, advanced features (JSONB/CTE/Full-text), functions, indexing, performance tuning, replication, and backup. Use when the user asks about PostgreSQL, needs to work with PostgreSQL features, write complex queries, or optimize PostgreSQL databases.
+license: Complete terms in LICENSE.txt
+---
+
+# PostgreSQL — 高级关系型数据库系统
+
+## Workflow — 使用流程
+
+```text
+遇到 PostgreSQL 需求时，按以下顺序决策:
+
+1. 明确需求类型
+   ├── DDL (建表/改表)        → 见 SQL 语法速查
+   ├── DML (查询/插入/更新)    → 见 SQL 语法速查
+   ├── 函数/数据处理            → 见 函数速查
+   ├── 查询性能优化             → 见 references/06-index-types.md + examples/03-performance-tuning.md
+   └── 高可用/备份/复制         → 见 references/08-replication-backup.md + examples/04-streaming-replication.md
+
+2. 确定模型: 关系型 → 标准表+B-Tree | JSON文档 → JSONB+GIN | 全文搜索 → tsvector+GIN | 地理 → PostGIS+GiST
+
+3. 索引策略: 等值→B-Tree | 范围→B-Tree | 全文→GIN | JSON→GIN | 向量→IVFFlat/HNSW | 大表时序→BRIN
+
+4. 数据量评估: <100GB→单实例 | 100GB-1TB→分区 | 1TB-10TB→分区+只读副本 | >10TB→Citus/逻辑复制
+
+5. 运维策略: autovacuum + pg_stat_statements + WAL归档 + PgBouncer
+```
+
+## When to Use (and When NOT to)
+
+| ✅ Use When | ❌ Skip When |
+|------------|-------------|
+| 需要完整 ACID 事务和复杂 SQL | 纯键值缓存 (用 Redis/Memcached) |
+| JSON 文档 + SQL 查询混合 | 纯文档无关联查询 (用 MongoDB) |
+| 地理空间数据分析 (PostGIS) | 大规模全文搜索 (用 Elasticsearch) |
+| 强数据完整性约束 | 海量无模式日志 (用 Elasticsearch/S3) |
+| OLTP + 复杂 OLAP 混合负载 | 超大规模 OLAP (用 ClickHouse/Snowflake) |
+| 需要流复制/逻辑复制/PITR | 自动水平分片 (用 CockroachDB/YugabyteDB) |
+
+**核心原则：PostgreSQL 是全能型关系型数据库，但不是所有场景的最佳选择。**
+
+## Boundary — 能力边界
+
+| ✅ 完全适用 | ⚠️ 有条件适用 | ❌ 不适用 → 替代 |
+|------------|--------------|----------------|
+| 标准 OLTP 业务系统 | 超大规模 OLAP >20TB → ClickHouse/cstore_fdw | 纯内存缓存 <1ms → Redis |
+| JSONB + 关系查询混合 | 高并发简单 KV >50万 QPS → Redis | 海量时序写入 >100万点/秒 → InfluxDB |
+| 全文搜索 (数亿文档) | 实时搜索 >10亿文档 → Elasticsearch | 复杂图遍历 → Neo4j |
+| 流复制 HA (故障恢复 <30s) | 跨地域多活 → CockroachDB | 自动分片无感扩缩容 |
+
+## SQL 语法速查
+
+深度 SQL 内容见 `references/` 各文件，此处为索引。
+
+- **DDL**: `CREATE TABLE` (含分区、继承), `ALTER TABLE`, 数据类型 (JSONB/TSVECTOR/CITEXT/数组等), 约束 (CHECK/EXCLUDE/UNIQUE/FOREIGN KEY)
+- **DML**: `INSERT ... ON CONFLICT` (UPSERT), `UPDATE ... FROM`, `DELETE ... USING`, `TRUNCATE`, `RETURNING` 子句
+- **CTE**: 公用表表达式 (`WITH`), 递归 CTE (`WITH RECURSIVE`) — 见 `examples/02-cte-recursive.md`
+- **连接**: `INNER/LEFT/RIGHT/FULL/CROSS JOIN`, `LATERAL` 子查询
+- **事务**: `READ COMMITTED` (默认), `REPEATABLE READ`, `SERIALIZABLE`, `SAVEPOINT`, `FOR UPDATE/SHARE/NOWAIT/SKIP LOCKED`, 咨询锁
+
+## 函数速查
+
+深度内容见 `references/`:
+
+| 类别 | 关键函数 | 参考文件 |
+|------|---------|---------|
+| 字符串/正则 | `FORMAT`, `SPLIT_PART`, `REGEXP_MATCH/REPLACE`, `STRING_AGG`, `CONCAT_WS`, `TRANSLATE`, `SUBSTRING` | `references/01-functions-string.md` |
+| 日期/时间 | `AGE`, `DATE_TRUNC`, `EXTRACT`, `TO_CHAR`, `MAKE_DATE`, `JUSTIFY_*`, 时区转换 | `references/02-functions-datetime.md` |
+| 聚合/窗口 | `ARRAY_AGG`, `JSONB_AGG`, `STRING_AGG`, `PERCENTILE_CONT/DISC`, `MODE`, `GROUPING SETS/CUBE/ROLLUP`, `ROW_NUMBER`, `RANK`, `LAG/LEAD`, `NTILE`, 窗口帧 | `references/03-functions-aggregate-window.md` |
+| JSONB | `->`/`->>`/`#>`, `@>`/`?`/`?|`/`?&`, `JSONB_SET`, `JSONB_BUILD_OBJECT`, `JSONB_EACH`, `JSONB_TYPEOF`, GIN 索引 | `references/04-functions-jsonb.md` |
+
+## 高级特性索引
+
+| 特性 | 说明 | 参考 |
+|------|------|------|
+| 6种索引 | B-Tree, Hash, GiST, GIN, BRIN, SP-GiST, Bloom + 部分索引/覆盖索引/CONCURRENTLY | `references/06-index-types.md` |
+| 视图与物化视图 | 普通视图 (虚拟表) vs 物化视图 (物理快照), WITH CHECK OPTION, CONCURRENTLY 刷新 | `references/06-index-types.md` |
+| PL/pgSQL | 函数 (FUNCTION) vs 过程 (PROCEDURE), 控制结构, 异常处理, 函数重载 | `references/01-functions-string.md` |
+| 触发器 | BEFORE/AFTER/INSTEAD OF, 行级/语句级, 事件触发器, 约束触发器 | `references/01-functions-string.md` |
+| 全文搜索 | tsvector/tsquery, @@ 操作符, ts_rank, ts_headline, 短语搜索, 中文搜索 (zhparser) | `references/05-fulltext-search.md` |
+| 分区表 | RANGE/LIST/HASH 分区, 子分区, 分区裁剪, ATTACH/DETACH | `references/07-partition-fdw.md` |
+| FDW 外部表 | postgres_fdw, file_fdw, IMPORT FOREIGN SCHEMA | `references/07-partition-fdw.md` |
+| 扩展 | PostGIS, pgvector, pg_stat_statements, uuid-ossp, pgcrypto, citext, pg_trgm, unaccent | `references/08-replication-backup.md` |
+| 权限管理 | ROLE, SCHEMA, GRANT, 默认权限, RLS 行级安全 | `references/08-replication-backup.md` |
+| 流复制与逻辑复制 | 同步/异步, PUBLICATION/SUBSCRIPTION, Patroni/repmgr | `references/08-replication-backup.md` |
+| 备份与恢复 | pg_dump/pg_restore, pg_basebackup, WAL 归档 + PITR | `references/08-replication-backup.md` |
+| 性能优化 | EXPLAIN ANALYZE, VACUUM/autovacuum, pg_stat_statements, 配置调优 | `examples/03-performance-tuning.md` |
+
+## Gotchas — 常见陷阱与反模式
+
+| # | 陷阱 | 风险 | 解决方案 |
+|---|------|------|---------|
+| 1 | JSONB 未建 GIN 索引 | 全表扫描, 性能差 | `CREATE INDEX ... USING GIN (config)` |
+| 2 | 大量直连数据库 | 每个连接耗 5-10MB, 撑爆内存 | 使用 PgBouncer 连接池 |
+| 3 | 索引膨胀未维护 | 索引体积远超表大小 | 定期 `REINDEX` 或 pg_repack |
+| 4 | N+1 查询 + `SELECT *` | 传输冗余数据, 多次查询 | 只选需要列, 用 JOIN/LATERAL |
+| 5 | 生产高峰期 `VACUUM FULL` | 锁表, 业务中断 | 用 pg_repack (不锁表) |
+| 6 | autovacuum 触发不及时 | 死元组堆积 → 表膨胀 → 性能崩溃 | 监控 n_dead_tup, 调参 |
+| 7 | `SERIAL` 而非 `BIGSERIAL` | 超 21 亿行后 ID 溢出 | 新表用 `BIGSERIAL` 或 UUID |
+| 8 | 多租户未设 RLS | 数据泄露 | 启用 RLS + 外键约束 |
+| 9 | 忽略事务 ID 回卷 | 数据库强制只读 | 监控 `age(relfrozenxid)` |
+| 10 | UUID 做主键 (v4 随机) | B-Tree 页分裂, 写入慢 2-3x | 用 UUID v7 或 BIGSERIAL |
+| 11 | 大表 `COUNT(*)` | 千万行以上全表扫描极慢 | 用 `pg_class.reltuples` 近似值 |
+| 12 | 外键无索引 | 删除/更新父表时子表全表扫描 | 外键列上建索引 |
+| 13 | SERIALIZABLE 无重试逻辑 | 事务冲突失败 | 应用层实现重试 |
+
+## FAQ
+
+**Q1: PostgreSQL vs MySQL 主要区别？**
+PostgreSQL: 完全 ACID, JSONB 可索引, 6 种索引类型, 递归 CTE, 流复制+逻辑复制, 丰富 EXTENSION。MySQL: Web 应用为主, 简单查询, InnoDB 事务, 间隙锁并发控制。
+
+**Q2: JSONB vs JSON？**
+始终选 JSONB。二进制格式, 支持 GIN 索引, 查询更快。JSON 仅在你需要保留空格和键顺序时使用。
+
+**Q3: UUID 为什么不适合做主键？**
+UUID v4 随机值导致 B-Tree 页频繁分裂, 比 BIGSERIAL 慢 2-3 倍。方案: UUID v7 (时间排序), BIGSERIAL, 或 ULID/Snowflake。
+
+**Q4: 如何在线迁移 PostgreSQL？**
+逻辑复制 (PG 10+, 推荐) > pglogical 扩展 > pg_dump+pg_restore (需停机)。逻辑复制支持跨大版本、选择性复制。
+
+**Q5: work_mem 怎么设？**
+每个排序操作分配, 最大内存 = work_mem × (连接数 × 并发排序数)。64GB 机器建议 64-128MB。监控 temp_files 指标, 有磁盘排序则调大。
+
+**Q6: pg_repack vs VACUUM FULL？**
+VACUUM FULL 锁表 (ACCESS EXCLUSIVE)。pg_repack 不锁写, 适合在线环境, 优先选择。
+
+**Q7: 死锁怎么处理？**
+PG 自动检测并回滚一个事务。预防: 保持锁顺序一致、缩短事务、用 NOWAIT/SKIP LOCKED, 监控 pg_stat_database.deadlocks。
+
+**Q8: 如何选择分区键？**
+条件: 查询频繁出现 (分区裁剪)、数据均匀分布、稳定不变。常见: 时间 (RANGE)、地区 (LIST)、ID 哈希 (HASH)。分区数建议 10-200。
+
+**Q9: 连接数设多少？**
+每个连接 5-10MB, 一般 200-500 够用。超过 500 必须用 PgBouncer。(max_connections × work_mem × 0.5) + shared_buffers + 系统开销 < 内存 80%。
+
+**Q10: 何时用 SERIALIZABLE？**
+金融转账、库存扣减、强一致性报表。注意: 失败率随冲突上升, 应用层需重试逻辑。
+
+**Q11: 查询没走索引的原因？**
+统计信息过旧→ANALYZE | 类型不匹配→隐式转换 | 选择性低→规划器认为全表更优 | 函数包裹索引列→避免 WHERE DATE(col) = 写法。
+
+**Q12: 怎么判断要不要分区？**
+表 > 100GB | 存在明显按时间/地区查询模式 | 旧数据定期归档 | VACUUM 跟不上更新。不满足则分区复杂度 > 收益。
+
+**Q13: 如何大版本升级？**
+pg_upgrade 最推荐: `pg_upgrade -b old_bin -B new_bin -d old_data -D new_data`, --link 模式最快。升级后执行 ANALYZE。
+
+**Q14: 逻辑复制 vs 流复制？**
+流复制: 物理块级, 全库, 大版本必须一致, 用于 HA。逻辑复制: SQL 变更, 选表/行, 跨大版本, 用于数据同步/迁移。
+
+**Q15: VACUUM 后表大小没变小？**
+VACUUM (不带 FULL) 只标记空间可重用, 不还给 OS。真正缩小需 VACUUM FULL 或 pg_repack。
+
+## Keywords
+
+postgresql, postgres, psql, SQL, DDL, DML, ACID, MVCC, 事务, 索引, B-Tree, GIN, GiST, BRIN, JSONB, hstore, 数组, 全文搜索, tsvector, tsquery, 窗口函数, CTE, 递归CTE, LATERAL, PL/pgSQL, 存储过程, 触发器, 物化视图, 分区表, PostGIS, pgvector, pg_stat_statements, pgcrypto, citext, pg_trgm, FDW, postgres_fdw, EXPLAIN, VACUUM, autovacuum, pg_dump, pg_restore, pg_basebackup, WAL归档, PITR, 流复制, 逻辑复制, PUBLICATION, SUBSCRIPTION, Patroni, repmgr, PgBouncer, RLS, 行级安全, 性能优化, 备份恢复, 高可用, 死锁, 连接池
+
+## References
+
+- [PostgreSQL 官方文档](https://www.postgresql.org/docs/current/)
+- [PostgreSQL 中文文档](http://www.postgres.cn/docs/16/)
+- [PostgreSQL 性能调优 — pgtune](https://pgtune.leopard.in.ua)
+- [Patroni 文档](https://patroni.readthedocs.io/)
+- [PgBouncer 官方文档](https://www.pgbouncer.org/)
+- [pgvector 文档](https://github.com/pgvector/pgvector)
+- [PostGIS 文档](https://postgis.net/documentation/)
+
+### 内部参考
+
+- `references/01-functions-string.md` — 字符串/正则函数详解
+- `references/02-functions-datetime.md` — 日期/时间函数详解
+- `references/03-functions-aggregate-window.md` — 聚合/窗口函数详解
+- `references/04-functions-jsonb.md` — JSONB 函数与操作详解
+- `references/05-fulltext-search.md` — 全文搜索详解
+- `references/06-index-types.md` — 索引类型与视图详解
+- `references/07-partition-fdw.md` — 分区表与 FDW 详解
+- `references/08-replication-backup.md` — 复制/备份/权限详解
+- `examples/01-jsonb-query.md` — JSONB 查询示例
+- `examples/02-cte-recursive.md` — 递归 CTE 示例
+- `examples/03-performance-tuning.md` — 性能调优示例
+- `examples/04-streaming-replication.md` — 流复制搭建示例

package/skills/database/postgresql/examples/01-jsonb-query.md

@@ -0,0 +1,72 @@
+# JSONB 查询示例
+
+## 场景：电商用户配置系统
+
+本示例演示如何使用 JSONB 存储和查询用户偏好配置。
+
+## 建表与数据
+
+```sql
+-- 建表
+CREATE TABLE user_configs (
+    id      BIGSERIAL PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    config  JSONB NOT NULL DEFAULT '{}'
+);
+
+-- 插入示例数据
+INSERT INTO user_configs (user_id, config) VALUES
+(1, '{
+    "theme": "dark",
+    "notifications": {"email": true, "sms": false, "push": true},
+    "preferences": {"language": "zh-CN", "timezone": "Asia/Shanghai"},
+    "tags": ["developer", "premium"],
+    "trust_score": 4.5
+}'),
+(2, '{
+    "theme": "light",
+    "notifications": {"email": false, "sms": true, "push": false},
+    "preferences": {"language": "en", "timezone": "America/New_York"},
+    "tags": ["basic"]
+}');
+
+-- 创建 GIN 索引
+CREATE INDEX idx_config_gin ON user_configs USING GIN (config);
+```
+
+## 查询示例
+
+```sql
+-- 1. 查询所有使用深色主题的用户
+SELECT user_id, config ->> 'theme' AS theme
+FROM user_configs
+WHERE config @> '{"theme": "dark"}';
+
+-- 2. 查询开启了邮件通知的用户
+SELECT user_id FROM user_configs
+WHERE config @> '{"notifications": {"email": true}}';
+
+-- 3. 查询有 trust_score 字段的用户
+SELECT user_id FROM user_configs WHERE config ? 'trust_score';
+
+-- 4. 查询语言为中文的高级用户 (tags 包含 "premium")
+SELECT user_id FROM user_configs
+WHERE config @> '{"preferences": {"language": "zh-CN"}}'
+  AND config @> '{"tags": ["premium"]}';
+
+-- 5. 更新嵌套字段（开启 SMS 通知）
+UPDATE user_configs SET config = JSONB_SET(
+    config, '{notifications, sms}', 'true'::JSONB
+) WHERE user_id = 1;
+
+-- 6. 追加标签
+UPDATE user_configs SET config = config || '{"tags": ["vip"]}'
+WHERE user_id = 1;
+
+-- 7. 展开 JSONB 查看所有键值对
+SELECT key, value FROM user_configs c,
+JSONB_EACH(c.config) WHERE user_id = 1;
+
+-- 8. 聚合用户配置为 JSONB 数组
+SELECT JSONB_AGG(config) AS all_configs FROM user_configs;
+```