dockerdb

README

dockerdb

This repository contains a package for fast database deployment in Docker container.

Tested Vendors

1. PosgreSQL
2. MySQL

Why dockerdb?

Usage

Download and install it:

go get github.com/egorgasay/dockerdb/v2

Import it in your code:

import "github.com/egorgasay/dockerdb/v2"

The first launch should look like this:

vdb, err := dockerdb.New(ctx, config)
if err != nil {
  log.Fatal(err)
}

If the database was turned off, then you can turn it on using:

err := vdb.Run(ctx)
if err != nil {
  log.Fatal(err)
}

Example

package main

import (
	"context"
	"fmt"
	"log"
	
	"https://github.com/egorgasay/dockerdb/v2"

    _ "github.com/lib/pq"
)

func main() {
	// Specify the data that is needed to run the database
	config := dockerdb.CustomDB{
		DB: dockerdb.DB{
			Name:     "admin",
			User:     "admin",
		Password: "admin",
		},
		Port:   "45217",
		Vendor: dockerdb.Postgres15,
	}
      
	ctx := context.TODO()
	vdb, err := dockerdb.New(ctx, config)
	if err != nil {
		log.Fatal(err)
	}
      
      // testing db is working
	var answer string
	err = vdb.DB.QueryRow("SELECT 'db is up'").Scan(&answer)
	if err != nil {
		log.Fatal(err)
	}
    
	fmt.Println(answer)
    
	if err = vdb.Stop(ctx); err != nil {
		log.Fatal(err)
	}
}

Example 2 (Unimplemented db)

package main

import (
    "context"
	"fmt"
	"log"
	
	"https://github.com/egorgasay/dockerdb"

    _ "github.com/lib/pq"
)

func main() {
	// Specify the data that is needed to run the database
	config := dockerdb.CustomDB{
		DB: dockerdb.DB{
			Name:     "admin",
			User:     "admin",
			Password: "admin",
		},
		Port:   "45217",
		Vendor: "postgres:10",

		PortDocker: "5432/tcp",
		EnvDocker:  []string{"POSTGRES_DB=" + "DBNAME", "POSTGRES_USER=" + "USERNAME",
			"POSTGRES_PASSWORD=" + "PASSWORD"},
	}

	// This will allow you to upload the image to your computer. 
	ctx := context.TODO()
	err := dockerdb.Pull(ctx, "postgres:10")
	if err != nil {
		log.Fatal(err)
	}

	vdb, err := dockerdb.New(ctx, config)
	if err != nil {
		log.Fatal(err)
	}

	// testing db is working
	var answer string
	err = vdb.DB.QueryRow("SELECT 'db is up'").Scan(&answer)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(answer)

	if err = vdb.Stop(ctx); err != nil {
		log.Fatal(err)
	}
	
	fmt.Println("db is down")
}

Documentation

Overview

Package dockerdb allows user to create virtual databases using docker. Tested with PostgreSQL, MySQL, MS SQL.

Index

• Variables
• func Build(conf CustomDB) (connStr string, err error)
• func Pull(ctx context.Context, image DockerHubName) error
• func Run(ctx context.Context, ID string) error
• func SetMaxWaitTime(sec time.Duration)
• type CustomDB
  • func Config() *CustomDB
  • func (c *CustomDB) SetDBPort(port string) *CustomDB
  • func (c *CustomDB) SetEnv(env []string) *CustomDB
  • func (c *CustomDB) SetExposePort(port nat.Port) *CustomDB
  • func (c *CustomDB) SetName(name string) *CustomDB
  • func (c *CustomDB) SetNoSQL() *CustomDB
  • func (c *CustomDB) SetPassword(password string) *CustomDB
  • func (c *CustomDB) SetSQL() *CustomDB
  • func (c *CustomDB) SetSQLConnStr(connString string) *CustomDB
  • func (c *CustomDB) SetUser(user string) *CustomDB
  • func (c *CustomDB) SetVendor(vendor DockerHubName) *CustomDB
