knex-seeder

Knex tool for seeding massive amount of fake data into a database.

Table of topics

1. Get started
2. Installation
3. Basic configuration
4. Examples
5. API
6. Database connections
7. Be a contributor
8. Get updated
9. Licence
10. Further help

About

This tool incorporates Faker.js for generating massive amounts of fake data. As knex-seeder is built in top of Knex.js module,it is possible to use the functions for creating and seeding tables.

Get Started

Installation

For development

git clone https://github.com/2rhop/knex-seeder.git ks
cd ks
npm install

For production

npm install knex-seeder --save

Configuration

Its important to know that knex-seeder loads all database configurations from a knexfile.js file located in your relative path, you can get more info about this file here or just copy this code snippet:

module.exports = {
    development: {
        client: 'database_client',
        connection: {
            host: '127.0.0.1',
            user: 'your_database_user',
            password: 'your_database_password',
            database: 'your_database_name',
            port: 'database_client_port'
        }
    }
    production: {
        client: 'pg',
        connection: process.env.DATABASE_URL || { user: 'me', database: 'my_app' }
    }
}

Note: To switch between environments you need to change the value of the NODE_ENV variable:

process.env.NODE_ENV = 'development' | 'production'

Examples

Note: All the example scripts are located in /examples/. . . folder.

• First we are going to see how to create a FieldModel: (e.g here)

const ks = require('knex-seeder')

var myFieldModel = new ks.FieldModelBuilder({
    
    fieldName : [1, 2, 5, 6, 7],//chooses an element in the array
    
    fieldName : new ks.SeedFaker('name.findName','en')//calls the faker.js function for [name.findName] with lang [english]
    
    fieldName : new ks.SeedFaker(ks.FAKER.NAME,ks.LANG.ENGLISH)//or call the faker.js functions with some predefine constants by kenex-seeder
    
    fieldName : new ks.SeedRange(2, 60),//chooses a random value in the range [2, 60]
    
    fieldName : 7,//chooses only this element for the seeding
    
    fieldName : 'Ingrid',//chooses only this element for the seeding

    fieldName : [true, false],//seeds randomly with TRUE or FALSE

    fieldName : new Date(),//seeds the table with the actual date
    
    fieldName : ()=>{//uses this fn for the seeding
      var gender = ['M', 'F'];
      var index = Math.floor(Math.random() * c.length);
      return gender[index];
    }
    
    //you can add more fields here
    ...
    
}).build;

...

And also how to create a TableModel:

...

var tableName = 'myTable'
var myTableModel = new ks.TableModelBuilder(tableName, myFieldModel).build;

Note: Notice the use of Builder Pattern to create the TableModel and FieldModel, reason why before pass it as an argument you must call .build getter to construct the Object.

• You can use the Knex functions inside knex-seeder to create a new table and also chain multiple tables creations: ( e.g. here )

const ks=require('knex-seeder')

ks.createTable(myTableModel, (table) => {
//here you can especify the fields for the first table
       table.increments();
       table.string('name');
       table.integer('role_id');
       table.timestamps(true,true);

       ...

    }).then(() => {//do chainning...
           ks.createTableAndClose(myTableModel2, (table) => {
           //here you can especify the fields for the second table
                table.increments();
                table.string('name');

                ...

            }).then(() => {
            //do something after here...
    });
});

Or you can omit the use of the knex.js function to create a new table and let knex-seeder to do that for you:

...

ks.createTable(myTableModel).then(() => {//do chainning...
           ks.createTableAndClose(myTableModel2).then(() => {
            //do something after here...
    });
});

Note: The function createTable() returns a Promise after creation is done and the function createTableAndClose() also closes the connection. The last one is useful for calling it at the end of a chainning.

• Also with knex-seeder you can (of course) seed tables in a database: ( e.g. here )

const ks = require('knex-seeder')

const queries = 10;

ks.Seeder.seedAndClose(myTableModel, queries).then(() => {
    //do something after...
})

• We have seen how to create a table and how to seed it, but how about do both at the same time, well here is a piece of code to show you how to do that: ( e.g. here )

const ks = require('knex-seeder')

//creating and seeding process
ks.createAndSeed(myTableModel, 10, (table) => {
    table.increments(),
        table.integer('age'),
        table.string('name'),
        table.string('country'),
        ...
        table.string('gender'),
        table.timestamps(true, true)
}).then(() => {
    ks.createAndSeed_close(myTableModel2, 10, (table) => {//closes the connection after process
        table.increments(),
            table.string('name'),
            table.string('category'),
            ...
            table.timestamps(true, true)
    })
}).then(() => {
    //do something after...
})

or omitting the knex.js function to create automatically the table

...

//creating and seeding process
ks.createAndSeed(myTableModel, 10).then(() => {
    ks.createAndSeed_close(myTableModel2, 10).then(() => {
    //do something after...
})

Note: If you forget how to create a Model, see the first example from above.

API

Belongs to	Function	Description
knex-seeder	createAndSeed(TableModelBuilder, number, ?function) : Promise	Creates a table and seed it after (does not close the connection)
	createAndSeed_close(TableModelBuilder, number, ?function) : Promise	Creates a table and seed it after (closes the connection)
	close() : Promise	Closes the connection to the database
knex-seeder.Schema	createTable(TableModelBuilder, ?function) : Promise	Creates a table (does not close the connection)
	createTableAndClose(TableModelBuilder, ?function) : Promise	Creates a table (closes the connection)
	existTable(string) : Boolean	Returns true if the table exists, otherwise returns false
knex-seeder.Seeder	seed(TableModelBuilder, number) : Promise	Seed the table with your TableModel properties(does not close the connection)
	seedAndClose(TableModelBuilder, number) : Promise	Seed the table with your TableModel properties (closes the connection)
knex-seeder.Generator	getGeneratedModel(FieldModelBuilder) : object	Returns an object with all the correct fake values for seeding

Note: If you wanna use the knex.js api, just import knex variable from knex-seeder, just like this:

const { knex } = require('knex-seeder')

or do this instead:

const ks = require('knex-seeder')

const knex = ks.knex;

Connections

To integrate this tool with a database connection you need to install the appropriate package:

• npm install pg
• npm install mysql
• npm install mysql2
• npm install mariasql
• npm install strong-oracle
• npm install oracle
• npm install mssql
• npm install sqlite3

Support

Contributing

All the unit tests are written with Jasmine. Feel free to add more functionalities and bug fixes but also add a test for each of them. Just type npm test, but before that you need to install Jasmine globally.

npm install -g jasmine

Also remember to update the CHANGELOG.md file with your modifications on this tool.

Changelog

Get update with all new versions here

Licence

Copyright (c) 2018 Rene Ricardo. Licensed under the MIT license.

Help

Send me an email or a tweet if you have some doubt or just add an issue