CLI: Seeding Data
Relevant source files
The following files were used as context for generating this wiki page:The data seeding feature, exposed through the @better-auth-kit/cli, provides a robust mechanism to populate a Better Auth database with deterministic, yet realistic, fake data. This is essential for development and testing environments, allowing developers to work with a consistent and populated dataset. The core logic is powered by the @better-auth-kit/seed library, which offers a flexible API for defining data schemas and generators.
The CLI command discovers and executes user-defined seed scripts. These scripts can be a single seed.ts file or a directory of multiple seed files. The system is designed to be extensible, using helper functions and a rich dataset of fake data generators to create complex data structures, including users, organizations, and their relationships.
Sources: packages/libraries/seed/package.json, packages/cli/src/commands/seed/index.ts:1-20, packages/libraries/seed/src/index.ts:1-10
Command Usage
The primary entry point for data seeding is the seed command provided by the CLI.
Sources: packages/cli/src/commands/seed/index.ts:130-137
# Example usage
bunx @better-auth-kit/cli seed
The command accepts several options to control its behavior:
| Option | Alias | Description | Default |
|---|---|---|---|
--cwd <cwd> | -c | The working directory. | process.cwd() |
--config <config> | The path to the auth configuration file. | The first auth.ts file found. | |
--run-all | Run all seed files in the seed folder without prompting. | false |
Sources: packages/cli/src/commands/seed/index.ts:131-136
Seeding Process Flow
The seed command follows a specific sequence of steps to locate, load, and execute seed files. It first loads the main auth.ts configuration to get the database adapter context, then proceeds to find and run the seed scripts.
This diagram illustrates the flow of the seed command.
Execution of a Seed File
Once a seed file is identified, the CLI loads it and executes the exported seed function.
The following sequence diagram shows the interactions during the execution of a single seed file.
Seed File Structure
A seed file must export a seed object created by the Seed() function and can optionally export a config object.
Sources: packages/cli/testing/seed.ts, packages/cli/testing/seed/0-test.ts
config Export
The config object allows for configuring the seeding process.
| Property | Type | Description |
|---|---|---|
deleteRowsBeforeSeeding | { enabled: boolean; models: string[] } | If enabled, deletes all rows from the specified models before seeding. |
rows | number | The default number of rows to generate per table if not specified otherwise. |
Sources: packages/libraries/seed/src/index.ts:33-34, packages/cli/testing/seed.ts:9-19
seed Export
The seed export is the main component, created by calling the Seed() function with a schema object. The schema defines the tables to be seeded.
An example seed.ts file:
import {
Seed,
users,
organizations,
type SeedConfig,
} from "@better-auth-kit/seed";
export const config: SeedConfig = {
deleteRowsBeforeSeeding: {
enabled: true,
models: [
"session",
"account",
"member",
"invitation",
"team",
"apikey",
"user",
"organization",
],
},
};
export const seed = Seed({
...users(),
...organizations(),
});
Sources: packages/cli/testing/seed.ts:1-23
Defining Data
The @better-auth-kit/seed library provides functions to define tables and generate data for their columns.
table()
The table() function defines a schema for a database table, including the number of rows to generate and the data for each column.
Sources: packages/libraries/seed/src/index.ts:157-197
dataset ($)
The dataset (aliased as $) is a collection of data generator functions for creating realistic fake data, such as names, emails, and UUIDs.
Sources: packages/libraries/seed/src/index.ts:12
Asynchronous Seeding and Helpers
The Seed function can also accept an asynchronous function that receives a helpers object. This allows for more complex seeding scenarios where data from one generator is needed in another. The helpers.get() function can be used to resolve a generator's value.
import { $, Seed, table, type SeedConfig } from "@better-auth-kit/seed";
// ... config export
export const seed = Seed(async ({ get }) => {
const first_name = await get($.firstname());
const last_name = await get($.lastname());
const isBanned = await get($.randomBoolean({ probability: 0.1 }));
return {
test: table({
name: $.custom(() => `${first_name} ${last_name}`),
banned: $.custom(() => isBanned),
banReason: $.custom(() => (isBanned ? "test" : null)),
}),
};
});
Sources: packages/cli/testing/seed/0-test.ts:1-24, packages/libraries/seed/src/index.ts:22-25
Seeding Helpers
The library includes pre-built helper functions to easily seed common, related data structures.
organizations() Helper
The organizations() helper is a high-level function that generates data for organizations, members, teams, and invitations, including the relationships between them.
This ER diagram shows the entities and relationships created by the organizations helper.
The helper can be configured with options to customize model names, the number of records, and whether to create related entities like members, teams, and invitations.
Sources: packages/libraries/seed/src/helpers/organizations.ts:60-95
Summary
The CLI seeding feature is a powerful and flexible tool for developers using the Better Auth Kit. It streamlines the process of populating a database for development and testing by combining a simple command-line interface with a rich data generation library. By defining simple seed.ts files, developers can generate complex, related data, including users and multi-tenant organization structures, ensuring a consistent and realistic development environment.
Sources: packages/cli/src/commands/seed/index.ts, packages/libraries/seed/src/index.ts