boilingseed

README

BoilingSeed

This is a CLI tool that helps generate database seeding helpers with sqlboiler.

This is a really early release, so while it works (I use it for my projects), it is not super stable YET.

Installation

• Install sqlboiler
• Install your database driver for sqlboiler.
• Generate your models. Link
• Install boilingseed: go get github.com/stephenafamo/boilingseed

Usage

Generate the seeds with:

boilingseed psql 

You can then seed the database like this:

package main

import (
    "context"
    "database/sql"

    "path/to/package/seed"
)

func main() {
    ctx := context.Background()
    db := getDB()
    seeder := seed.Seeder
    seeder.MinJetsToSeed = 1
    seeder.MinLanguagesToSeed = 1
    seeder.MinPilotsToSeed = 1

    err := seeder.Run(ctx, db)
    if err != nil {
      panic(err)
    }
}

Configuration

By defualt the sqlboiler configuration files are used: sqlboiler.toml or json or yaml.

Apart from the standard configuration for SQLBoiler, the only other added configuration is the package name of the generated SQLBoiler models. By default the models subdirectory of the current go module is used.

The program accepts these flags to overwrite any configuration.

• --sqlboiler-models: The package of your generated models. Needed to import them properly in the seeder. DEFAULT: current/go/module/models.
• --config: Configuration file path. DEFAULT: sqlboiler.toml
• --output or -o: The name of the folder to output to. DEFAULT: seeds
• --pkgname or -p: The name you wish to assign to your generated package. DEFAULT: seeds
• --no-context: Were the models generated with no context?. DEFAULT false
• --wipe: Delete the output folder (rm -rf) before generation to ensure sanity. DEFAULT false
• --version: Print the version
• debug or d: Debug mode prints stack traces on error. DEFAULT false

They can also be set in the config file, or as environment variables

NOTE: If you have customized the output folder or pkgname in your sqlboiler config file and you are passing the same file to boilingseed, you should overwrite them using the -o and p flags respectively.

Controlling seeding

Most examples will be demonstrated using the following Postgres schema, structs and variables:

CREATE TABLE pilots (
  id integer NOT NULL,
  name text NOT NULL
);

ALTER TABLE pilots ADD CONSTRAINT pilot_pkey PRIMARY KEY (id);

CREATE TABLE jets (
  id integer NOT NULL,
  pilot_id integer NOT NULL,
  age integer NOT NULL,
  name text NOT NULL,
  color text NOT NULL
);

ALTER TABLE jets ADD CONSTRAINT jet_pkey PRIMARY KEY (id);
ALTER TABLE jets ADD CONSTRAINT jet_pilots_fkey FOREIGN KEY (pilot_id) REFERENCES pilots(id);

CREATE TABLE languages (
  id integer NOT NULL,
  language text NOT NULL
);

ALTER TABLE languages ADD CONSTRAINT language_pkey PRIMARY KEY (id);

-- Join table
CREATE TABLE pilot_languages (
  pilot_id integer NOT NULL,
  language_id integer NOT NULL
);

-- Composite primary key
ALTER TABLE pilot_languages ADD CONSTRAINT pilot_language_pkey PRIMARY KEY (pilot_id, language_id);
ALTER TABLE pilot_languages ADD CONSTRAINT pilot_language_pilots_fkey FOREIGN KEY (pilot_id) REFERENCES pilots(id);
ALTER TABLE pilot_languages ADD CONSTRAINT pilot_language_languages_fkey FOREIGN KEY (language_id) REFERENCES languages(id);

The generated package will define a Seeder struct whose fields control seeding.
The comments help understand what each field does.

