drydock

README

Drydock

This code is an experimental library for running PostgreSQL in Docker during unit tests.

Idea

The basic idea behind this code is this

• You want to run unit tests against a PostgreSQL database
• You want to do all the setup and teardown in the unit test
• You have docker installed, you might as well use it

Example

import (
    "github.com/borud/drydock"
    "github.com/stretchr/testify/assert"
)

func TestSomething(t *testing.T) {
     // This fires up a Docker container with postgres.  You can
     // run multiple of these concurrently since this creates a
     // new container, listening to a unique port.  New will wait
     // until the database responds or the operation times out
     // before responding.
     dd, err := drydock.New("postgres:13")
     assert.Nil(t, err)

     // Ask the unit test framework to clean up once the test
     // is done.  If the test crashes this might end up not
     // running, so there may be docker containers still running.
     // These will have names that start with "drydock-".
     t.Cleanup(func() { dd.Terminate() })

     // Start the container
     err = dd.Start()
     assert.Nil(t, err)

     // This creates a new database inside the postgres instance
     // and returns a connection to it.  Or rather, a *sqlx.DB.
     // The idea being that every time you ask for a new DB and
     // connection, you want to have a clean database so you can
     // know the state.
    db, err := dd.NewDBConn()
    assert.Nil(t, err)

    // We can then do our database things. 
    _, err = db.Exec("CREATE TABLE foo (id INTEGER NOT NULL)")
    assert.Nil(t, err)

    stmt, err := db.Preparex("INSERT INTO foo (id) VALUES ($1)")
    assert.Nil(t, err)

    for i := 0; i < 10; i++ {
        _, err := stmt.Exec(i)
        assert.Nil(t, err)
    }

    // We don't bother cleaning up after ourselves since
    // the container gets nuked anyway.
}

Where to take this?

This seems to work pretty well. The container tends to come up in about 500ms on my machine, and PostgreSQL then needs another 2500ms or so before it is ready to serve requests.

I should be doable to make this somewhat generic, so that it can work for a wider range of databases, and perhaps too things that are not databases. What other scenarios would it be nice to make use of ephemeral docker containers.

I haven't really figured out the cleanup phase yet. If we kill the test before it shuts down the docker container will remain and needs to be removed manually. There are several ways we could try to solve that.

There is also the question of "do we need this?". It might be cleaner to manage docker containers for unit testing in the build system. But being able to do this directly from the tests is somewhat enticing in its immediacy and simplicity.

If you find this idea interesting, please do not hesitate to grab the code and play with it. Let me know if you do something interesting with it.

Documentation

Overview

Package drydock implements a way to run unit tests against a PostgreSQL database if you have docker installed.

import (
    "github.com/borud/drydock"
    "github.com/stretchr/testify/assert"
)

func TestSomething(t *testing.T) {
     // This fires up a Docker container with postgres.  You can
     // run multiple of these concurrently since this creates a
     // new container, listening to a unique port.  New will wait
     // until the database responds or the operation times out
     // before responding.
     dd, err := drydock.New("postgres:13")
     assert.Nil(t, err)

     // Ask the unit test framework to clean up once the test
     // is done.  If the test crashes this might end up not
     // running, so there may be docker containers still running.
     // These will have names that start with "drydock-".
     t.Cleanup(func() { dd.Terminate() })

     // Start the container
     err = dd.Start()
     assert.Nil(t, err)

     // This creates a new database inside the postgres instance
     // and returns a connection to it.  Or rather, a *sqlx.DB.
     // The idea being that every time you ask for a new DB and
     // connection, you want to have a clean database so you can
     // know the state.
    db, err := dd.NewDBConn()
    assert.Nil(t, err)

    // We can then do our database things.
    _, err = db.Exec("CREATE TABLE foo (id INTEGER NOT NULL)")
    assert.Nil(t, err)

    stmt, err := db.Preparex("INSERT INTO foo (id) VALUES ($1)")
    assert.Nil(t, err)

    for i := 0; i < 10; i++ {
        _, err := stmt.Exec(i)
        assert.Nil(t, err)
    }

    // We don't bother cleaning up after ourselves since
    // the container gets nuked anyway.
}

Index

• type Drydock
  • func New(image string) (*Drydock, error)
  • func (d *Drydock) NewDB() (string, error)
  • func (d *Drydock) NewDBConn() (*sqlx.DB, error)
  • func (d *Drydock) Start() error
  • func (d *Drydock) Terminate()

Types

type Drydock

type Drydock struct {
	// Image is the docker image given by repository and tag, eg. "postgres:13"
	Image string

	// DataDir is the directory where the data files live during the test
	DataDir string

	// Port is a randomly allocated free port that is used by the database instance
	Port int

	// Password of the PostgreSQL database
	Password string
	// contains filtered or unexported fields
}

Drydock represents a database drydock

func New

func New(image string) (*Drydock, error)

New creates a new Drydock instance. Returns a *Drydock and a nil error if successful, otherwise a nil *Drydock and an error

func (*Drydock) NewDB

func (d *Drydock) NewDB() (string, error)

NewDB creates a new database and returns the name

func (*Drydock) NewDBConn

func (d *Drydock) NewDBConn() (*sqlx.DB, error)

NewDBConn creates a new database and returns a client connection to it.

func (*Drydock) Start

func (d *Drydock) Start() error

Start the drydock. Will pull the image if we do not have it locally before starting the container.

func (*Drydock) Terminate

func (d *Drydock) Terminate()

Terminate removes the container, nukes the data directories and closes the docker client.