Introduction
Germinator is a database seeding tool.
It reads YAML files that are templated using Handlebars.
It's well suited for:
- Development fixture data to emulate a "production-ish" environment
- Generating real-looking data using random generators (faker.js and chance.js)
- Canonical production data which is not changed by users
- One-off data dumps based on YAML/JSON structures
Germinator has a CLI, a Docker Image and a Node.js API. They all do essentially the same thing.
An example of a germinator seed file:
germinator: v2
# This flag tells germinator if it should UPDATE and DELETE entries
synchronize: true
# Optionally, seeds can respect NODE_ENV
$env: [dev, test, qa]
# Data defined here is passed as template data below the separator
data:
employees: 1000
positions:
- janitor
- chef
- server
---
# A list of all the database rows you want germinator to create
entities:
{{#each positions as |position|}}
- Position:
$id: 'position-{{position}}'
name: {{position}}
{{#repeat @root.employees}}
- Employee:
$id: '{tableName}-{{@index}}-{{position}}'
fullName: {{chance "name"}}
email: {{chance "email"}}
position: { $id: 'position-{{position}}' }
{{/repeat}}
{{/each}}
If we made employees: 10
, germinator would do the following:
insert into `position` (`name`) values ('janitor')
insert into `position` (`name`) values ('chef')
insert into `position` (`name`) values ('server')
insert into `employee` (`full_name`, `position`) values ('Seth Tran', 1)
insert into `employee` (`full_name`, `position`) values ('Isaiah Erickson', 1)
insert into `employee` (`full_name`, `position`) values ('Winifred Barnes', 1)
insert into `employee` (`full_name`, `position`) values ('Scott Collins', 1)
insert into `employee` (`full_name`, `position`) values ('Todd Houston', 1)
insert into `employee` (`full_name`, `position`) values ('Elijah Watson', 1)
insert into `employee` (`full_name`, `position`) values ('Isabelle Anderson', 1)
insert into `employee` (`full_name`, `position`) values ('Jeff Glover', 1)
insert into `employee` (`full_name`, `position`) values ('Ophelia Woods', 1)
insert into `employee` (`full_name`, `position`) values ('Patrick Wilkerson', 1)
insert into `employee` (`full_name`, `position`) values ('Troy Nichols', 2)
insert into `employee` (`full_name`, `position`) values ('Mayme Jones', 2)
insert into `employee` (`full_name`, `position`) values ('David Rice', 2)
insert into `employee` (`full_name`, `position`) values ('Beatrice Lawson', 2)
insert into `employee` (`full_name`, `position`) values ('Daniel Robertson', 2)
insert into `employee` (`full_name`, `position`) values ('Ruth McDonald', 2)
insert into `employee` (`full_name`, `position`) values ('Brian Conner', 2)
insert into `employee` (`full_name`, `position`) values ('Dora Lawrence', 2)
insert into `employee` (`full_name`, `position`) values ('Eugenia Rhodes', 2)
insert into `employee` (`full_name`, `position`) values ('Daniel Nunez', 2)
insert into `employee` (`full_name`, `position`) values ('Alberta Long', 3)
insert into `employee` (`full_name`, `position`) values ('Paul Miller', 3)
insert into `employee` (`full_name`, `position`) values ('Georgie Mathis', 3)
insert into `employee` (`full_name`, `position`) values ('Jean Elliott', 3)
insert into `employee` (`full_name`, `position`) values ('Michael Edwards', 3)
insert into `employee` (`full_name`, `position`) values ('Jay Gomez', 3)
insert into `employee` (`full_name`, `position`) values ('Clifford Cooper', 3)
insert into `employee` (`full_name`, `position`) values ('Lou Fitzgerald', 3)
insert into `employee` (`full_name`, `position`) values ('Samuel Owen', 3)
insert into `employee` (`full_name`, `position`) values ('Kyle Simmons', 3)
Principles
- Seed entries (which map to database rows) should be globally uniquely identifiable via
$id
- Seeds are a collection of these entries, divided into an unordered pool of files
- Insertion order is defined by foreign keys, and otherwise will be resolved optimally
- Seed entries can be marked as "synchronized", which allows them to be edited and deleted
- Seed files should be ergonomic and easy to read, with naming strategy support
Features
- Provides many template helpers to help you write fixtures
- Supports synchronized seeds - easy to add to your server startup
- Supports inter-entry references to auto-populate foreign keys
- Supports environment-specific seeds
- Supports custom
namingStrategy
andtables
mapping
Germinator is ORM and database agnostic. It's usable without Node.js, and is designed to be deployed using Docker.
It's a great solution for one-offs, or for long-lived canonical data.
Other noteable features:
- bcrypt password hashing
- moment.js date handling
- faker and chance libraries for realistic data fixtures
- custom primary key names (default is
id
), and composite IDs