请注意，sql<T> 不执行任何运行时映射。您使用 sql<T> 定义的类型纯粹是 Drizzle 的一个辅助工具。重要的是要明白，没有可行的方法可以动态确定确切的类型，因为 SQL 查询可以高度灵活和可定制。
神奇的 sql 运算符 🪄
在使用 ORM 库时，有时会遇到难以使用其提供的 ORM 语法编写特定查询的情况。在这种情况下，您可以选择使用原始查询，即将查询构建为原始字符串。然而，原始查询通常缺乏类型安全和查询参数化的优势。
为了解决这个问题，许多库引入了 sql 模板的概念。该模板允许您编写更具类型安全和参数化的查询，从而提高代码的整体安全性和灵活性。Drizzle 作为一款强大的 ORM 库，也支持 sql 模板。
借助 Drizzle 的 sql 模板，您可以在查询构建方面更进一步。如果您在使用库的查询构建器编写整个查询时遇到困难，您可以在 Drizzle 查询的特定部分选择性地使用 sql 模板。这种灵活性使您可以在部分 SELECT 语句、WHERE 子句、ORDER BY 子句、HAVING 子句、GROUP BY 子句，甚至在关系查询构建器中使用 sql 模板。
通过利用 Drizzle 中 sql 模板的功能，您可以在保持类型安全和查询参数化优势的同时，实现所需的查询结构和复杂性。这使您能够在应用程序中创建更健壮、更易于维护的代码。
sql“ template
在其他 ORM 中，您可能遇到的最常见用法之一是能够直接将 sql 查询用于原始查询。
import { sql } from 'drizzle-orm'
const id = 69;
await db.execute(sql`select * from ${usersTable} where ${usersTable.id} = ${id}`)它将生成当前查询
select * from "users" where "users"."id" = $1; --> [69]提供给 sql 参数的任何表和列都会自动映射到其相应的 SQL 语法，其中表名会进行转义，并且转义后的表名会附加到列名中。
此外，任何动态参数（例如 ${id}）都将映射到 `$1` 占位符，并且相应的值将移至一个单独传递给数据库的值数组中。
这种方法有效防止了任何潜在的 SQL 注入漏洞。
sql<T>
您可以在 Drizzle 中定义一个自定义类型，用于字段需要特定类型而非 unknown 的地方。
此功能在部分 SELECT 查询中特别有用，可确保所选字段的类型一致性。
// without sql<T> type defined
const response: { id: unknown }[] = await db.select({
lowerName: sql`lower(${usersTable.id})`
}).from(usersTable);
// with sql<T> type defined
const response: { id: string }[] = await db.select({
lowerName: sql<string>`lower(${usersTable.id})`
}).from(usersTable);sql``.mapWith()
在需要对从数据库驱动程序传递到 Drizzle 的值进行运行时映射的情况下，可以使用 .mapWith()。
此函数接受不同的值，这些值将在运行时映射响应。
只要 mapWith 内部的接口与 Column 实现的接口相同，您就可以复制特定的列映射策略。
const usersTable = pgTable('users', {
id: serial('id').primaryKey(),
name: text('name').notNull(),
});
// at runtime this values will be mapped same as `text` column is mapped in drizzle
sql`...`.mapWith(usersTable.name);您还可以为 DriverValueDecoder 接口传入自己的实现。
sql``.mapWith({
mapFromDriverValue: (value: any) => {
const mappedValue = value;
// mapping you want to apply
return mappedValue;
},
});
// or
sql``.mapWith(Number);sql``.as<T>()
在不同情况下，有时很难确定如何命名要使用的自定义字段。您可能会遇到需要为将要选择的字段显式指定别名的情况。这在处理复杂查询时特别有用。
为了解决这些情况，我们引入了一个有用的 .as('alias_name') 辅助函数，它允许您显式定义别名。通过利用此功能，您可以为字段提供清晰且有意义的名称，使您的查询更直观、更易读。
sql`lower(usersTable.name)`.as('lower_name')... "usersTable"."name" as lower_name ...sql.raw()
在某些情况下，您可能不需要从输入创建参数化值，或将表/列映射到转义后的值。相反，您可能只是想按原样生成查询。对于这种情况，我们提供了 sql.raw() 函数。
sql.raw() 函数允许您在查询中包含原始 SQL 语句，而无需任何额外的处理或转义。当您有预先构建的 SQL 语句，或者需要将复杂或动态的 SQL 代码直接合并到查询中时，这会非常有用。
sql.raw(`select * from users where id = ${12}`);
// vs
sql`select * from users where id = ${12}`;select * from users where id = 12;
--> vs
select * from users where id = $1; --> [12]您还可以在 sql 函数内部使用 sql.raw()，这使您能够包含任何原始字符串，而无需通过主 sql 模板函数对其进行转义。
通过在 sql 函数内部使用 sql.raw()，您可以将未转义的原始字符串直接包含在查询中。当您有特定的 SQL 代码或表达式不应受模板函数自动转义或修改影响时，这会特别有用。
sql`select * from ${usersTable} where id = ${12}`;
// vs
sql`select * from ${usersTable} where id = ${sql.raw(12)}`;select * from "users" where id = $1; --> [12]
--> vs
select * from "users" where id = 12;sql.fromList()
sql 模板生成 SQL 块，这些 SQL 块是 SQL 部分的数组，它们将在 Drizzle 中将 SQL 应用于数据库或查询后，连接成查询和参数。
在某些情况下，您可能需要使用自定义业务逻辑将这些块聚合成一个数组，然后将它们连接成一个可以传递给数据库或查询的单个 SQL 语句。对于这种情况，`fromList` 函数会非常有用。
fromList 函数允许您将多个 SQL 块组合成一个 SQL 语句。您可以使用它根据您的特定要求聚合和连接各个 SQL 部分，然后获得一个可以执行的统一 SQL 查询。
const sqlChunks: SQL[] = [];
sqlChunks.push(sql`select * from users`);
// some logic
sqlChunks.push(sql` where `);
// some logic
for (let i = 0; i < 5; i++) {
sqlChunks.push(sql`id = ${i}`);
if (i === 4) continue;
sqlChunks.push(sql` or `);
}
const finalSql: SQL = sql.fromList(sqlChunks)select * from users where id = $1 or id = $2 or id = $3 or id = $4 or id = $5; --> [0, 1, 2, 3, 4]sql.join()
确实，sql.join 函数与 fromList 辅助函数目的相似。然而，在处理 SQL 块之间的空格或指定自定义分隔符来连接 SQL 块时，它提供了额外的灵活性。
使用 sql.join，您可以使用指定的分隔符将 SQL 块连接在一起。此分隔符可以是您希望插入在块之间的任何字符串或字符。
当您对 SQL 块的格式或定界有特定要求时，这尤其有用。通过指定自定义分隔符，您可以在最终的 SQL 查询中实现所需的结构和格式。
const sqlChunks: SQL[] = [];
sqlChunks.push(sql`select * from users`);
// some logic
sqlChunks.push(sql`where`);
// some logic
for (let i = 0; i < 5; i++) {
sqlChunks.push(sql`id = ${i}`);
if (i === 4) continue;
sqlChunks.push(sql`or`);
}
const finalSql: SQL = sql.join(sqlChunks, sql.raw(' '));select * from users where id = $1 or id = $2 or id = $3 or id = $4 or id = $5; --> [0, 1, 2, 3, 4]sql.append()
如果您已经使用 sql 模板生成了 SQL，您可以通过使用 append 函数直接向生成的 SQL 添加新块，从而实现与 fromList 相同的行为。
通过使用 append 函数，您可以将额外的 SQL 块动态添加到现有 SQL 字符串中，从而有效地将它们连接在一起。这使您能够整合自定义逻辑或业务规则，以将这些块聚合到最终的 SQL 查询中。
const finalSql = sql`select * from users`;
// some logic
finalSql.append(sql` where `);
// some logic
for (let i = 0; i < 5; i++) {
finalSql.append(sql`id = ${i}`);
if (i === 4) continue;
finalSql.append(sql` or `);
}select * from users where id = $1 or id = $2 or id = $3 or id = $4 or id = $5; --> [0, 1, 2, 3, 4]sql.empty()
通过使用 sql.empty()，您可以从一个空白的 SQL 对象开始，然后根据需要动态地向其追加 SQL 块。这使您能够以增量方式构建 SQL 查询，应用自定义逻辑或条件来确定每个块的内容。
一旦您使用 sql.empty() 初始化了 SQL 对象，您就可以充分利用 sql 模板的全部功能，例如参数化、组合和转义。这使您能够以灵活且受控的方式构建 SQL 查询，并使其适应您的特定要求。
const finalSql = sql.empty();
// some logic
finalSql.append(sql`select * from users`);
// some logic
finalSql.append(sql` where `);
// some logic
for (let i = 0; i < 5; i++) {
finalSql.append(sql`id = ${i}`);
if (i === 4) continue;
finalSql.append(sql` or `);
}select * from users where id = $1 or id = $2 or id = $3 or id = $4 or id = $5; --> [0, 1, 2, 3, 4]将 sql 转换为字符串和参数
在所有前面的示例中，您都看到了 TypeScript 中 SQL 模板语法的使用以及生成的 SQL 输出。
如果您需要获取从 SQL 模板生成的查询字符串和相应的参数，则必须指定您打算为其生成查询的数据库方言。不同的数据库在参数化和转义方面有不同的语法，因此选择合适的方言至关重要。
选择方言后，您可以使用相应实现的函数将 SQL 模板转换为所需的查询字符串和参数格式。这确保了与您正在使用的特定数据库系统的兼容性。
PostgreSQL
MySQL
SQLite
import { PgDialect } from 'drizzle-orm/pg-core';
const pgDialect = new PgDialect();
pgDialect.sqlToQuery(sql`select * from ${usersTable} where ${usersTable.id} = ${12}`);select * from "users" where "users"."id" = $1; --> [ 12 ]sql 选择
您也可以在部分 SELECT 查询中使用 sql 功能。部分 SELECT 查询允许您从表中检索特定字段或列，而不是获取整个行。
有关部分 SELECT 查询的更多详细信息，请参阅 核心 API 文档。
从表中选择不同的自定义字段
在这里，您可以看到 sql<T>、sql``.mapWith()、sql``.as<T>() 的用法。
import { sql } from 'drizzle-orm'
import { usersTable } from 'schema'
await db.select({
id: usersTable.id,
lowerName: sql<string>`lower(${usersTable.name})`,
aliasedName: sql<string>`lower(${usersTable.name})`.as('aliased_column'),
count: sql<number>`count(*)`.mapWith(Number)
}).from(usersTable)select `id`, lower(`name`), lower(`name`) as `aliased_column`, count(*) from `users`;sql 在 where 子句中
确实，Drizzle 提供了一组可在 sql 模板中使用的可用表达式。然而，数据库通常拥有更广泛的可用表达式，包括通过扩展或其他方式提供的表达式。
为确保灵活性并使您能够使用 Drizzle 不原生支持的任何表达式，您可以自由地直接使用 sql 函数编写 SQL 模板。这使您能够利用 SQL 的全部功能，并整合任何特定于目标数据库的表达式或功能。
通过使用 sql 模板，您不仅限于 Drizzle 中预定义的表达式。相反，您可以表达复杂的查询并整合底层数据库系统提供的任何受支持的表达式。
通过 id 进行筛选，但使用 sql
import { sql } from 'drizzle-orm'
import { usersTable } from 'schema'
const id = 77
await db.select()
.from(usersTable)
.where(sql`${usersTable.id} = ${id}`)select * from "users" where "users"."id" = $1; --> [ 77 ]高级全文搜索 where 语句
import { sql } from 'drizzle-orm'
import { usersTable } from 'schema'
const searchParam = "Ale"
await db.select()
.from(usersTable)
.where(sql`to_tsvector('simple', ${usersTable.name}) @@ to_tsquery('simple', ${searchParam})`)select * from "users" where to_tsvector('simple', "users"."name") @@ to_tsquery('simple', '$1'); --> [ "Ale" ]sql 在 orderBy 子句中
当您需要 Drizzle 中不具备的特定排序功能，但又不想使用原始 SQL 时，sql 模板确实可以在 ORDER BY 子句中使用。
import { sql } from 'drizzle-orm'
import { usersTable } from 'schema'
await db.select().from(usersTable).orderBy(sql`${usersTable.id} desc nulls first`)select * from "users" order by "users"."id" desc nulls first;sql 在 having 和 groupBy 子句中
当您需要 Drizzle 中不具备的特定排序功能，但又不想使用原始 SQL 时，sql 模板确实可以在 HAVING 和 GROUP BY 子句中使用。
import { sql } from 'drizzle-orm'
import { usersTable } from 'schema'
await db.select({
projectId: usersTable.projectId,
count: sql<number>`count(${usersTable.id})`.mapWith(Number)
}).from(usersTable)
.groupBy(sql`${usersTable.projectId}`)
.having(sql`count(${usersTable.id}) > 300`)select "project_id", count("users"."id") from users group by "users"."project_id" having count("users"."id") > 300;