Drizzle 与 Nile Database

本教程演示了如何将 Drizzle ORM 与 Nile Database 结合使用。Nile 是为多租户应用程序重新设计的 Postgres 数据库。

本教程将演示如何将 Drizzle 与 Nile 的虚拟租户数据库结合使用，以开发安全、可扩展的多租户应用程序。

我们将逐步构建这个示例应用程序。如果您想查看完整示例，可以在其 Github 仓库中查看。

本指南假定您熟悉

您应该已经安装了 Drizzle ORM 和 Drizzle Kit。您可以通过运行以下命令来完成此操作：

npm

yarn

pnpm

bun

npm i drizzle-orm
npm i -D drizzle-kit

yarn add drizzle-orm
yarn add -D drizzle-kit

pnpm add drizzle-orm
pnpm add -D drizzle-kit

bun add drizzle-orm
bun add -D drizzle-kit

您应该已安装 dotenv 包来管理环境变量。在此处了解有关此包的更多信息这里

npm

yarn

pnpm

bun

npm i dotenv

yarn add dotenv

pnpm add dotenv

bun add dotenv

您应该已安装用于连接到 Postgres 数据库的 node-postgres 包。在此处了解有关此包的更多信息 here

npm

yarn

pnpm

bun

npm i node-postgres

yarn add node-postgres

pnpm add node-postgres

bun add node-postgres

您应该已安装用于 Web 框架的 express 包。在此处了解有关 express 的更多信息 here

npm

yarn

pnpm

bun

npm i express

yarn add express

pnpm add express

bun add express

本指南使用 AsyncLocalStorage 来管理租户上下文。如果您的框架或运行时不支持 AsyncLocalStorage，您可以参考 Drizzle<>Nile 文档以获取替代选项。

设置 Nile 和 Drizzle ORM

如果您尚未注册，请注册 Nile 并按照应用程序说明创建一个新数据库。

获取数据库连接字符串

在左侧边栏菜单中，选择“Settings”选项，点击 Postgres 标志，然后点击“generate credentials”。复制连接字符串并将其添加到项目中的 .env 文件。

NILEDB_URL=postgres://youruser:[email protected]:5432:5432/your_db_name

将 Drizzle ORM 连接到您的数据库

在 src/db 目录中创建 db.ts 文件并设置您的数据库配置

import { drizzle } from 'drizzle-orm/node-postgres';
import dotenv from "dotenv/config";
import { sql } from "drizzle-orm";
import { AsyncLocalStorage } from "async_hooks";

export const db = drizzle(process.env.NILEDB_URL);
export const tenantContext = new AsyncLocalStorage<string | undefined>();

export function tenantDB<T>(cb: (tx: any) => T | Promise<T>): Promise<T> {
  return db.transaction(async (tx) => {
    const tenantId = tenantContext.getStore();
    console.log("executing query with tenant: " + tenantId);
    // if there's a tenant ID, set it in the transaction context
    if (tenantId) {
      await tx.execute(sql`set local nile.tenant_id = '${sql.raw(tenantId)}'`);
    }

    return cb(tx);
  }) as Promise<T>;
}

设置 Drizzle 配置文件

Drizzle config - 由 Drizzle Kit 使用的配置文件，包含有关你的数据库连接、迁移文件夹和 schema 文件的所有信息。

在项目的根目录中创建 drizzle.config.ts 文件并添加以下内容

import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
  out: './drizzle',
  schema: './src/db/schema.ts',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.NILEDB_URL!,
  },
});

内省 Nile 数据库

Nile 数据库内置了一些表。其中最重要的是 tenants 表，它用于创建和管理租户。为了在我们的应用程序中使用此表，我们将使用 Drizzle Kit CLI 生成一个包含此模式的模式文件。

npx drizzle-kit pull

内省的结果将是 schema.ts 文件、包含数据库模式快照的 meta 文件夹、包含迁移的 SQL 文件以及用于关系查询的 relations.ts 文件。

我们建议将从 drizzle/schema.ts 和 drizzle/relations.ts 生成的代码转移到实际的模式文件。本指南中，我们将代码转移到了 src/db/schema.ts。生成的模式和关系文件可以删除。这样您可以以更结构化的方式管理您的模式。

 ├ 📂 drizzle
 │ ├ 📂 meta
 │ ├ 📜 migration.sql
 │ ├ 📜 relations.ts ────────┐
 │ └ 📜 schema.ts ───────────┤
 ├ 📂 src                    │ 
 │ ├ 📂 db                   │
 │ │ ├ 📜 relations.ts <─────┤
 │ │ └ 📜 schema.ts <────────┘
 │ └ 📜 index.ts         
 └ …

