Drizzle Seed

drizzle-seed 是一个 TypeScript 库，可帮助你生成确定性但又逼真的假数据来填充数据库。它利用可设定种子的伪随机数生成器（pRNG），确保你生成的数据在不同运行之间保持一致且可重现。这对于测试、开发和调试尤其有用。

什么是确定性数据生成？

确定性数据生成意味着相同的输入总会产生相同的输出。在 drizzle-seed 中，当你使用相同的种子值初始化库时，它每次都会生成相同的假数据序列。这使得数据集具有可预测性和可重复性。

伪随机数生成器（pRNG）

伪随机数生成器是一种生成数字序列的算法，这些数字序列在性质上近似随机数。然而，由于它基于一个初始值，也就是种子，你可以控制它的随机性。使用相同的种子时，pRNG 将产生相同的数字序列，使你的数据生成过程可重现。

使用 pRNG 的好处：

一致性：确保你的测试每次都在相同的数据上运行。
调试：通过提供一致的数据集，更容易复现并修复错误。
协作：团队成员可以共享种子值，以使用相同的数据集进行工作。

借助 drizzle-seed，你可以兼得两者：既能生成逼真的假数据，又能在需要时随时控制并重现这些数据。

安装

npm

yarn

pnpm

bun

npm i drizzle-seed

yarn add drizzle-seed

pnpm add drizzle-seed

bun add drizzle-seed

基本用法

在这个示例中，我们将创建 10 个拥有随机姓名和 id 的用户

import { cockroachTable, int4, text } from "drizzle-orm/cockroach-core";
import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";

const users = cockroachTable("users", {
  id: int4().primaryKey(),
  name: text().notNull(),
});

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);
  await seed(db, { users });
}

main();

选项

count

默认情况下，seed 函数会创建 10 个实体。不过，如果你的测试需要更多，可以在 seed 选项对象中指定这一点

await seed(db, schema, { count: 1000 });

seed

如果你需要一个 seed 来为后续的所有运行生成不同的一组值，可以在 seed 选项中定义一个不同的数字。任何新的数字都会生成一组唯一的值

await seed(db, schema, { seed: 12345 });

重置数据库

使用 drizzle-seed，你可以轻松重置数据库并使用新值对其进行填充，例如，在你的测试套件中

// 指向包含你想要重置的 schema 的文件路径
import * as schema from "./schema.ts";
import { reset } from "drizzle-seed";

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);
  await reset(db, schema);
}

main();

不同的方言会有不同的数据库重置策略

对于 CockroachDB，drizzle-seed 包将生成带有 CASCADE 选项的 TRUNCATE 语句，以确保在运行 reset 函数后所有表都为空

TRUNCATE tableName1, tableName2, ... CASCADE;

精细化

如果你需要更改 drizzle-seed 默认使用的种子生成器函数行为，可以指定你自己的实现，甚至可以在种子生成过程中使用你自己的值列表。

.refine 是一个回调函数，它接收来自 drizzle-seed 的所有可用生成器函数列表。它应该返回一个对象，其键代表你想要精细化的表，并按需定义它们的行为。
每个表都可以指定若干属性，以简化数据库的种子生成：

columns：通过指定所需的生成器函数来精细化每一列的默认行为，或者通过指定 false 将该列排除在种子生成之外。
count：指定要插入数据库的行数。默认值为 10。如果在 seed() 选项中定义了全局 count，这里定义的 count 将覆盖该表的全局设置。
with：如果你想生成关联实体，则定义每个父表要创建多少个引用实体。

info

你也可以为要创建的引用值数量指定加权随机分布。有关此 API 的详细信息，你可以参考 Weighted Random docs 文档部分。

API

await seed(db, schema).refine((f) => ({
  users: {
    columns: {},
    count: 10,
    with: {
        posts: 10
    }
  },
}));

让我们通过一些示例来看看会发生什么：

import { cockroachTable, int4, text } from "drizzle-orm/cockroach-core";

export const users = cockroachTable("users", {
  id: int4().primaryKey(),
  name: text().notNull(),
});

export const posts = cockroachTable("posts", {
  id: int4().primaryKey(),
  description: text(),
  userId: int4().references(() => users.id),
});

示例 1：仅为 users 表生成 20 条实体，并为 name 列使用精细化的种子逻辑