• type DB
• type DockerHubName
• type VDB
  • func New(ctx context.Context, conf CustomDB) (*VDB, error)
  • func (ddb *VDB) Clear(ctx context.Context) (err error)
  • func (ddb *VDB) Kill(ctx context.Context, signal string) (err error)
  • func (ddb *VDB) Pause(ctx context.Context) (err error)
  • func (ddb *VDB) Remove(ctx context.Context) (err error)
  • func (ddb *VDB) Restart(ctx context.Context) (err error)
  • func (ddb *VDB) Run(ctx context.Context) (err error)
  • func (ddb *VDB) SQL() (db *sql.DB)
  • func (ddb *VDB) Stop(ctx context.Context) (err error)
  • func (ddb *VDB) Unpause(ctx context.Context) (err error)

Variables

var (
	ErrUnknown     = errors.New("unknown error")
	ErrUnsupported = errors.New("unsupported db vendor")
)

Functions

func Build

func Build(conf CustomDB) (connStr string, err error)

Build builds connection string by CustomDB config.

func Pull

func Pull(ctx context.Context, image DockerHubName) error

Pull pulls an image from net. WARNING!! USE IT CAREFULLY! DOWNLOADING SOME DB IMAGES MAY TAKE SOME TIME. Tested with PostgreSQL, MySQL, MS SQL.

func Run

func Run(ctx context.Context, ID string) error

Run launches a docker container by ID.

func SetMaxWaitTime

func SetMaxWaitTime(sec time.Duration)

Types

type CustomDB

type CustomDB struct {
	DB     DB
	Port   string
	Vendor DockerHubName

	// Optional if you are using a supported vendor
	PortDocker nat.Port
	EnvDocker  []string
	NoSQL      bool
	SQLConnStr string
	// contains filtered or unexported fields
}

func Config

func Config() *CustomDB

func (*CustomDB) SetDBPort

func (c *CustomDB) SetDBPort(port string) *CustomDB

func (*CustomDB) SetEnv

func (c *CustomDB) SetEnv(env []string) *CustomDB

func (*CustomDB) SetExposePort

func (c *CustomDB) SetExposePort(port nat.Port) *CustomDB

func (*CustomDB) SetName

func (c *CustomDB) SetName(name string) *CustomDB

func (*CustomDB) SetNoSQL

func (c *CustomDB) SetNoSQL() *CustomDB

func (*CustomDB) SetPassword

func (c *CustomDB) SetPassword(password string) *CustomDB

func (*CustomDB) SetSQL

func (c *CustomDB) SetSQL() *CustomDB

func (*CustomDB) SetSQLConnStr

func (c *CustomDB) SetSQLConnStr(connString string) *CustomDB

func (*CustomDB) SetUser

func (c *CustomDB) SetUser(user string) *CustomDB

func (*CustomDB) SetVendor

func (c *CustomDB) SetVendor(vendor DockerHubName) *CustomDB

type DB

type DB struct {
	Name     string
	User     string
	Password string
}

type DockerHubName

type DockerHubName string

const (
	Postgres15 DockerHubName = "postgres:15"
	Postgres14 DockerHubName = "postgres:14"
	Postgres13 DockerHubName = "postgres:13"
	Postgres12 DockerHubName = "postgres:12"
	Postgres11 DockerHubName = "postgres:11"

	MySQL5Image DockerHubName = "mysql:5.7"
	MySQL8Image DockerHubName = "mysql:8"
)

type VDB

type VDB struct {
	// contains filtered or unexported fields
}

func New

func New(ctx context.Context, conf CustomDB) (*VDB, error)

New creates a new docker container and launches it

func (*VDB) Clear

func (ddb *VDB) Clear(ctx context.Context) (err error)

Clear kills and removes a container.

func (*VDB) Kill

func (ddb *VDB) Kill(ctx context.Context, signal string) (err error)

Kill kills the docker container.

func (*VDB) Pause

func (ddb *VDB) Pause(ctx context.Context) (err error)

Pause suspends the docker container.

func (*VDB) Remove

func (ddb *VDB) Remove(ctx context.Context) (err error)

Remove removes a container.

func (*VDB) Restart

func (ddb *VDB) Restart(ctx context.Context) (err error)

Restart stops and starts a container again.

func (*VDB) Run

func (ddb *VDB) Run(ctx context.Context) (err error)

Run launches the docker container.

func (*VDB) SQL

func (ddb *VDB) SQL() (db *sql.DB)

SQL returns an *sql.DB instance.

func (*VDB) Stop

func (ddb *VDB) Stop(ctx context.Context) (err error)

Stop stops the docker container.

func (*VDB) Unpause

func (ddb *VDB) Unpause(ctx context.Context) (err error)

Unpause resumes the docker container.