视图(Views)
用 pgView、mysqlView、sqliteView 声明视图,掌握 PostgreSQL 物化视图的刷新与既有视图的迁移行为。
视图把一段查询固化为数据库对象,之后可以像表一样查询它。Drizzle 三个方言都支持视图声明:pgView、mysqlView、sqliteView,PostgreSQL 额外支持物化视图 pgMaterializedView。视图定义写在 schema 文件里,drizzle-kit 会生成对应的 CREATE VIEW 迁移。
用 query builder 声明视图
最常用的方式是 .as((qb) => ...):列结构会自动从查询推导,无需手写。
import { eq, sql } from 'drizzle-orm';
import { integer, pgTable, pgView, serial, text } from 'drizzle-orm/pg-core';
export const users = pgTable('users', {
id: serial('id').primaryKey(),
name: text('name').notNull(),
email: text('email').notNull(),
cityId: integer('city_id'),
});
// 列结构自动推导
export const usersView = pgView('users_view').as((qb) =>
qb.select().from(users),
);
// 也可以只暴露部分列、加过滤条件
export const activeUsers = pgView('active_users').as((qb) =>
qb.select({ id: users.id, name: users.name })
.from(users)
.where(sql`${users.cityId} is not null`),
); 三个方言都可以改用独立的 QueryBuilder(从各自的 core 包导入),效果完全相同:
import { QueryBuilder, pgView } from 'drizzle-orm/pg-core';
const qb = new QueryBuilder();
export const usersView = pgView('users_view').as(qb.select().from(users)); 查询视图
视图声明导出后,用法与表一致,支持 where、join、分页等:
import { eq } from 'drizzle-orm';
const result = await db.select().from(activeUsers).where(eq(activeUsers.id, 1)); 视图定义里的参数会被内联
.as() 中的查询在生成 DDL 时会把参数内联为字面量(如 where city_id = 1),而不是 $1 占位符——视图定义必须是确定的 SQL。查询视图本身时参数仍正常走占位符。
用原生 SQL 声明视图
query builder 覆盖不了的语法(窗口函数细节、方言特有表达式等)可以直接用 sql,但此时必须显式声明列结构:
import { sql } from 'drizzle-orm';
import { integer, pgView, serial, text } from 'drizzle-orm/pg-core';
export const newYorkers = pgView('new_yorkers', {
id: serial('id').primaryKey(),
name: text('name').notNull(),
cityId: integer('city_id').notNull(),
}).as(sql`select * from ${users} where ${users.cityId} = 1`); PostgreSQL 物化视图
物化视图把查询结果物理存储下来,查询快但数据是快照,需要手动刷新:
import { pgMaterializedView, uniqueIndex } from 'drizzle-orm/pg-core';
export const cityStats = pgMaterializedView('city_stats').as((qb) =>
qb.select({ cityId: users.cityId, count: sql<number>`count(*)::int` })
.from(users)
.groupBy(users.cityId),
); // 用 qb 定义时列结构自动推导 刷新数据:
await db.refreshMaterializedView(cityStats); // 普通刷新,期间阻塞读
await db.refreshMaterializedView(cityStats).concurrently(); // 并发刷新,不阻塞读
await db.refreshMaterializedView(cityStats).withNoData(); // 清空数据(REFRESH ... WITH NO DATA) concurrently() 要求物化视图上至少有一个唯一索引,可以在第三个参数的回调里声明(写法与表一致):
export const cityStats = pgMaterializedView(
'city_stats',
{ cityId: integer('city_id'), count: integer('count') },
(view) => [uniqueIndex('city_stats_city_idx').on(view.cityId)],
).as(sql`select city_id, count(*)::int as count from users group by city_id`); 其他要点:
- 声明期的
.withNoData():创建时不填充数据(WITH NO DATA),首次查询前必须先 refresh,否则报错。 .using('heap')、.with({ fillfactor: 90 })、.tablespace('...')可控制存储参数。- 普通
pgView也支持.with({ checkOption: 'cascaded', securityBarrier: true, securityInvoker: true });securityInvoker: true(PG 15+)让视图以查询者权限执行,是通过视图实施 RLS 的关键。
既有视图:.existing()
如果视图已经存在于数据库中(例如 DBA 维护、或只读接入的库),用 .existing() 声明。drizzle-kit 会忽略它,不生成 CREATE VIEW,你只获得类型安全的查询能力:
export const trimmedUsers = pgView('trimmed_users', {
id: integer('id'),
name: text('name'),
}).existing(); // 必须显式声明列结构 MySQL 的 mysqlView(...).existing() 与 SQLite 的 sqliteView(...).existing() 用法相同。
迁移行为与陷阱
视图变更是 DROP + CREATE
视图定义无法原地 ALTER。修改 .as() 里的查询后,drizzle-kit generate 会生成 DROP VIEW + CREATE VIEW。依赖该视图的其他视图会导致 DROP 失败,需要在自定义迁移里手动处理依赖顺序(或谨慎使用 CASCADE)。
- 视图引用的底层表列改名/删除时,kit 不会自动重建视图,迁移可能执行失败或视图悄然失效,务必检查生成的 SQL。
.existing()视图完全不参与迁移:改了列声明只影响 TypeScript 类型,不会碰数据库;列声明与真实视图不一致时错误只会在运行时暴露。- 物化视图的刷新不在迁移职责内,通常由定时任务或写入后的钩子触发。
drizzle-kit push对视图同样采用重建策略,生产环境建议走 generate + 审查。