import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";
import * as schema from './schema.ts'

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);

  await seed(db, { users: schema.users }).refine((f) => ({
    users: {
        columns: {
            name: f.fullName(),
        },
        count: 20
    }
  }));
}

main();

示例 2：仅为 users 表生成种子，并将 name 列排除在种子生成之外

import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";
import * as schema from './schema.ts'

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);

  await seed(db, { users: schema.users }).refine((f) => ({
    users: {
        columns: {
            name: false, // name 列不会被生成种子，允许数据库使用其默认值。
        }
    }
  }));
}

main();

示例 3：为 users 表生成 20 条实体，并通过为 posts 表生成种子并创建从 posts 到 users 的引用，为每个 user 添加 10 条 posts

import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";
import * as schema from './schema.ts'

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);

  await seed(db, schema).refine((f) => ({
    users: {
        count: 20,
        with: {
            posts: 10
        }
    }
  }));
}

main();

示例 4：为 users 表生成 5 条实体，并向数据库填充 100 条 posts，但不将它们与 users 实体关联。精细化 users 的 id 生成，使其生成任意从 10000 到 20000 的整数且保持唯一，并精细化 posts，使其从自定义数组中获取值

import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";
import * as schema from './schema.ts'

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);

  await seed(db, schema).refine((f) => ({
    users: {
        count: 5,
        columns: {
            id: f.int({
              minValue: 10000,
              maxValue: 20000,
              isUnique: true,
            }),
        }
    },
    posts: {
        count: 100,
        columns: {
            description: f.valuesFromArray({
            values: [
                "The sun set behind the mountains, painting the sky in hues of orange and purple", 
                "I can't believe how good this homemade pizza turned out!", 
                "Sometimes, all you need is a good book and a quiet corner.", 
                "Who else thinks rainy days are perfect for binge-watching old movies?", 
                "Tried a new hiking trail today and found the most amazing waterfall!",
                // ...
            ],
          })
        }
    }
  }));
}

main();

IMPORTANT

我们将在这些文档中定义更多可能性，但目前你可以浏览本文档中的几个章节。查看 Generators 部分，以熟悉你可以使用的所有可用生成器函数。

一个特别强大的功能是使用加权随机化，既可用于为某一列创建的生成器值，也可用于确定 drizzle-seed 能生成多少个相关实体。

请查看 Weighted Random docs 了解更多信息。

加权随机

在某些情况下，你可能需要在种子阶段将具有不同优先级的多个数据集插入到数据库中。对于这种情况，drizzle-seed 提供了一个名为 weighted random 的 API

Drizzle Seed 包在以下几个地方可以使用 weighted random：

每个表细化中的列
with 属性，用于确定要创建的相关实体数量

下面来看两个示例：

import { cockroachTable, int4, text, varchar, doublePrecision } from "drizzle-orm/cockroach-core";

export const orders = cockroachTable(
  "orders",
  {
    id: int4().primaryKey(),
    name: text().notNull(),
    quantityPerUnit: varchar().notNull(),
    unitPrice: doublePrecision().notNull(),
    unitsInStock: int4().notNull(),
    unitsOnOrder: int4().notNull(),
    reorderLevel: int4().notNull(),
    discontinued: int4().notNull(),
  }
);

export const details = cockroachTable(
  "details",
  {
    unitPrice: doublePrecision().notNull(),
    quantity: int4().notNull(),
    discount: doublePrecision().notNull(),

    orderId: int4()
      .notNull()
      .references(() => orders.id, { onDelete: "cascade" }),
  }
);

示例 1：细化 unitPrice 的生成逻辑，生成 5000 个随机价格，其中有 30% 的概率生成 10-100 之间的价格，70% 的概率生成 100-300 之间的价格

import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";
import * as schema from './schema.ts'

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);

  await seed(db, schema).refine((f) => ({
    orders: {
       count: 5000,
       columns: {
           unitPrice: f.weightedRandom(
               [
                   {
                       weight: 0.3,
                       value: f.int({ minValue: 10, maxValue: 100 })
                   },
                   {
                       weight: 0.7,
                       value: f.number({ minValue: 100, maxValue: 300, precision: 100 })
                   }
               ]
           ),
       }
    }
  }));
}

main();

示例 2：对于每个订单，生成 1 到 3 条 details 的概率为 60%，生成 5 到 7 条 details 的概率为 30%，生成 8 到 10 条 details 的概率为 10%

