在 Encore.ts 中使用 Knex.js数据库连接、SQL 迁移与查询构建实战指南【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore本文介绍如何在 Encore.tsEncore 的 TypeScript 运行时项目中集成 Knex.js——Node.js 生态中最流行的 SQL 查询构建器之一。文章以SQLDatabase资源为切入点完整讲解如何创建数据库实例、将连接字符串交给 Knex.js 初始化查询构建器、用纯 SQL 迁移文件维护表结构以及 Encore 自动应用迁移的底层机制。读完本文你将掌握在 Encore.ts 服务中使用 Knex.js 完成增删改查、配合 Encore 迁移体系管理 schema 的完整实战方案。集成模型Encore 管数据库Knex.js 管查询Encore 将 SQL 数据库视为逻辑资源由平台负责供给、连接与迁移而 ORM / 查询构建器只负责消费。Encore 官方对 ORM 兼容性的判定非常简单只要你的 ORM 能通过标准 SQL 驱动连接数据库就能与 Encore 一起使用见 ORM 集成总览。Knex.js 正是这一类工具它本身不管理连接只接收一个连接字符串connection string。Encore 的SQLDatabase实例恰好对外暴露了这个字符串调用new SQLDatabase(name, { migrations: ./migrations })声明一个逻辑数据库资源并指定迁移目录通过SiteDB.connectionString读取该数据库的运行时连接信息将连接字符串传给knex({ client: pg, connection: ... })即可获得一个类型安全的查询构建器。从源码看connectionString是一个实时读取的 getter直接委托给运行时层的连接解析实现// runtimes/js/encore.dev/storage/sqldb/database.ts get connectionString(): string { return this.impl.connString(); }也就是说无论在本地开发Docker 中的 PostgreSQL还是云端环境Encore 都会按环境注入正确的连接配置Knex.js 拿到的始终是当前环境下可用的连接字符串无需手工管理主机、端口、账号密码。第一步创建数据库并配置 Knex.js 连接在服务文件site.ts中初始化SQLDatabase并配置 Knex.js完整代码如下// site.ts import { SQLDatabase } from encore.dev/storage/sqldb; import knex from knex; // Create SQLDatabase instance with migrations configuration const SiteDB new SQLDatabase(siteDB, { migrations: ./migrations, }); // Initialize Knex with the database connection string const orm knex({ client: pg, connection: SiteDB.connectionString, }); // Define the Site interface export interface Site { id: number; url: string; } // Query builder for the site table const Sites () ormSite(site); // Example queries // Query all sites await Sites().select(); // Query a site by id await Sites().where(id, id).first(); // Insert a new site await Sites().insert({ url: params.url });配置要点说明client: pgKnex.js 通过pgnode-postgres驱动连接 Encore 提供的 PostgreSQL 数据库。使用前需在项目中安装依赖npm install knex pg。SiteDB.connectionString由SQLDatabase动态提供不要硬编码数据库地址。类型化查询构建器ormSite(site)返回针对site表的构建器Site接口中的id、url字段会为链式查询提供 TypeScript 类型提示await Sites().select()返回的正是Site[]形态的数据。顶层变量约束new SQLDatabase(...)必须赋值给模块顶层变量服务初始化阶段执行这是 Encore 静态分析发现基础设施资源的前提在函数内部创建数据库实例不会被识别。关于SQLDatabase的配置项源码中定义了如下接口// runtimes/js/encore.dev/storage/sqldb/database.ts export interface SQLMigrationsConfig { path: string; source?: prisma | drizzle | drizzle/v1; } export interface SQLDatabaseConfig { migrations?: string | SQLMigrationsConfig; }可以看到migrations既可以是简单字符串路径也可以是对象形式。需要特别指出的是source字段仅支持prisma与drizzleKnex.js 不在其中——这正是后文「使用 SQL 迁移文件」的原因所在Knex 生成的是 JavaScript 迁移文件而 Encore 目前只接受 SQL 格式迁移。第二步用 SQL 迁移文件定义表结构Encore目前不支持knex migrate:make生成的 JavaScript 迁移文件因此你需要自行创建并维护 SQL 格式的迁移文件。以创建site表为例迁移文件内容如下-- migrations/1_create_table.up.sql CREATE TABLE site ( id SERIAL PRIMARY KEY, url TEXT NOT NULL UNIQUE );迁移文件的命名规范Encore 对迁移文件有严格的命名要求详见 SQL 数据库文档文件名必须以数字 下划线开头如1_、2_且数字需严格递增用于确定应用顺序文件名必须以.up.sql结尾合法的例子1_first_migration.up.sql、2_second_migration.up.sql、3_migration_name.up.sql为便于编辑器排序也允许使用前导零如0001_migration.up.sql。迁移目录结构迁移文件位于服务内部的migrations目录中/my-app ├── encore.app // 项目根文件 │ └── site // site 服务 ├── migrations // 数据库迁移目录 │ └── 1_create_table.up.sql // 创建 site 表的迁移 ├── site.ts // 服务代码含 SQLDatabase 与 Knex 初始化 └── site.test.ts // 测试文件迁移出错时的处理Encore 在应用迁移失败时会回滚迁移云端部署失败会中止部署并在数据库中通过schema_migrations表记录已应用的迁移版本database# \d schema_migrations Table public.schema_migrations Column | Type | Collation | Nullable | Default ------------------------------------------------ version | bigint | | not null | dirty | boolean | | not null |如果遇到sqldb: unknown database之类的错误常见原因是迁移文件名不符合规范命名或位置有误可检查迁移文件后重新运行encore run。本地数据库状态损坏时可用encore db reset database-name加--all重置全部将数据库删除重建并从头应用所有迁移。第三步迁移的自动应用Knex.js 体系下通常需要手工执行knex migrate:latest来应用迁移而Encore 会在应用运行时自动应用迁移——你无需也不应手动运行任何knex migrate:latest之类的命令。这一机制与 Encore 的数据库管理模型一致本地环境执行encore run时Encore 通过 Docker 自动创建 PostgreSQL 数据库并按其顺序逐个应用*.up.sql迁移需要本地安装并运行 Docker若在应用运行期间新增数据库定义需重启encore run。云端环境部署时 Encore 自动完成数据库供给、迁移与运行时连接注入应用启动后数据库即可直接使用。因此你只需要保证迁移文件命名正确、SQL 合法Encore 会在本地与云端保持一致地完成 schema 演进。这一设计让 Knex.js 只负责「查询」把「schema 生命周期」完全交给 Encore 管理两者各司其职。用 Knex.js 编写业务查询Sites()构建器支持 Knex.js 完整的链式查询 API下面是基于site表的常用写法// 查询全部站点 const allSites: Site[] await Sites().select(); // 按 id 查询单个站点无结果返回 undefined const site await Sites().where(id, id).first(); // 新增站点 await Sites().insert({ url: params.url }); // 更新与删除同样沿用 Knex 语法 await Sites().where(id, id).update({ url: newUrl }); await Sites().where(id, id).delete();结合 Encore 的 SQLDatabase 原生能力需要强调SQLDatabase本身也提供了完整的查询 APIquery、queryRow、queryAll、exec等模板字符串方法见 database.ts因此你可以按场景混用偏好类型化链式查询 → 使用 Knex.js需要写复杂原生 SQL → 直接使用SiteDB.query\... 模板查询参数自动参数化防注入需要事务 → 两种方式都可用Knex 有自身的orm.transaction(...)而SQLDatabase也提供await db.begin()返回实现AsyncDisposable的Transaction对象未显式 commit/rollback 时自动回滚可根据团队习惯选择。与其它 ORM 集成的差异对比Encore 官方文档中还有 Drizzle、Prisma、Sequelize 等集成指南见 ORM 集成总览与 Knex.js 的关键差异在于迁移来源ORM / 工具连接方式迁移文件格式备注Knex.jsknex({ client: pg, connection: SiteDB.connectionString })纯 SQL*.up.sql不支持 Knex 生成的 JS 迁移文件Drizzledrizzle(db.connectionString)SQL由drizzle-kit generate生成migrations.source可设为drizzlePrismaPrismaClient 连接字符串SQLPrisma Migrate 生成migrations.source可设为prismaSequelizenew Sequelize(DB.connectionString)纯 SQL*.up.sql不支持 sequelize-cli 生成的 JS 迁移对于 Knex.js 用户建议的取舍是利用 Knex 的查询构建能力编写业务数据访问层同时用 Encore 的 SQL 迁移体系管理 schema两者互不冲突。如果表结构复杂、对迁移生成有自动化诉求可考虑改用 Drizzle/Prisma它们能自动产出 Encore 可识别的 SQL 迁移。总结在 Encore.ts 中集成 Knex.js 只需要三步new SQLDatabase(...)声明数据库资源 → 用connectionString初始化knex({ client: pg })→ 在migrations目录中维护 SQL 迁移文件。Encore 负责数据库的供给、连接注入与迁移应用Knex.js 专注查询构建这种职责划分让团队既能享受 Knex 的灵活链式查询又能获得 Encore 提供的环境一致性与云端自动化能力。进一步阅读Encore 中数据库资源与迁移的完整说明ORM 与迁移框架集成总览Drizzle ORM 集成指南Sequelize 集成指南SQLDatabase 源码实现【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Encore.ts 中使用 Knex.js：数据库连接、SQL 迁移与查询构建实战指南
在 Encore.ts 中使用 Knex.js数据库连接、SQL 迁移与查询构建实战指南【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore本文介绍如何在 Encore.tsEncore 的 TypeScript 运行时项目中集成 Knex.js——Node.js 生态中最流行的 SQL 查询构建器之一。文章以SQLDatabase资源为切入点完整讲解如何创建数据库实例、将连接字符串交给 Knex.js 初始化查询构建器、用纯 SQL 迁移文件维护表结构以及 Encore 自动应用迁移的底层机制。读完本文你将掌握在 Encore.ts 服务中使用 Knex.js 完成增删改查、配合 Encore 迁移体系管理 schema 的完整实战方案。集成模型Encore 管数据库Knex.js 管查询Encore 将 SQL 数据库视为逻辑资源由平台负责供给、连接与迁移而 ORM / 查询构建器只负责消费。Encore 官方对 ORM 兼容性的判定非常简单只要你的 ORM 能通过标准 SQL 驱动连接数据库就能与 Encore 一起使用见 ORM 集成总览。Knex.js 正是这一类工具它本身不管理连接只接收一个连接字符串connection string。Encore 的SQLDatabase实例恰好对外暴露了这个字符串调用new SQLDatabase(name, { migrations: ./migrations })声明一个逻辑数据库资源并指定迁移目录通过SiteDB.connectionString读取该数据库的运行时连接信息将连接字符串传给knex({ client: pg, connection: ... })即可获得一个类型安全的查询构建器。从源码看connectionString是一个实时读取的 getter直接委托给运行时层的连接解析实现// runtimes/js/encore.dev/storage/sqldb/database.ts get connectionString(): string { return this.impl.connString(); }也就是说无论在本地开发Docker 中的 PostgreSQL还是云端环境Encore 都会按环境注入正确的连接配置Knex.js 拿到的始终是当前环境下可用的连接字符串无需手工管理主机、端口、账号密码。第一步创建数据库并配置 Knex.js 连接在服务文件site.ts中初始化SQLDatabase并配置 Knex.js完整代码如下// site.ts import { SQLDatabase } from encore.dev/storage/sqldb; import knex from knex; // Create SQLDatabase instance with migrations configuration const SiteDB new SQLDatabase(siteDB, { migrations: ./migrations, }); // Initialize Knex with the database connection string const orm knex({ client: pg, connection: SiteDB.connectionString, }); // Define the Site interface export interface Site { id: number; url: string; } // Query builder for the site table const Sites () ormSite(site); // Example queries // Query all sites await Sites().select(); // Query a site by id await Sites().where(id, id).first(); // Insert a new site await Sites().insert({ url: params.url });配置要点说明client: pgKnex.js 通过pgnode-postgres驱动连接 Encore 提供的 PostgreSQL 数据库。使用前需在项目中安装依赖npm install knex pg。SiteDB.connectionString由SQLDatabase动态提供不要硬编码数据库地址。类型化查询构建器ormSite(site)返回针对site表的构建器Site接口中的id、url字段会为链式查询提供 TypeScript 类型提示await Sites().select()返回的正是Site[]形态的数据。顶层变量约束new SQLDatabase(...)必须赋值给模块顶层变量服务初始化阶段执行这是 Encore 静态分析发现基础设施资源的前提在函数内部创建数据库实例不会被识别。关于SQLDatabase的配置项源码中定义了如下接口// runtimes/js/encore.dev/storage/sqldb/database.ts export interface SQLMigrationsConfig { path: string; source?: prisma | drizzle | drizzle/v1; } export interface SQLDatabaseConfig { migrations?: string | SQLMigrationsConfig; }可以看到migrations既可以是简单字符串路径也可以是对象形式。需要特别指出的是source字段仅支持prisma与drizzleKnex.js 不在其中——这正是后文「使用 SQL 迁移文件」的原因所在Knex 生成的是 JavaScript 迁移文件而 Encore 目前只接受 SQL 格式迁移。第二步用 SQL 迁移文件定义表结构Encore目前不支持knex migrate:make生成的 JavaScript 迁移文件因此你需要自行创建并维护 SQL 格式的迁移文件。以创建site表为例迁移文件内容如下-- migrations/1_create_table.up.sql CREATE TABLE site ( id SERIAL PRIMARY KEY, url TEXT NOT NULL UNIQUE );迁移文件的命名规范Encore 对迁移文件有严格的命名要求详见 SQL 数据库文档文件名必须以数字 下划线开头如1_、2_且数字需严格递增用于确定应用顺序文件名必须以.up.sql结尾合法的例子1_first_migration.up.sql、2_second_migration.up.sql、3_migration_name.up.sql为便于编辑器排序也允许使用前导零如0001_migration.up.sql。迁移目录结构迁移文件位于服务内部的migrations目录中/my-app ├── encore.app // 项目根文件 │ └── site // site 服务 ├── migrations // 数据库迁移目录 │ └── 1_create_table.up.sql // 创建 site 表的迁移 ├── site.ts // 服务代码含 SQLDatabase 与 Knex 初始化 └── site.test.ts // 测试文件迁移出错时的处理Encore 在应用迁移失败时会回滚迁移云端部署失败会中止部署并在数据库中通过schema_migrations表记录已应用的迁移版本database# \d schema_migrations Table public.schema_migrations Column | Type | Collation | Nullable | Default ------------------------------------------------ version | bigint | | not null | dirty | boolean | | not null |如果遇到sqldb: unknown database之类的错误常见原因是迁移文件名不符合规范命名或位置有误可检查迁移文件后重新运行encore run。本地数据库状态损坏时可用encore db reset database-name加--all重置全部将数据库删除重建并从头应用所有迁移。第三步迁移的自动应用Knex.js 体系下通常需要手工执行knex migrate:latest来应用迁移而Encore 会在应用运行时自动应用迁移——你无需也不应手动运行任何knex migrate:latest之类的命令。这一机制与 Encore 的数据库管理模型一致本地环境执行encore run时Encore 通过 Docker 自动创建 PostgreSQL 数据库并按其顺序逐个应用*.up.sql迁移需要本地安装并运行 Docker若在应用运行期间新增数据库定义需重启encore run。云端环境部署时 Encore 自动完成数据库供给、迁移与运行时连接注入应用启动后数据库即可直接使用。因此你只需要保证迁移文件命名正确、SQL 合法Encore 会在本地与云端保持一致地完成 schema 演进。这一设计让 Knex.js 只负责「查询」把「schema 生命周期」完全交给 Encore 管理两者各司其职。用 Knex.js 编写业务查询Sites()构建器支持 Knex.js 完整的链式查询 API下面是基于site表的常用写法// 查询全部站点 const allSites: Site[] await Sites().select(); // 按 id 查询单个站点无结果返回 undefined const site await Sites().where(id, id).first(); // 新增站点 await Sites().insert({ url: params.url }); // 更新与删除同样沿用 Knex 语法 await Sites().where(id, id).update({ url: newUrl }); await Sites().where(id, id).delete();结合 Encore 的 SQLDatabase 原生能力需要强调SQLDatabase本身也提供了完整的查询 APIquery、queryRow、queryAll、exec等模板字符串方法见 database.ts因此你可以按场景混用偏好类型化链式查询 → 使用 Knex.js需要写复杂原生 SQL → 直接使用SiteDB.query\... 模板查询参数自动参数化防注入需要事务 → 两种方式都可用Knex 有自身的orm.transaction(...)而SQLDatabase也提供await db.begin()返回实现AsyncDisposable的Transaction对象未显式 commit/rollback 时自动回滚可根据团队习惯选择。与其它 ORM 集成的差异对比Encore 官方文档中还有 Drizzle、Prisma、Sequelize 等集成指南见 ORM 集成总览与 Knex.js 的关键差异在于迁移来源ORM / 工具连接方式迁移文件格式备注Knex.jsknex({ client: pg, connection: SiteDB.connectionString })纯 SQL*.up.sql不支持 Knex 生成的 JS 迁移文件Drizzledrizzle(db.connectionString)SQL由drizzle-kit generate生成migrations.source可设为drizzlePrismaPrismaClient 连接字符串SQLPrisma Migrate 生成migrations.source可设为prismaSequelizenew Sequelize(DB.connectionString)纯 SQL*.up.sql不支持 sequelize-cli 生成的 JS 迁移对于 Knex.js 用户建议的取舍是利用 Knex 的查询构建能力编写业务数据访问层同时用 Encore 的 SQL 迁移体系管理 schema两者互不冲突。如果表结构复杂、对迁移生成有自动化诉求可考虑改用 Drizzle/Prisma它们能自动产出 Encore 可识别的 SQL 迁移。总结在 Encore.ts 中集成 Knex.js 只需要三步new SQLDatabase(...)声明数据库资源 → 用connectionString初始化knex({ client: pg })→ 在migrations目录中维护 SQL 迁移文件。Encore 负责数据库的供给、连接注入与迁移应用Knex.js 专注查询构建这种职责划分让团队既能享受 Knex 的灵活链式查询又能获得 Encore 提供的环境一致性与云端自动化能力。进一步阅读Encore 中数据库资源与迁移的完整说明ORM 与迁移框架集成总览Drizzle ORM 集成指南Sequelize 集成指南SQLDatabase 源码实现【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考