这是生成的 schema.ts 文件的示例

// table schema generated by introspection
import { pgTable, uuid, text, timestamp, varchar, vector, boolean } from "drizzle-orm/pg-core"
import { sql } from "drizzle-orm"

export const tenants = pgTable("tenants", {
	id: uuid().default(sql`public.uuid_generate_v7()`).primaryKey().notNull(),
	name: text(),
	created: timestamp({ mode: 'string' }).default(sql`LOCALTIMESTAMP`).notNull(),
	updated: timestamp({ mode: 'string' }).default(sql`LOCALTIMESTAMP`).notNull(),
	deleted: timestamp({ mode: 'string' }),
});

创建附加表

除了内置表之外，我们的应用程序还需要一些表来存储其数据。我们将它们添加到我们之前生成的 src/db/schema.ts 中，因此该文件将如下所示

// table schema generated by introspection
import { pgTable, uuid, text, timestamp, varchar, vector, boolean } from "drizzle-orm/pg-core"
import { sql } from "drizzle-orm"

export const tenants = pgTable("tenants", {
	id: uuid().default(sql`public.uuid_generate_v7()`).primaryKey().notNull(),
	name: text(),
	created: timestamp({ mode: 'string' }).default(sql`LOCALTIMESTAMP`).notNull(),
	updated: timestamp({ mode: 'string' }).default(sql`LOCALTIMESTAMP`).notNull(),
	deleted: timestamp({ mode: 'string' }),
});

export const todos = pgTable("todos", {
	id: uuid().defaultRandom(),
	tenantId: uuid("tenant_id"),
	title: varchar({ length: 256 }),
	estimate: varchar({ length: 256 }),
	embedding: vector({ dimensions: 3 }),
	complete: boolean(),
});

将更改应用于数据库

您可以使用 drizzle-kit push 命令直接将更改应用到数据库。这是一种在本地开发环境中快速测试新模式设计或修改的便捷方法，允许快速迭代，而无需管理迁移文件。

npx drizzle-kit push

在文档中阅读更多关于 push 命令的信息。

提示

或者，你可以使用 drizzle-kit generate 命令生成迁移，然后使用 drizzle-kit migrate 命令应用它们

生成迁移

npx drizzle-kit generate

应用迁移

npx drizzle-kit migrate

在文档中阅读更多关于迁移过程的信息。

初始化 Web 应用程序

现在我们已经设置好 Drizzle 连接到 Nile 并准备好模式，我们可以在多租户 Web 应用程序中使用它们。在此示例中，我们使用 Express 作为 Web 框架，尽管 Nile 和 Drizzle 可以用于任何 Web 框架。

为了简化示例，我们将 Web 应用程序实现在单个文件 src/app.ts 中。我们将从初始化 Web 应用程序开始

import express from "express";
import { tenantDB, tenantContext, db } from "./db/db";
import {
  tenants as tenantSchema,
  todos as todoSchema,
} from "./db/schema";
import { eq } from "drizzle-orm";

const PORT = process.env.PORT || 3001;

const app = express();
app.listen(PORT, () => console.log(`Server is running on port ${PORT}`));
app.use(express.json());

初始化租户感知中间件

接下来，我们将向示例添加中间件。此中间件从路径参数中获取租户 ID 并将其存储在 AsyncLocalStorage 中。我们在 src/db/index.ts 中创建的 tenantDB 包装器使用此租户 ID 在执行查询时设置 nile.tenant_id，从而确保查询将针对此租户的虚拟数据库执行。

// set the tenant ID in the context based on the URL parameter
app.use('/api/tenants/:tenantId/*', (req, res, next) => {
  const tenantId = req.params.tenantId;
  console.log("setting context to tenant: " + tenantId);
  tenantContext.run(tenantId, next);
});

此示例从路径参数获取租户 ID，但通常也通过请求头（例如 x-tenant-id）或 Cookie 来设置租户 ID。

添加路由