import { drizzle } from "drizzle-orm/cockroach";
import { seed } from "drizzle-seed";
import * as schema from './schema.ts'

async function main() {
  const db = drizzle(process.env.DATABASE_URL!);

  await seed(db, schema).refine((f) => ({
    orders: {
       with: {
           details:
               [
                   { weight: 0.6, count: [1, 2, 3] },
                   { weight: 0.3, count: [5, 6, 7] },
                   { weight: 0.1, count: [8, 9, 10] },
               ]
       }
    }
  }));
}

main();

复杂示例

main.ts

schema.ts

import { seed } from "drizzle-seed";
import * as schema from "./schema.ts";

const main = async () => {
    const titlesOfCourtesy = ["Ms.", "Mrs.", "Dr."];
    const unitsOnOrders = [0, 10, 20, 30, 50, 60, 70, 80, 100];
    const reorderLevels = [0, 5, 10, 15, 20, 25, 30];
    const quantityPerUnit = [
        "100 - 100 g pieces",
        "100 - 250 g bags",
        "10 - 200 g glasses",
        "10 - 4 oz boxes",
        "10 - 500 g pkgs.",
        "10 - 500 g pkgs."
    ];
    const discounts = [0.05, 0.15, 0.2, 0.25];

    await seed(db, schema).refine((funcs) => ({
        customers: {
            count: 10000,
            columns: {
                companyName: funcs.companyName(),
                contactName: funcs.fullName(),
                contactTitle: funcs.jobTitle(),
                address: funcs.streetAddress(),
                city: funcs.city(),
                postalCode: funcs.postcode(),
                region: funcs.state(),
                country: funcs.country(),
                phone: funcs.phoneNumber({ template: "(###) ###-####" }),
                fax: funcs.phoneNumber({ template: "(###) ###-####" })
            }
        },
        employees: {
            count: 200,
            columns: {
                firstName: funcs.firstName(),
                lastName: funcs.lastName(),
                title: funcs.jobTitle(),
                titleOfCourtesy: funcs.valuesFromArray({ values: titlesOfCourtesy }),
                birthDate: funcs.date({ minDate: "2010-12-31", maxDate: "2010-12-31" }),
                hireDate: funcs.date({ minDate: "2010-12-31", maxDate: "2024-08-26" }),
                address: funcs.streetAddress(),
                city: funcs.city(),
                postalCode: funcs.postcode(),
                country: funcs.country(),
                homePhone: funcs.phoneNumber({ template: "(###) ###-####" }),
                extension: funcs.int({ minValue: 428, maxValue: 5467 }),
                notes: funcs.loremIpsum()
            }
        },
        orders: {
            count: 50000,
            columns: {
                shipVia: funcs.int({ minValue: 1, maxValue: 3 }),
                freight: funcs.number({ minValue: 0, maxValue: 1000, precision: 100 }),
                shipName: funcs.streetAddress(),
                shipCity: funcs.city(),
                shipRegion: funcs.state(),
                shipPostalCode: funcs.postcode(),
                shipCountry: funcs.country()
            },
            with: {
                details:
                    [
                        { weight: 0.6, count: [1, 2, 3, 4] },
                        { weight: 0.2, count: [5, 6, 7, 8, 9, 10] },
                        { weight: 0.15, count: [11, 12, 13, 14, 15, 16, 17] },
                        { weight: 0.05, count: [18, 19, 20, 21, 22, 23, 24, 25] },
                    ]
            }
        },
        suppliers: {
            count: 1000,
            columns: {
                companyName: funcs.companyName(),
                contactName: funcs.fullName(),
                contactTitle: funcs.jobTitle(),
                address: funcs.streetAddress(),
                city: funcs.city(),
                postalCode: funcs.postcode(),
                region: funcs.state(),
                country: funcs.country(),
                phone: funcs.phoneNumber({ template: "(###) ###-####" })
            }
        },
        products: {
            count: 5000,
            columns: {
                name: funcs.companyName(),
                quantityPerUnit: funcs.valuesFromArray({ values: quantityPerUnit }),
                unitPrice: funcs.weightedRandom(
                    [
                        {
                            weight: 0.5,
                            value: funcs.int({ minValue: 3, maxValue: 300 })
                        },
                        {
                            weight: 0.5,
                            value: funcs.number({ minValue: 3, maxValue: 300, precision: 100 })
                        }
                    ]
                ),
                unitsInStock: funcs.int({ minValue: 0, maxValue: 125 }),
                unitsOnOrder: funcs.valuesFromArray({ values: unitsOnOrders }),
                reorderLevel: funcs.valuesFromArray({ values: reorderLevels }),
                discontinued: funcs.int({ minValue: 0, maxValue: 1 })
            }
        },
        details: {
            columns: {
                unitPrice: funcs.number({ minValue: 10, maxValue: 130 }),
                quantity: funcs.int({ minValue: 1, maxValue: 130 }),
                discount: funcs.weightedRandom(
                    [
                        { weight: 0.5, value: funcs.valuesFromArray({ values: discounts }) },
                        { weight: 0.5, value: funcs.default({ defaultValue: 0 }) }
                    ]
                )
            }
        }
    }));
}