type Seeder struct {
	// The minimum number of Jets to seed
	MinJetsToSeed int
	// RandomJet creates a random models.Jet
	// It does not need to add relationships.
	// If one is not set, defaultRandomJet() is used
	RandomJet func() (*models.Jet, error)
	// AfterJetsAdded runs after all Jets are added
	AfterJetsAdded func(ctx context.Context) error
	// defaultJetForeignKeySetter() is used if this is not set
	// setting this means that the xxxPerxxx settings cannot be guaranteed
	JetForeignKeySetter func(i int, o *models.Jet, allPilots models.PilotSlice) error

	// The minimum number of Languages to seed
	MinLanguagesToSeed int
	// RandomLanguage creates a random models.Language
	// It does not need to add relationships.
	// If one is not set, defaultRandomLanguage() is used
	RandomLanguage func() (*models.Language, error)
	// AfterLanguagesAdded runs after all Languages are added
	AfterLanguagesAdded func(ctx context.Context) error

	// The minimum number of PilotLanguages to seed
	MinRelsPerPilotLanguages int

	// The minimum number of Pilots to seed
	MinPilotsToSeed int
	// RandomPilot creates a random models.Pilot
	// It does not need to add relationships.
	// If one is not set, defaultRandomPilot() is used
	RandomPilot func() (*models.Pilot, error)
	// AfterPilotsAdded runs after all Pilots are added
	AfterPilotsAdded func(ctx context.Context) error

	JetsPerPilot int

	// Number of times to retry getting a unique relationship in many-to-many relationships
	Retries int
}

MinXXXToSeed

The MinXXXToSeed variables are used to control how many of each model to seed.

NOTE: The final amount seeded could be more than this because of other variables. For example, if MinJetsToSeed and MinPilotsToSeed are set to 3, but JetsPerPilot is set to 5, then the final number of Jets seeded will be 15 because each of the 3 pilots need 5 jets.

seeder.MinJetsToSeed = 5
seeder.MinLanguagesToSeed = 4
seeder.MinPilotsToSeed = 3

xxxPerXXX

The xxxPerXXX fields are used to control how many one-to-many relationships are added. For example, if you seed a single pliot, it will auto-seed jets related to that pilot.

seeder.JetsPerPilot = 2

MinRelsPerXXX

The MinRelsPerXXX fields are control how many many-to-many relationships are added. In this example, it will try to give each Pilot at least 3 Languages and each Language at least 3 pilots.

Naturally, if there are more pilots than languages, each language will likely have more than 3 pilots.

seeder.MinRelsPerPilotLanguages = 3

RandomXXX

The package has defaultRandomXXX functions that use github.com/volatiletech/randomize. However, for better control you can set custom RandomXXX functions. A single function that randomly generates a model.

The RandomXXX functions do not need to add any relationships to the models.

seeder.RandomPilot = func() (*models.Pilot, error) {
    // Build a random pilot
    // Do not worry about relationships those are auto generaeted by the seeder
    // check out github.com/Pallinder/go-randomdata
}

seeder.RandomJet = func() (*models.Jet, error) {
    // Build a random jet
    // Do not worry about relationships those are auto generaeted by the seeder
    // check out github.com/Pallinder/go-randomdata
}

seeder.RandomLanguage = func() (*models.Language, error) {
    // Build a random language
    // Do not worry about relationships those are auto generaeted by the seeder
    // check out github.com/Pallinder/go-randomdata
}

AfterXXXAdded

The package has default AfterXXXAdded functions that do nothing.

If you'd like to perform any actions after all models of a specific table is added to the database, you can set this field.

seeder.AfterPilotsAdded = func(ctx context.Context) error {
  // Do something
}

seeder.AfterJetsAdded = func(ctx context.Context) error {
  // Do something
}

seeder.AfterLanguagesAdded = func(ctx context.Context) error {
  // Do something
}

xxxForeignKeySetter

After a random model is generated, this function is called to set the foreign keys on the model.

In most cases, you wouldn't have to touch this, the default functions evenly distribute relationships to related models.

seeder.	JetForeignKeySetter func(i int, o *models.Jet, allPilots models.PilotSlice) error {
    o.PilotID = 12345
    return nil
}

Contributing

This still needs some polishing, looking forward to pull requests!