TypeORM Seeding
A delightful way to seed test data into your database.
Inspired by the awesome framework laravel in PHP and of the repositories from pleerock
Made with ❤️ by Gery Hirschfeld and contributors
❯ Table of contents
- Introduction
- Installation
- Basic Seeder
- Using Entity Factory
- Seeding Data in Testing
- Changelog
- License
❯ 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 for your entities (models) and a seed script.
Enity
First create your TypeORM entites.
// user.enity.ts // pet.enity.ts
Factory
Then for each entity define a factory. The purpose of a factory is to create new entites with generate data.
Note: Factories can also be used to generate data for testing.
// user.factory.tsdefineUser, // pet.factory.tsdefinePet,
Seeder
And last but not least, create a seeder. The seeder can be called by the configured cli command seed:run
. In this case it generates 10 pets with a owner (User).
Note:
seed:run
must be configured first. Go to CLI Configuration.
// create-pets.seed.ts
❯ Installation
Before using this TypeORM extension please read the TypeORM Getting Started documentation. This explains how to setup a TypeORM project.
After that install the extension with npm
or yarn
.
npm i typeorm-seeding# or yarn add typeorm-seeding
Optional, install the type definitions of the Faker
library.
npm install -D @types/faker
Configuration
To configure the path to your seeds and factories change the TypeORM config file(ormconfig.js or ormconfig.json).
The default paths are
src/database/{seeds,factories}/**/*{.ts,.js}
ormconfig.js
module.exports = { ... seeds: ['src/seeds/**/*{.ts,.js}'], factories: ['src/factories/**/*{.ts,.js}'],}
.env
TYPEORM_SEEDING_FACTORIES=src/factories/**/*{.ts,.js}
TYPEORM_SEEDING_SEEDS=src/seeds/**/*{.ts,.js}
CLI Configuration
Add the following scripts to your package.json
file to configure the seed cli commands.
"scripts": {
"seed:config": "ts-node ./node_modules/typeorm-seeding/dist/cli.js config"
"seed:run": "ts-node ./node_modules/typeorm-seeding/dist/cli.js seed"
...
}
To execute the seed run npm run seed:run
in the terminal.
Note: More CLI optios are here
Add the following TypeORM cli commands to the package.json to drop and sync the database.
"scripts": {
...
"schema:drop": "ts-node ./node_modules/typeorm/cli.js schema:drop",
"schema:sync": "ts-node ./node_modules/typeorm/cli.js schema:sync",
...
}
CLI Options
Option | Default | Description |
---|---|---|
--seed or -s |
null | Option to specify a seeder class to run individually. |
--connection or -c |
null | Name of the typeorm connection. Required if there are multiple connections. |
--configName or -n |
ormconfig.js |
Name to the typeorm config file. |
--root or -r |
process.cwd() |
Path to the typeorm config file. |
❯ Basic Seeder
A seeder class only contains one method by default run
. Within this method, you may insert data into your database. For manually insertion use the Query Builder or use the Entity Factory
Note. The seeder files will be executed alphabetically.
❯ Using Entity Factory
Of course, manually specifying the attributes for each entity seed is cumbersome. Instead, you can use entity factories to conveniently generate large amounts of database records.
For all entities we want to create, we need to define a factory. To do so we give you the awesome faker library as a parameter into your factory. Then create your "fake" entity and return it. Those factory files should be in the src/database/factories
folder and suffixed with .factory
like src/database/factories/user.factory.ts
.
Types | Description |
---|---|
Enity |
TypeORM Enity like the user or the pet in the samples. |
Context |
Argument to pass some static data into the factory function. |
EntityFactory |
This object is used to make new filled entities or create it into the database. |
define
The define function creates a new enity factory.
define:void;
defineUser,
factory
Factory retrieves the defined factory function and returns the EntityFactory to start creating new enities.
factory:EntityFactory<Entity, Context>
factoryPetfactoryPet
EntityFactory
map
Use the .map()
function to alter the generated value before they get persisted.
mapmapFunction:Promise<Entity>: EntityFactory<Entity, Context>
await factoryUser .map .createMany5
make
& makeMany
Make and makeMany executes the factory functions and return a new instance of the given enity. The instance is filled with the generated values from the factory function, but not saved in the database.
overrideParams - Override some of the attributes of the enity.
makeoverrideParams: EntityProperty<Entity> = : Promise<Entity>
await factoryUser.makeawait factoryUser.makeMany10 // override the emailawait factoryUser.makeawait factoryUser.makeMany10,
create
& createMany
the create and createMany method is similar to the make and makeMany method, but at the end the created entity instance gets persisted in the database.
overrideParams - Override some of the attributes of the enity.
createoverrideParams: EntityProperty<Entity> = : Promise<Entity>
await factoryUser.createawait factoryUser.createMany10 // override the emailawait factoryUser.createawait factoryUser.createMany10,
❯ Seeding Data in Testing
The entity factories can also be used in testing. To do so call the useSeeding
function, which loads all the defined entity factories.
Choose your test database wisley. We suggest to run your test in a sqlite in memory database.
However, if the test database is not in memory, than use the --runInBand
flag to disable parallelizes runs.
describe"UserService",
useSeeding
Loads the defined entity factories.
useSeedingoptions: ConfigureOption = : Promise<void>
runSeeder
Runs the given seeder class.
runSeederseed: SeederConstructor: Promise<void>
useRefreshDatabase
Connects to the database, drops it and recreates the schema.
useRefreshDatabaseoptions: ConfigureOption = : Promise<Connection>
tearDownDatabase
Closes the open database connection.
tearDownDatabase: Promise<void>
ConfigureOption
❯ Example Projects
Please fill free to add your open-source project here. This helps others to better understand the seeding technology.
Project | Description |
---|---|
copa-ch/copa-backend | 🚀 Nest application written in TypeScript for the COPA project. This app manages your tournaments and generates the schedules. |