Awesome

IntegreSQL Client Library for Golang

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

Overview

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

Background

See IntegreSQL: Background

Install

Install the IntegreSQL client for Go using go get or by simply importing the library in your testing code (go modules, see below):

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

If you want to take a look on how we integrate IntegreSQL - 🤭 - please just try our go-starter project or take a look at our testing setup code.

In general setting up the IntegreSQL client, initializing a PostgreSQL template (migrate + seed) and retrieving a PostgreSQL test database goes like this:

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
    }

    // compute a hash over all database related files in your workspace (warm template cache)
    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

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

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

Execute project tests:

# Execute tests
make test