最后，我们需要添加一些用于创建和列出租户及待办事项的路由。请注意我们如何使用 tenantDB 包装器连接到租户的虚拟数据库。另请注意，在 app.get("/api/tenants/:tenantId/todos" 中，我们不需要在查询中指定 where tenant_id=...。这正是因为我们被路由到该租户的数据库，并且查询无法返回任何其他租户的数据。

// create new tenant
app.post("/api/tenants", async (req, res) => {
  try {
    const name = req.body.name;
    var tenants: any = null;
    tenants = await tenantDB(async (tx) => {
        return await tx.insert(tenantSchema).values({ name }).returning();
    });
    res.json(tenants);
  } catch (error: any) {
    console.log("error creating tenant: " + error.message);
    res.status(500).json({message: "Internal Server Error",});
  }
});

// return list of tenants
app.get("/api/tenants", async (req, res) => {
  let tenants: any = [];
  try {
      tenants = await tenantDB(async (tx) => {
        return await tx.select().from(tenantSchema);
      });
    res.json(tenants);
  } catch (error: any) {
    console.log("error listing tenants: " + error.message);
    res.status(500).json({message: "Internal Server Error",});
  }
});

// add new task for tenant
app.post("/api/tenants/:tenantId/todos", async (req, res) => {
  try {
    const { title, complete } = req.body;
    if (!title) {
      res.status(400).json({message: "No task title provided",});
    }
    const tenantId = req.params.tenantId;

    const newTodo = await tenantDB(async (tx) => {
      return await tx
        .insert(todoSchema)
        .values({ tenantId, title, complete })
        .returning();
    });
    // return without the embedding vector, since it is huge and useless
    res.json(newTodo);
  } catch (error: any) {
    console.log("error adding task: " + error.message);
    res.status(500).json({message: "Internal Server Error",});
  }
});

// update tasks for tenant
// No need for where clause because we have the tenant in the context
app.put("/api/tenants/:tenantId/todos", async (req, res) => {
  try {
    const { id, complete } = req.body;
    await tenantDB(async (tx) => {
      return await tx
        .update(todoSchema)
        .set({ complete })
        .where(eq(todoSchema.id, id));
    });
    res.sendStatus(200);
  } catch (error: any) {
    console.log("error updating tasks: " + error.message);
    res.status(500).json({message: "Internal Server Error",});
  }
});

// get all tasks for tenant
app.get("/api/tenants/:tenantId/todos", async (req, res) => {
  try {
    // No need for a "where" clause here because we are setting the tenant ID in the context
    const todos = await tenantDB(async (tx) => {
      return await tx
        .select({
          id: todoSchema.id,
          tenant_id: todoSchema.tenantId,
          title: todoSchema.title,
          estimate: todoSchema.estimate,
        })
        .from(todoSchema);
    });
    res.json(todos);
  } catch (error: any) {
    console.log("error listing tasks: " + error.message);
    res.status(500).json({message: error.message,});
  }
});

试一试！

您现在可以运行您的新 Web 应用程序

npx tsx src/app.ts

并使用 curl 尝试您刚刚创建的路由

# create a tenant
curl --location --request POST 'localhost:3001/api/tenants' \
--header 'Content-Type: application/json' \
--data-raw '{"name":"my first customer"}'

# get tenants
curl  -X GET 'https://:3001/api/tenants'

# create a todo (don't forget to use a real tenant-id in the URL)
curl  -X POST \
  'https://:3001/api/tenants/108124a5-2e34-418a-9735-b93082e9fbf2/todos' \
  --header 'Content-Type: application/json' \
  --data-raw '{"title": "feed the cat", "complete": false}'

# list todos for tenant (don't forget to use a real tenant-id in the URL)
curl  -X GET \
  'https://:3001/api/tenants/108124a5-2e34-418a-9735-b93082e9fbf2/todos'

项目文件结构

这是项目的文件结构。在 src/db 目录中，我们有与数据库相关的文件，包括 db.ts 中的连接和 schema.ts 中的模式定义。由迁移和内省生成的文件位于 ./drizzle 中。

📦 <project root>
 ├ 📂 src
 │   ├ 📂 db
 │   │  ├ 📜 db.ts
 │   │  └ 📜 schema.ts
 │   └ 📜 app.ts
 ├ 📂 drizzle
 │   ├ 📂 meta
 │   │  ├ 📜 _journal.json
 │   │  └ 📜 0000_snapshot.json
 │   ├ 📜 relations.ts
 │   ├ 📜 schema.ts
 │   └ 📜 0000_watery_spencer_smythe.sql
 ├ 📜 .env
 ├ 📜 drizzle.config.ts
 └ 📜 package.json

Drizzle 与 Nile Database

设置 Nile 和 Drizzle ORM

注册 Nile 并创建数据库

获取数据库连接字符串

将 Drizzle ORM 连接到您的数据库

设置 Drizzle 配置文件

内省 Nile 数据库

创建附加表

将更改应用于数据库

初始化 Web 应用程序

初始化租户感知中间件

添加路由

试一试！

项目文件结构