SQL 注释

你可以使用 .comment() 方法为任何查询添加自定义标签。这些标签会以 sqlcommenter 格式的注释附加在每个查询末尾，帮助你为查询跟踪、调试和数据库流量控制附加元数据。

.comment() 方法可用于 select、insert、update 和 delete 查询。

你可以传入一个原始字符串作为注释：

db.select().from(users).comment("my_first_tag");

select `id`, `name` from `users` /*my_first_tag*/

db.select().from(users).comment("key='val'");

select `id`, `name` from `users` /*key='val'*/

你可以传入一个包含键值对的对象，用于结构化标签：

db.select().from(users).comment({ priority: 'high', category: 'analytics' });

select `id`, `name` from `users` /*priority='high',category='analytics'*/

db.select().from(users).comment({ trace: true, route: '/api/users', version: 2 });

select `id`, `name` from `users` /*route='%2Fapi%2Fusers',trace='true',version='2'*/

db.insert(users).values({ name: 'Dan' }).comment({ operation: 'seed' });

insert into `users` (`name`) values ('Dan') /*operation='seed'*/

db.update(users).set({ name: 'Dan' }).where(eq(users.id, 1)).comment({ operation: 'update' });

update `users` set `name` = 'Dan' where `users`.`id` = 1 /*operation='update'*/

db.delete(users).where(eq(users.id, 1)).comment({ operation: 'cleanup' });

delete from `users` where `users`.`id` = 1 /*operation='cleanup'*/

在语句已经准备好之后，你不能再使用 .comment()。预编译语句只会编译一次 SQL 查询并在多次执行中重复使用，因此查询字符串会在准备时固定下来，之后无法再修改——包括追加注释：

// 不能使用
const p = db.select().from(users).prepare();
// ❌
p.comment({ key: 'val' }).execute();

相反，请在准备语句之前添加注释：

// ✅
db.select().from(users).comment({ key: "val" }).prepare();