> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talosjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Populate your database with initial data, fixtures, and test datasets using environment-aware, dependency-ordered seeds.

The `@talosjs/seeds` package is a database seeding framework for populating initial data, fixtures, and test datasets. A seed is a class implementing `ISeed` with a `run` method, an active flag, an optional environment list, and an optional dependency list. Seeds are registered with a decorator, filtered by whether they are active and target the current environment, and run in dependency order.

## How seeds behave

Each seed's `run()` populates the database. A seed can gate itself with `isActive()` and restrict itself to specific environments with `getEnv()`, so the runner only executes seeds that apply to the current run. Seeds can also declare other seeds as dependencies, and those run first — their return values are passed into the dependent seed's `run(data)`, so a seed can build on the records its dependencies created.

Unlike [migrations](/migrations/overview), seeds have no database table recording what has run. The per-seed [run cache](/seeds/caching) is the only record that a seed already ran, letting `seed:run` skip a seed whose code is unchanged since its last successful run for the same environment.

## The `ISeed` contract

A seed is a class that satisfies `ISeed` from `@talosjs/seeds`:

```typescript theme={null}
export interface ISeed {
  run: <T = unknown>(data?: unknown[]) => Promise<T> | T;
  isActive: () => Promise<boolean> | boolean;
  getDependencies: () => Promise<SeedClassType[]> | SeedClassType[];
  getEnv: () => Promise<Environment[]> | Environment[];
}
```

| Member              | Purpose                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `run(data)`         | Populate the database. Receives the return values of this seed's dependencies as `data`. |
| `isActive()`        | Return `false` to skip the seed entirely; `true` to include it.                          |
| `getDependencies()` | Return the seed classes that must run before this one.                                   |
| `getEnv()`          | Restrict the seed to the listed environments. An empty list runs in every environment.   |

## How seeds are selected

The runner resolves every registered seed from the container and keeps only those that apply to the run. A seed is skipped when `isActive()` returns `false`, or when `getEnv()` returns a non-empty list that does not include the current environment. The current environment comes from `APP_ENV`, which the [`seed:run`](/seeds/running) command sets from its `--env` option.

## Next steps

* [Writing seeds](/seeds/writing): scaffold a seed and implement `run()`, `isActive()`, `getEnv()`, and dependencies.
* [Running seeds](/seeds/running): populate the database across every module with `talos seed:run`.
* [Caching](/seeds/caching): how the per-seed run cache skips unchanged seeds.