TypeORM Seeding
A delightful way to seed test data into your database.
Inspired by the awesome framework laravel in PHP, MikroORM seeding and the repositories from pleerock
Made with ❤️ by Gery Hirschfeld, Jorge Bodega and contributors
# Contents
- [Seeder](#seeder-1)
- [run](#run)
- [CLI](#cli-configuration)
- [seed](#seed)
- [Testing features](#testing-features)
# Installation
Before using this TypeORM extension please read the [TypeORM Getting Started](https://typeorm.io/#/) documentation. This explains how to setup a TypeORM project.
After that install the extension with `npm` or `yarn`. Add development flag if you are not using seeders nor factories in production code.
```bash
npm i [-D] @jorgebodega/typeorm-seeding
yarn add [-D] @jorgebodega/typeorm-seeding
pnpm add [-D] @jorgebodega/typeorm-seeding
```
# Introduction
Isn't it exhausting to create some sample data for your database, well this time is over!
How does it work? Just create a entity factory and/or seed script.
### Entity
```typescript
@Entity()
class User {
@PrimaryGeneratedColumn('increment')
id!: number
@Column()
name!: string
@Column()
lastName!: string
@Column()
email!: string
@OneToMany(() => Pet, (pet) => pet.owner)
pets?: Pet[]
@ManyToOne(() => Country, (country) => country.users, { nullable: false })
@JoinColumn()
country!: Country
}
```
### Seeder
```typescript
class UserSeeder extends Seeder {
async run(dataSource: DataSource) {
const users: User[] = [...]
await dataSource.createEntityManager().save(users)
}
}
```
# Seeder
Seeder class is how we provide a way to insert data into databases, and could be executed by the command line or by helper method. Is an abstract class with one method to be implemented, and a helper function to run some more seeder sequentially.
```typescript
class UserSeeder extends Seeder {
async run(dataSource: DataSource) {
...
}
}
```
This seeder class must be exported as default to be handled by the CLI.
```typescript
export default class UserSeeder extends Seeder {
async run(dataSource: DataSource) {
...
}
}
```
## `run`
This function is the one that needs to be defined when extending the class.
```typescript
run(dataSource: DataSource): Promise
```
```typescript
async run(dataSource: DataSource) {
const users: User[] = [...]
await dataSource.createEntityManager().save(users)
}
```
# CLI Configuration
There is a command that allows you to execute multiple seeders from cli.
```bash
typeorm-seeding seed -d path/to/datasource src/seeders/*.ts
```
Add the following script to your `package.json` file to configure them.
```json
"scripts": {
"seed:run": "typeorm-seeding seed -d path/to/datasource",
...
}
```
## `seed`
This command execute a seeder, that could be specified as a parameter. Glob pattern is supported.
```bash
typeorm-seeding -d [...] seed
```
CLI command only executes default seeders.
##### Options
| Option | Default | Description |
| ---------------------- | ------------------------------------ | ----------------------------------------------------- |
| `--dataSource` or `-d` | | Path of the data source |
# Testing features
We provide some testing features that we already use to test this package, like connection configuration.
The entity factories can also be used in testing. To do so call the `useFactories` or `useSeeders` function.
## `useSeeders`
Execute one or more seeders.
```typescript
useSeeders(entrySeeders: ClassConstructor | ClassConstructor[]): Promise
useSeeders(
entrySeeders: ClassConstructor | ClassConstructor[],
customOptions: Partial,
): Promise
```
## `useDataSource`
Use specific data source on the factories. If the data source is not initialized when provided, can be initialized with the `forceInitialization` flag.
```typescript
useDataSource(dataSource: DataSource): Promise
useDataSource(dataSource: DataSource, overrideOptions: Partial): Promise
useDataSource(dataSource: DataSource, forceInitialization: boolean): Promise
useDataSource(
dataSource: DataSource,
overrideOptions: Partial,
forceInitialization: boolean,
): Promise
```
# Factory
Factory related code has been removed from this package, now on [@jorgebodega/typeorm-factory](https://github.com/jorgebodega/typeorm-factory).