这次我们直接来聊 SQL 注释。
很多开发同学写 SQL 的时候，注释基本不写，或者只在复制查询时顺手加两行--。真到接手别人留下的存储过程、批量脚本和报表 SQL 时，才意识到注释不是“锦上添花”，而是维护成本的一部分。Neso Academy 的数据库管理系统课程里专门有一节讲 SQL 注释，把行注释、块注释和数据库扩展语法拆开讲清楚了。这篇文章就以这个主题为主线，把 SQL 注释的语法、兼容性、实操技巧、批量脚本里的用法、接口调用中的注意事项都展开说明，并且提供可以直接照做的排查清单。
从实用角度看，SQL 注释值得掌握的点很集中：一是三种语法分别怎么写，二是哪些数据库支持哪些语法，三是注释写在哪里不影响执行结果，四是注释在调参、排错、批量执行、接口程序中怎么配合使用。这篇文章会按照“能认知、能上手、能排查”的顺序一步步来。
1. SQL 注释核心能力速览
SQL 注释不算复杂，但它跨数据库使用时有很多细节差异，先把核心信息压成一张速览表。
| 能力项 | 说明 |
|---|---|
| 核心内容 | SQL 行注释与块注释的语法、行为、使用场景、批量脚本维护 |
| 语法类型 | --行注释、/* */块注释、MySQL/MariaDB 的#行注释、/*! */可执行注释 |
| 覆盖范围 | SELECT、INSERT、UPDATE、DELETE、DDL、存储过程、视图、批量脚本 |
| 兼容数据库 | MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite 等，标准语法通用 |
| 主要价值 | 提高脚本可读性、维护链路可追溯、调试时快速禁用或启用语句 |
| 常见风险 | 注释内容泄露敏感信息，错误使用“可执行注释”导致隐式执行，拼接 SQL 时被恶意利用 |
再看一张语法速览表，方便日常对照。
| 语法 | 类型 | 行为 | 主要兼容性 |
|---|---|---|---|
-- 注释内容 | 行注释 | 从--到行尾不参与执行 | SQL 标准，几乎全数据库支持 |
/* 注释内容 */ | 块注释 | 注释内容可跨行，直到*/结束 | SQL 标准，几乎全数据库支持 |
# 注释内容 | 行注释 | 从#到行尾不参与执行 | MySQL、MariaDB 专属语法 |
/*! 可执行内容 */ | 可执行注释 | MySQL 解析后执行内部语句 | MySQL、MariaDB 专属语法 |
这张表里最容易出问题的是最后一行的/*! */，后面会重点展开。
2. 适用场景与使用边界
SQL 注释适合哪类人使用？简单说，所有需要长期维护数据库脚本的人都应该养成习惯。DBA 运维数据库时，注释可以帮助区分“这个定时任务为什么存在”；后端开发写复杂查询时，注释可以标出业务口径；数据分析师做取数脚本时，注释能告诉下一个接手的同事，这个指标是按哪个时间维度算的。
注释能解决的实际问题很具体。第一，查询脚本的“为什么”通常不能从表结构里直接看出来，注释可以把业务逻辑沉淀在代码旁边。第二，排查问题时，用注释临时停用某条语句，比一行行删除再粘贴恢复要安全得多，尤其在大事务脚本里。第三，线上发布时，带版本说明的注释能让回滚和追溯更直接。
但注释也有使用边界。注释不是文档系统的替代品，业务规则如果频繁变化，只在 SQL 里写注释而不维护，注释很快就会过期。注释也不应该存放数据库账号、密钥、内部服务器地址等敏感信息，因为数据库备份、慢查询日志、客户端历史记录都可能把注释内容带出去。更重要的是，任何把用户输入直接拼进 SQL 的做法，都不应该依赖注释来兜底安全，后面第 9 部分会专门讲这个风险点。
3. 环境准备与前置条件
这篇文章里的示例大多可以直接在本地数据库环境里验证。需要的条件很少，按你的常用数据库选择即可。
推荐准备这几样东西：
- 一个数据库实例：MySQL 8.x、PostgreSQL 15+、SQL Server 2019+、Oracle 21c 四选一，也可以都用。
- 一个 SQL 客户端：DBeaver、Navicat、MySQL Workbench、SQL Server Management Studio 都可以。
- 一个测试库：可以用
test库，也可以新建demo_sql_comment库，避免影响生产环境。 - 如果只想快速看效果，不装数据库也能用在线 SQL 模拟环境或数据库官方沙箱，但不同平台的在线环境能力差异较大，建议本地验证更可靠。
以 MySQL 为例，准备测试库的命令大致如下。
CREATE DATABASE IF NOT EXISTS demo_sql_comment DEFAULT CHARSET utf8mb4; USE demo_sql_comment; CREATE TABLE orders ( id INT PRIMARY KEY AUTO_INCREMENT, user_id INT NOT NULL, amount DECIMAL(10, 2) NOT NULL, order_date DATETIME NOT NULL ); INSERT INTO orders (user_id, amount, order_date) VALUES (1, 199.00, '2025-01-01 10:00:00'), (2, 299.00, '2025-01-02 11:30:00'), (1, 89.00, '2025-01-03 09:20:00');如果你用的是 PostgreSQL，建表语句差别很小；用 SQL Server 时，把AUTO_INCREMENT换成IDENTITY(1,1)即可。这里的重点不是建表，是环境能正常执行多语句脚本。
检查环境是否就绪，可以用下面这条作为“验证探针”。
-- 注释环境自检 SELECT 1 AS check_result;能返回一列check_result且值为 1，说明客户端连接、数据库权限和基本执行链路都正常。
4. SQL 注释语法与标准详解
这一部分把注释语法掰开讲，重点不是背语法，而是理解注释在语句解析中的位置。
4.1 行注释--
标准 SQL 中，--表示行注释，一直注释到当前行末尾。标准语法要求--后面紧跟一个空格，实际是空格、制表符或换行等控制字符。这个细节在不同数据库里表现不一致，最稳妥的写法就是固定写成-- 注释内容。
-- 查询用户数量 SELECT COUNT(*) FROM users;--注释可以放在语句中间，但从--开始到行尾的内容都会失效。下面的例子中，AND order_date >= '2025-01-01'没有真正生效。
SELECT * FROM orders WHERE user_id = 1 -- AND order_date >= '2025-01-01'实际执行时会发现返回结果包含所有订单，而不是只包含 2025 年之后的订单。这个行为在排错时很实用：临时注释掉一个条件，对比结果差异，能很快定位条件问题。
4.2 块注释/* */
块注释以/*开始，以*/结束，可以跨越多行。适合写在复杂查询的头部，说明整段逻辑。
/* 查询支付金额排名前 10 的用户 逻辑说明： 1. 从 payments 表按 user_id 聚合金额 2. 按总金额降序排序 3. 保留前 10 行 */ SELECT user_id, SUM(amount) AS total_amount FROM payments GROUP BY user_id ORDER BY total_amount DESC LIMIT 10;块注释有一个容易忽略的行为：它会把注释范围内的一切都当成注释，包括分号和 SQL 关键字。如果某段代码被大块注释覆盖，调试时去掉/* */时才恢复执行。
对于嵌套块注释，不同数据库差异较大。PostgreSQL 支持嵌套，MySQL 对嵌套处理则没有那么宽容。跨数据库使用时，避免在块注释里再嵌套/* */，否则容易出现“注释提前结束”或语法报错。
4.3 MySQL 专属行注释#
MySQL 和 MariaDB 支持#作为行注释符号，这一语法相当于是 MySQL 的方言。
# 这是 MySQL 专属行注释 SELECT COUNT(*) FROM orders;在 MySQL 客户端里这段代码可以正常执行，但放到 SQL Server 或 Oracle 里可能直接报错。工程上，如果你的脚本可能跨数据库迁移，尽量不用#，统一使用-- 注释或/* */，减少迁移成本。
4.4 MySQL 可执行注释/*! */
MySQL 有一种特殊注释，写法是/*! ... */。普通数据库会把/*!之后的内容都当注释忽略，但 MySQL 会解析并执行里面的语句。这种语法常用于版本条件控制和导出工具自动生成的脚本。
看一个常见示例：
/*!40101 SET NAMES utf8mb4 */;这条语句在 MySQL 客户端执行时，等价于执行SET NAMES utf8mb4；在 SQL Server 里执行时，则整行被当成注释忽略。这种特性看起来方便，但也容易踩坑，尤其是把 MySQL 导出的 SQL 文件放到其他数据库执行时，可能被静默跳过部分设置，导致字符集或事务行为不一致。
可执行注释还可以带版本号，例如/*!50000 */表示只有 MySQL 5.0.0 及以上版本才执行。这类语法不建议手写，也不建议在业务脚本里主动使用，等你遇到工具自动生成的备份文件时，知道它的含义就够了。
5. SQL 注释在实际操作中的用法
知道语法后，真正重要的是在什么时候写、怎么写、写在哪里。
5.1 单条查询上的注释
单个查询的注释，重点是标注“这段 SQL 为什么这么写”。尤其是指标口径、时间范围、业务状态判断，这些信息代码里全部看不出来。
-- 统计 2025 年 1 月成功支付的订单总额 SELECT DATE(order_date) AS pay_day, SUM(amount) AS total_amount FROM orders WHERE status = 'PAID' AND order_date >= '2025-01-01' AND order_date < '2025-02-01' GROUP BY DATE(order_date);这里把“成功支付”这个业务状态用注释单独写出来，等下一个人接手时，不会误删status = 'PAID'这个条件。
5.2 DDL 与建表脚本中的注释
建表时除了 SQL 注释，还可以使用数据库提供的 COMMENT 元数据能力。MySQL 用COMMENT '...'，SQL Server 用sp_addextendedproperty，PostgreSQL 用COMMENT ON语句。
在 MySQL 里，字段注释可以直接写在建表语句中。
CREATE TABLE users ( id BIGINT PRIMARY KEY COMMENT '用户 ID，自增主键', username VARCHAR(50) NOT NULL COMMENT '登录用户名，全局唯一', email VARCHAR(100) COMMENT '用户邮箱，允许为空', created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间，默认当前时间' ) COMMENT='用户基础信息表';字段注释有一个实际作用：数据字典工具和 BI 元数据采集通常能直接读到 COMMENT，省掉人工维护字典文档的工作。这与--注释不同，--注释在客户端执行后不会保存到数据库元数据里，COMMENT 则会被持久化。
PostgreSQL 里面注释是独立的系统函数。
COMMENT ON TABLE users IS '用户基础信息表'; COMMENT ON COLUMN users.username IS '登录用户名，全局唯一';这里要区分“SQL 脚本注释”和“数据库元数据注释”，两者解决的问题不同。脚本注释服务于代码维护，元数据注释服务于数据字典和后续数据治理。
5.3 调试时用注释快速停用语句
多步骤脚本中，最常见的使用场景是临时把某一条 UPDATE 或 DELETE 注释掉，观察结果。
BEGIN; -- 停用下面的清理语句，排查线上数据异常 -- DELETE FROM orders WHERE order_date < '2024-01-01'; UPDATE orders SET status = 'CHECKED' WHERE id = 1024; COMMIT;这样做比逐行删除更安全，因为注释恢复起来只要删掉--，而删除语句可能需要重新从备份里找。团队协作时，注释掉的代码还带有历史上下文，不会立刻丢失“这里原本处理了什么逻辑”。
5.4 存储过程与视图中的注释
存储过程和视图会长期保存在数据库里，维护者可能换了一拨又一拨，注释的重要性在这里更明显。
CREATE OR REPLACE VIEW v_user_order_stats AS /* 用户订单统计视图 口径说明： 按用户展示订单数和支付总金额 只统计状态为 PAID 的订单 */ SELECT user_id, COUNT(*) AS order_count, SUM(amount) AS total_amount FROM orders WHERE status = 'PAID' GROUP BY user_id;视图定义中的注释会被数据库系统保留，也不需要额外文档。但要注意，修改视图时如果用了CREATE OR REPLACE，一定要把注释同步维护在最新版本里，否则旧注释会误导后面读视图的人。
6. 批量任务与脚本维护中的注释
批量 SQL 脚本比单条查询更依赖注释。脚本一旦超过几十行，没有注释的话，后续排查会非常痛苦。
6.1 脚本头部版本注释
批量脚本的第一个注释块，通常写脚本名称、用途、适用数据库、作者、修改日期、变更内容。
/* ===================================================== script : daily_cleanup.sql purpose : 清理过期临时订单数据 database : MySQL 8.x author : dev_team last_mod : 2025-06-01 change log: 2025-06-01 新增归档逻辑 2025-05-20 修改保留天数从 30 天调整为 90 天 ===================================================== */这个头部注释不只是给别人看的，也是给自己看的。三个月后重新读这个文件时，change log 能直接告诉你为什么要做这次改动。
6.2 分步骤注释
批量脚本通常包含多个阶段：备份、清理、聚合、归档。每一阶段前加一行说明，能显著降低误操作概率。
BEGIN; -- 阶段 1：备份要清理的数据到归档表 INSERT INTO orders_archive SELECT * FROM orders WHERE order_date < '2024-01-01'; -- 阶段 2：删除主表中的归档数据 DELETE FROM orders WHERE order_date < '2024-01-01'; -- 阶段 3：更新汇总表 UPDATE daily_stats SET clean_status = 'DONE' WHERE clean_date = CURRENT_DATE; COMMIT;如果中途发生错误，通过注释标记的阶段号和倒序执行日志，可以快速定位到底失败在第几步。
6.3 多语句文件的分隔与批量执行
批量 SQL 文件通常以分号分隔多条语句。注释的位置如果放错，可能导致一部分语句被意外注释掉。例如下例中，注释写到分号之后，会导致下一条语句的头部失效。
-- 错误示范 SELECT 1; -- 这是注释，不会影响 SELECT 2 吗？ SELECT 2;把注释放在语句之间是安全的。更要注意的是，在 MySQL 存储过程或触发器脚本里，DELIMITER会改变分隔符逻辑，注释与DELIMITER的相对位置也可能影响解析。遇到这类场景，建议先在小脚本里验证，再放到生产任务。
6.4 批量执行中的条件开关
有时需要批量脚本支持“参数化开关”。比如开发环境执行全部步骤，生产环境只执行部分步骤。没有复杂调度系统时，很多人用注释来作为开关。
-- 生产环境开启归档 SET @do_archive = 1; -- 开发环境调试时，手动改为 0 -- SET @do_archive = 0; SELECT IF(@do_archive = 1, '执行归档', '跳过归档') AS next_action;这种注释调度方式简单直接，但只适合人工操作的脚本。自动化调度平台应该用真实任务参数，而不是依赖注释来切换逻辑。
7. 接口 API 与编程调用中的 SQL 注释
后端的 SQL 注释不仅存在于数据库文件里，也存在于应用代码、数据管道和自动化任务中。这里给出一套通用调用示例，具体参数需要根据你使用的数据库驱动调整。
7.1 Python + mysql-connector 执行带注释 SQL
先安装驱动：
pip install mysql-connector-python然后执行带注释的查询：
import mysql.connector conn = mysql.connector.connect( host="127.0.0.1", port=3306, user="your_user", password="your_password", database="demo_sql_comment" ) cursor = conn.cursor() sql = """ -- 查询最近 7 天的支付订单 SELECT order_id, amount, order_date FROM orders WHERE status = 'PAID' AND order_date >= NOW() - INTERVAL 7 DAY; """ cursor.execute(sql) for row in cursor.fetchall(): print(row) cursor.close() conn.close()执行结果不受注释影响，注释只是帮助维护代码。这里的核心是把 SQL 作为独立文本块传递给驱动，参数绑定要单独处理。
7.2 SQLAlchemy 中的注释与 text()
使用 SQLAlchemy 时，推荐用text()或自定义编译注释来组织复杂 SQL。text()可以直接嵌入注释。
from sqlalchemy import create_engine, text engine = create_engine("mysql+mysqlconnector://user:password@127.0.0.1:3306/demo_sql_comment") with engine.connect() as conn: sql = text(""" /* 查询用户订单统计 */ SELECT user_id, COUNT(*) AS order_count FROM orders WHERE status = 'PAID' GROUP BY user_id """) result = conn.execute(sql) for row in result: print(row)注意，Python 字符串里的#会被当成注释吗？不会，Python 的注释只在.py文件解析时生效，字符串内容里的#只是普通字符。SQL 风格的注释则依据目标数据库的规则解析。
7.3 命令行批量导入带注释的 SQL 文件
用 mysql 命令行导入整个 SQL 文件时，注释会被正确识别和忽略。
mysql -u your_user -p demo_sql_comment < ./scripts/init_orders.sql这个命令会把init_orders.sql文件中的所有 SQL 语句按顺序执行，文件中的--、/* */注释都不会影响执行结果。批量自动化脚本里，用命令行导入比手动复制更可控。
这里要说明一下，上面给出的连接参数、数据库驱动名称都是常见实现方式，不同版本的驱动参数会略有差异，实际使用时以官方文档为准。
8. 常见问题与排查方法
SQL 注释本身不复杂，但实际使用中会遇到很多“看起来正常却报错”的情况。下面是高频问题的排查表。
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
--注释后的语句没有生效 | --后缺少空格，部分数据库不识别为注释 | 查看当前行的完整字符，确认是否有空格 | 统一改成-- 注释格式 |
| 块注释提前结束，后续 SQL 报错 | 注释内容里包含*/ | 搜索注释中的*/字符 | 改写注释内容，或拆成多行注释 |
| 注释中的中文乱码 | 客户端或文件字符集不一致 | 查看连接字符集、文件编码 | 使用 UTF-8，并确认SET NAMES utf8mb4 |
| 在 PostgreSQL 能用，在 MySQL 里报错 | 使用了#或/*! */等扩展语法 | 对比两库语法 | 跨库脚本统一用--和/* */ |
| 导入 SQL 文件时某段语句被跳过 | 文件中包含 MySQL 可执行注释/*! */ | 检查文件中的可执行注释段 | 确认目标数据库是否支持该语法 |
| 注释放在字符串里被数据库处理成注释 | SQL 变量或字符串中出现了-- | 检查字符串引号状态 | 调整分隔符或使用参数绑定 |
| 批量事务回滚时注释内容造成误解 | 注释描述的步骤与实际步骤不一致 | 对照脚本头部 change log 和实际代码 | 同步维护注释，确保与执行逻辑一致 |
| 使用可视化工具导出后多出奇怪注释 | 工具自动追加版本或来源注释 | 查看导出设置 | 关闭工具自动注释选项 |
其中最需要注意的是前两行。MySQL 对--注释的空格要求相对严格，建议所有团队统一标准为-- 加空格，规避绝大多数问题。
9. 权限、审计与安全边界：注释与 SQL 注入
注释在数据库安全里也是一个绕不开的话题。很多渗透测试示例里都会出现通过注释截断后续 SQL 语法的行为，比如经典的万能密码绕过。
典型的错误拼接写法是这样的：
username = request.form.get("username") password = request.form.get("password") # 危险写法，不要在生产环境使用 sql = "SELECT * FROM users WHERE username = '" + username + "' AND password = '" + password + "'"当输入的用户名是admin' --时，实际执行的 SQL 可能变成：
SELECT * FROM users WHERE username = 'admin' -- ' AND password = '...'由于--把后面的AND password = '...'全部注释掉，条件只剩下username = 'admin'，如果这条语句被用于登录校验，就可能造成越权。这个例子不是鼓励测试绕过手段，而是说明：任何从外部接收的参数都绝对不能直接拼进 SQL 字符串。
正确的做法是使用参数化查询。以下用通用 Python 风格演示：
import mysql.connector conn = mysql.connector.connect( host="127.0.0.1", user="your_user", password="your_password", database="demo_sql_comment" ) cursor = conn.cursor(prepared=True) sql = """ SELECT * FROM users WHERE username = %s AND password = %s """ cursor.execute(sql, (username, password)) rows = cursor.fetchall()参数化后，即使username里包含--或单引号，数据库也会把它当成普通字符串处理，不会改变 SQL 语义。这是防止 SQL 注入最基础也最有效的手段。
另一个安全边界是 MySQL 的可执行注释/*! */。如果业务代码里主动拼接这类语法，扫描工具会把它标记为可疑行为，也可能被恶意脚本利用。生产环境尽量避免业务代码使用可执行注释，导出和备份工具生成的语句则要充分评估后再执行。
安全合规方面，还有几点需要明确：涉及用户数据的查询，不要通过注释把手机号、身份证号、明文密码等敏感信息写进脚本；数据库账号密码不要出现在注释里；发布日志、慢查询日志、数据备份都会保留注释内容，一旦泄露可能影响系统安全。合规审计更希望看到的是：数据访问有授权、SQL 语句可追溯、参数化查询被普遍使用。
10. 最佳实践与使用建议
SQL 注释的最佳实践不在语法层面，而在工程习惯层面。下面这些建议可以直接放进团队开发规范。
10.1 统一注释格式
推荐全团队统一使用以下格式：
- 单行注释：
-- 注释内容，--后必须带一个空格。 - 多行注释：使用
/* ... */包裹，缩进与代码对齐。 - 不提写
#，除非明确只在 MySQL 单库使用。 - 长脚本头部保留版本和变更历史。
10.2 注释放在语句上方，不放在混乱位置
注释尽量放在语句正上方，说明这一段做什么。放在语句右侧的注释可以用于简短解释，但如果过多会破坏排版。
-- 只统计状态为 PAID 的订单 SELECT COUNT(*) FROM orders WHERE status = 'PAID';10.3 脚本文件头注释模板
建议一个最小可用的文件头模板：
/* 脚本名：daily_summary.sql 用途：生成每日销售汇总 数据库：PostgreSQL 15+ 维护人：数据库组 版本：1.2 修改记录： 1.2 增加毛利率字段 1.1 修复时间区间边界 1.0 初版 */这个模板不仅方便人读，也可以在 CI 脚本中通过文本校验，确保每个 SQL 文件都有版本说明。
10.4 保持注释与代码同步
注释过期比没有注释更危险。修改 SQL 逻辑时，同步修改注释；如果逻辑变化太大，旧注释直接删除，保留变更记录在文件头即可。不要让“这段注释可能不对”成为新维护者接手的心理负担。
10.5 在 IDE 中配置快捷键
DBeaver、Navicat、SSMS 等都支持快捷键注释和取消注释。例如 MySQL Workbench 的Ctrl+/，DBeaver 的Ctrl+/或Ctrl+Shift+/，SSMS 的Ctrl+K, Ctrl+C注释、Ctrl+K, Ctrl+U取消注释。建议提前配置好，调试大脚本时能节省大量时间。
11. 总结与下一步
SQL 注释看着简单，真正写对、写到位并不容易。它不改变 SQL 执行结果，但决定了三个月后你和你的队友还能不能快速看懂这段脚本。跨数据库时，--、/* */、#、/*! */的差异更是非常容易踩坑。最核心的做法是：统一用-- 加空格和/* */，避免依赖 MySQL 专属语法，不要在生产代码里拼接可执行注释。
接下来建议你直接做三件事。第一，把你手边最长的一条查询脚本用注释标清每一段，至少加上“用途”和“口径说明”。第二，在一台装有 MySQL 和一台装有 PostgreSQL 的环境里分别测试--、/* */、#和/*! */的实际行为，感受一下差异。第三，在团队 SQL 规范里增加“注释格式”和“安全边界”两条，并把常见问题排查表放进维护文档。做完这些，再看数据库脚本的长期维护成本，你会感觉到明显差别。
