Oracle SQL 编写（DDL / DML / PL/SQL）

何时使用

满足以下任一情况时使用（本技能覆盖 DDL、DML 与承载它们的 PL/SQL 程序单元的编写与审阅）：

• 需要新建或修改数据库对象：表、索引、约束、分区、表空间、序列、视图、物化视图、数据库链接、虚拟列、用户
• 需要编写查询或增删改语句，尤其是要落到生产库上的
• 需要编写或修改存储过程、函数、包、触发器、匿名块
• 有语句执行报错，需要定位原因并改正
• 需要判断一段 SQL 是否合法、是否存在注入风险、是否该被拦截

目录结构

oracle-sql-authoring/
├── SKILL.md
├── scripts/
│   └── check_sql.py
└── references/
    ├── admin/
    ├── agent/
    ├── appdev/
    ├── design/
    ├── devops/
    ├── features/
    ├── performance/
    ├── plsql/
    └── sql-dev/

参考文档索引

常用入口

• references/sql-dev/sql-best-practices.md
• references/sql-dev/sql-patterns.md
• references/agent/schema-discovery.md
• references/agent/safe-dml-patterns.md
• references/agent/idempotency-patterns.md
• references/agent/ora-error-catalog.md
• references/plsql/plsql-error-handling.md
• references/design/data-modeling.md

静态检查脚本

scripts/check_sql.py 对 SQL 做纯文本层面的检查，不连接数据库、不执行任何语句。

python3 scripts/check_sql.py 脚本.sql          # 检查文件
python3 scripts/check_sql.py -                 # 从标准输入读取
cat 脚本.sql | python3 scripts/check_sql.py -
python3 scripts/check_sql.py --json 脚本.sql   # 结构化输出
python3 scripts/tests/run_matrix.py            # 自检：13 用例回归矩阵，全过应退出 0

检查三类问题：

1. 语句合法性——括号与引号配对、BEGIN/END 配对、必备子句（INSERT … INTO、UPDATE … SET、DELETE … FROM、MERGE … USING/ON）、起始关键字拼写、UPDATE/DELETE 是否漏写 WHERE
2. 注入风险——动态 SQL（EXECUTE IMMEDIATE、OPEN … FOR、DBMS_SQL）用 || 拼接、拼接变量未经 DBMS_ASSERT 校验、DBMS_SQL.PARSE 缺 BIND、恒真条件残留
3. 危险语句闸门——按下面的环境变量决定是否放行

环境变量 ORACLE_SQL_ACCESS_MODE

未设置时按 readonly 处理——默认只读是刻意的：不显式声明允许写，就不放行写操作。取值非法时退回 readonly 并在标准错误输出告警。

闸门按语句逐条判定，不是只看第一条——SELECT 1 FROM DUAL; DROP TABLE users; 里的 DROP 照样会被拦下。匿名块内部同样逐条扫描；块内的动态 SQL 会按其语句文本判定，因此 EXECUTE IMMEDIATE 'DROP TABLE orders' 被识别为写操作，而语句文本来自变量的（如 EXECUTE IMMEDIATE v_sql）因无法静态确认，在只读模式下一律拦截。

# 只读（默认）直接跑；要写库时加前缀：ORACLE_SQL_ACCESS_MODE=readwrite python3 …
python3 scripts/check_sql.py query.sql

退出码

多类问题同时存在时返回其中最大的码值。非零即不应执行。

若环境中装有 sqlglot，脚本会用它复核普通 SQL（SELECT/INSERT/UPDATE/DELETE/MERGE/DDL）的语法；未安装时退化为内置结构检查，无需任何第三方依赖。

PL/SQL 程序体不做语法校验。 包、触发器、匿名块只会被检查块配对、括号引号、写操作与注入特征；sqlglot 对这类结构会退化成不透明的命令节点，交出去只会得到"看似合法"的假结论。脚本会在结论中明确标注哪些语句属于这一情况，这些语句的语法正确性需在数据库中编译确认。

常用组合流程

失败与恢复

遇到下列情况按对应分支处理，不要跳过：

每条分支的产出仍然是"过检的语句 + 说明"，与「工作方式」第 4、5 条一致。

工作方式

1. 先明确目标库与口径：方言（DDL 若非 Oracle——如 Hive/Spark 的 STRING、STORED AS parquet——先声明并映射转换 STRING→VARCHAR2、BIGINT→NUMBER(19,0)，不要直接按 Oracle 写）、指标含义、时间字段、粒度、去重键、空值处理。口径不唯一时先问，不要猜。
2. 写 DDL 前先探查现有模式，避免重复创建、命名冲突、类型不匹配。
3. 写 DML 前先确认影响范围，对生产库的写操作先预估行数。
4. 写完必须过脚本：交付前对生成的语句运行 scripts/check_sql.py，确认语法与注入两项均无 × 级问题。
5. 有问题就改，改完再跑：脚本报告 × 级问题时，必须修正语句并重新执行脚本，直到语法与注入检查通过；不得把带问题的语句交付给用户。若某条 × 只是口径不清导致的（例如确实需要对全表 UPDATE），先向用户确认，而不是带病交付。

🔴 检查点（必须停下等用户确认）

到达下列任一情况时，停止生成、先向用户提问，得到明确答复前不得继续交付：

检查点通过后，用户答复写入「口径假设」小节可追溯。

🔴 禁止事项（反例黑名单）

以下写法一律不得出现在交付中：

违反任意一条即未完成，必须改到合规。

不覆盖的范围

数据库运维（实例参数、redo/undo、Data Guard、RAC、多租户）、性能诊断（AWR、ASH、执行计划、优化器统计）、异构库迁移、应用侧驱动与 ORM、命令行工具链、数据库内置 AI 特性——这些不属于本技能。