integresql

IntegreSQL

IntegreSQL manages isolated PostgreSQL databases for your integration tests.

Overview

Table of Contents

• Background
• Install
  • Install using Docker (preferred)
  • Install locally
• Configuration
• Usage
  • Run using Docker (preferred)
  • Run locally
• Contributing
  • Development setup
  • Development quickstart
• Maintainers
• License

Background

Install

Install using Docker (preferred)

A minimal Docker image containing a pre-built IntegreSQL executable is available at Docker Hub.

docker pull allaboutapps/integresql

Install locally

Installing IntegreSQL locally requires a working Go (1.14 or above) environment. Install the IntegreSQL executable to your Go bin folder:

go get github.com/allaboutapps/integresql/cmd/server

Configuration

IntegreSQL requires little configuration, all of which has to be provided via environment variables (due to the intended usage in a Docker environment). The following settings are available:

Usage

Run using Docker (preferred)

Simply start the IntegreSQL Docker (19.03 or above) container, provide the required environment variables and expose the server port:

docker run -d --name integresql -e INTEGRESQL_PORT=5000 -p 5000:5000 allaboutapps/integresql

IntegreSQL can also be included in your project via Docker Compose (1.25 or above):

version: "3.4"
services:

  # Your main service image
  service:
    depends_on:
      - postgres
      - integresql
    environment:
      PSQL_DBNAME: &PSQL_DBNAME "test" 
      PSQL_USER: &PSQL_USER "test"
      PSQL_PASS: &PSQL_PASS "testpass"
      PSQL_HOST: &PSQL_HOST "postgres"

      # [...] additional main service setup

  integresql:
    image: allaboutapps/integresql:latest
    ports:
      - "5000:5000"
    depends_on:
      - postgres
    environment: 
      PGHOST: *PSQL_HOST
      PGUSER: *PSQL_USER
      PGPASSWORD: *PSQL_PASS

  postgres:
    image: postgres:12.2-alpine
    command: "postgres -c 'shared_buffers=128MB' -c 'fsync=off' -c 'synchronous_commit=off' -c 'full_page_writes=off' -c 'max_connections=100' -c 'client_min_messages=warning'" # not necessarily required, some performance optimization for rapid integration testing, validate parameters for own requirements
    expose:
      - "5432"
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: *PSQL_DBNAME
      POSTGRES_USER: *PSQL_USER
      POSTGRES_PASSWORD: *PSQL_PASS
    volumes:
      - pgvolume:/var/lib/postgresql/data

volumes:
  pgvolume: # declare a named volume to persist DB data

Run locally

Running the IntegreSQL server locally requires configuration via exported environment variables (see below):

export INTEGRESQL_PORT=5000
export PSQL_HOST=127.0.0.1
export PSQL_USER=test
export PSQL_PASS=testpass
integresql

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 IntegreSQL without the Docker setup, please ensure a working Go (1.14 or above) environment has been configured as well as a PostgreSQL instance is available (tested against 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 and start server:

# Execute tests
make test

# Run IntegreSQL server with config from environment
integresql

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