main();

import type { AnyCockroachColumn } from "drizzle-orm/cockroach-core";
import { int4, numeric, cockroachTable, text, timestamp, varchar } from "drizzle-orm/cockroach-core";

export const customers = cockroachTable('customer', {
	id: varchar({ length: 256 }).primaryKey(),
	companyName: text().notNull(),
	contactName: text().notNull(),
	contactTitle: text().notNull(),
	address: text().notNull(),
	city: text().notNull(),
	postalCode: text(),
	region: text(),
	country: text().notNull(),
	phone: text().notNull(),
	fax: text(),
});

export const employees = cockroachTable(
	'employee',
	{
		id: int4().primaryKey(),
		lastName: text().notNull(),
		firstName: text(),
		title: text().notNull(),
		titleOfCourtesy: text().notNull(),
		birthDate: timestamp().notNull(),
		hireDate: timestamp().notNull(),
		address: text().notNull(),
		city: text().notNull(),
		postalCode: text().notNull(),
		country: text().notNull(),
		homePhone: text().notNull(),
		extension: int4().notNull(),
		notes: text().notNull(),
		reportsTo: int4().references((): AnyCockroachColumn => employees.id),
		photoPath: text(),
	},
);

export const orders = cockroachTable('order', {
	id: int4().primaryKey(),
	orderDate: timestamp().notNull(),
	requiredDate: timestamp().notNull(),
	shippedDate: timestamp(),
	shipVia: int4().notNull(),
	freight: numeric().notNull(),
	shipName: text().notNull(),
	shipCity: text().notNull(),
	shipRegion: text(),
	shipPostalCode: text(),
	shipCountry: text().notNull(),

	customerId: text().notNull().references(() => customers.id, { onDelete: 'cascade' }),

	employeeId: int4().notNull().references(() => employees.id, { onDelete: 'cascade' }),
});

export const suppliers = cockroachTable('supplier', {
	id: int4().primaryKey(),
	companyName: text().notNull(),
	contactName: text().notNull(),
	contactTitle: text().notNull(),
	address: text().notNull(),
	city: text().notNull(),
	region: text(),
	postalCode: text().notNull(),
	country: text().notNull(),
	phone: text().notNull(),
});

export const products = cockroachTable('product', {
	id: int4().primaryKey(),
	name: text().notNull(),
	quantityPerUnit: text().notNull(),
	unitPrice: numeric().notNull(),
	unitsInStock: int4().notNull(),
	unitsOnOrder: int4().notNull(),
	reorderLevel: int4().notNull(),
	discontinued: int4().notNull(),

	supplierId: int4().notNull().references(() => suppliers.id, { onDelete: 'cascade' }),
});

export const details = cockroachTable('order_detail', {
	unitPrice: numeric().notNull(),
	quantity: int4().notNull(),
	discount: numeric().notNull(),

	orderId: int4().notNull().references(() => orders.id, { onDelete: 'cascade' }),

	productId: int4().notNull().references(() => products.id, { onDelete: 'cascade' }),
});

限制

`with` 的类型限制

由于某些 TypeScript 限制以及 Drizzle 当前的 API，无法正确推断表之间的引用关系，尤其是在表之间存在循环依赖时。

这意味着 with 选项会显示 schema 中的所有表，你需要手动选择那个具有一对多关系的表

warning

with 选项适用于一对多关系。例如，如果你有一个 user 和多个 posts，你可以使用 users with posts，但不能使用 posts with users

Drizzle 表中第三个参数的类型限制：

目前，我们还不支持 Drizzle 表第三个参数的类型。虽然它在运行时可以工作，但在类型层面上无法正常运行