integresql

README

IntegreSQL Client Library for Golang

Client library for interacting with a IntegreSQL server, managing isolated PostgreSQL databases for your integration tests.

Overview

Table of Contents

• Background
• Install
• Configuration
• Usage
• Contributing
  • Development setup
  • Development quickstart
• Maintainers
• License

Background

Install

Install the IntegreSQL client for Go using go get:

go get github.com/allaboutapps/integresql-client-go

Configuration

The IntegreSQL client library requires little configuration which can either be passed via the ClientConfig struct or parsed from environment variables automatically. The following settings are available:

Description	Environment variable	Default	Required
IntegreSQL: base URL of server http://127.0.0.1:5000/api	INTEGRESQL_CLIENT_BASE_URL	"http://integresql:5000/api"
IntegreSQL: API version of server	INTEGRESQL_CLIENT_API_VERSION	"v1"

Usage

Setting up the IntegreSQL client, initializing a template and retrieving a test database:

package yourpkg

import (
    "github.com/allaboutapps/integresql-client-go"
    "github.com/allaboutapps/integresql-client-go/pkg/util"
)

func doStuff() error {
    c, err := integresql.DefaultClientFromEnv()
    if err != nil {
        return err
    }

    hash, err := hash.GetTemplateHash("/app/scripts/migrations", "/app/internal/fixtures/fixtures.go")
    if err != nil {
        return err
    }

    template, err := c.InitializeTemplate(context.TODO(), hash)
    if err != nil {
        return err
    }

    // Use template database config received to initialize template, e.g. by applying migrations and fixtures

    if err := c.FinalizeTemplate(context.TODO(), hash); err != nil {
        return err
    }

    test, err := c.GetTestDatabase(context.TODO(), hash)
    if err != nil {
        return err
    }

    // Use test database config received to run integration tests in isolated DB
}

A very basic example has been added as the cmd/cli executable, you can build it using make cli and execute integresql-cli afterwards.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Development setup

IntegreSQL requires the following local setup for development:

• Docker CE (19.03 or above)
• Docker Compose (1.25 or above)

The project makes use of the devcontainer functionality provided by Visual Studio Code so no local installation of a Go compiler is required when using VSCode as an IDE.

Should you prefer to develop the IntegreSQL client library without the Docker setup, please ensure a working Go (1.14 or above) environment has been configured as well as an IntegreSQL server and a a PostgreSQL instance are available (tested against PostgreSQL version 12 or above, but should be compatible to lower versions) and the appropriate environment variables have been configured as described in the Install section.

Development quickstart

1. Start the local docker-compose setup and open an interactive shell in the development container:

# Build the development Docker container, start it and open a shell
./docker-helper.sh --up

1. Initialize the project, downloading all dependencies and tools required (executed within the dev container):

# Init dependencies/tools
make init

# Build executable (generate, format, build, vet)
make

1. Execute project tests:

# Execute tests
make test

Maintainers

• Nick Müller - @MorpheusXAUT
• Mario Ranftl - @majodev

License

MIT © 2020 aaa – all about apps GmbH | Nick Müller | Mario Ranftl and the IntegreSQL project contributors

Documentation

Index

• Variables
• type Client
  • func DefaultClientFromEnv() (*Client, error)
  • func NewClient(config ClientConfig) (*Client, error)
  • func (c *Client) DiscardTemplate(ctx context.Context, hash string) error
  • func (c *Client) FinalizeTemplate(ctx context.Context, hash string) error
  • func (c *Client) GetTestDatabase(ctx context.Context, hash string) (models.TestDatabase, error)
  • func (c *Client) InitializeTemplate(ctx context.Context, hash string) (models.TemplateDatabase, error)
  • func (c *Client) ResetAllTracking(ctx context.Context) error
  • func (c *Client) ReturnTestDatabase(ctx context.Context, hash string, id int) error
  • func (c *Client) SetupTemplate(ctx context.Context, hash string, init func(conn string) error) error
  • func (c *Client) SetupTemplateWithDBClient(ctx context.Context, hash string, init func(db *sql.DB) error) error
• type ClientConfig
  • func DefaultClientConfigFromEnv() ClientConfig

Variables

var (
	ErrManagerNotReady            = errors.New("manager not ready")
	ErrTemplateAlreadyInitialized = errors.New("template is already initialized")
	ErrTemplateNotFound           = errors.New("template not found")
	ErrDatabaseDiscarded          = errors.New("database was discarded (typically failed during initialize/finalize)")
	ErrTestNotFound               = errors.New("test database not found")
)

Types

type Client

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

func DefaultClientFromEnv

func DefaultClientFromEnv() (*Client, error)

func NewClient

func NewClient(config ClientConfig) (*Client, error)

func (*Client) DiscardTemplate

func (c *Client) DiscardTemplate(ctx context.Context, hash string) error

func (*Client) FinalizeTemplate

func (c *Client) FinalizeTemplate(ctx context.Context, hash string) error

func (*Client) GetTestDatabase

func (c *Client) GetTestDatabase(ctx context.Context, hash string) (models.TestDatabase, error)

func (*Client) InitializeTemplate

func (c *Client) InitializeTemplate(ctx context.Context, hash string) (models.TemplateDatabase, error)

func (*Client) ResetAllTracking

func (c *Client) ResetAllTracking(ctx context.Context) error

func (*Client) ReturnTestDatabase

func (c *Client) ReturnTestDatabase(ctx context.Context, hash string, id int) error

func (*Client) SetupTemplate

func (c *Client) SetupTemplate(ctx context.Context, hash string, init func(conn string) error) error

func (*Client) SetupTemplateWithDBClient

func (c *Client) SetupTemplateWithDBClient(ctx context.Context, hash string, init func(db *sql.DB) error) error

type ClientConfig

type ClientConfig struct {
	BaseURL    string
	APIVersion string
}

func DefaultClientConfigFromEnv

func DefaultClientConfigFromEnv() ClientConfig