goose-docker

Docker configuration for the pressly/goose migration tool.

Based on ideas of the gomicro/docker-goose repository. Features:

• No need to create your own Dockerfile (but you still may);
• goose env vars are used;
• docker compose usage;
• all goose commands are available, not only up;
• an image with a gopher in a goose costume in a box is even worse than an image with a gopher in a goose costume.

Pure goose command wrapper

Looking for a pure goose wrapper with no sugar around?

👉 Check out the command wrapper mode document.

What's the difference?

The pure command wrapper uses a goose command as a docker's entrypoint instead of the entrypoint.sh script:

ENTRYPOINT ["/bin/goose"]

This allows you to get a full control what are you passing to the goose command, for example:

docker run --rm -v ./migrations:/migrations \
     -e GOOSE_MIGRATION_DIR="/migrations" \
     -e GOOSE_DRIVER="postgres" \
     ghcr.io/kukymbr/goose-docker-cmd:v3.27.1 \
     create my_new_feature sql

or:

docker run --rm -v ./migrations:/migrations \
     ghcr.io/kukymbr/goose-docker-cmd:v3.27.1 \
     -dir="/migrations" postgres "user=postgres dbname=postgres sslmode=disable" up-to 20230607203836

Usage

Image Environment Variables

The image supports the following environment variables:

Variable	Required	Description	Default value
GOOSE_DRIVER	✅	this should specify the database driver (e.g., postgres)	none
GOOSE_DBSTRING	✅	specify the database connection parameters in this variable (e.g., host=localhost port=5432 user=postgres password=postgres dbname=postgres)	none
GOOSE_COMMAND		the goose command to execute	up
GOOSE_COMMAND_ARG		argument for the goose command, for example, the VERSION argument for the up-to/down-to commands	none
GOOSE_EXTRA_ARGS		additional goose arguments, for example GOOSE_EXTRA_ARGS="-table=_db_version -allow-missing"	none
GOOSE_VERBOSE		if set to true, goose will be executed with the -v flag	false

See the goose usage for available drivers, format of the connection string and available commands.

.env file for a goose

To pass environment variables to the goose via the .env file (available in goose since v3.24.0, see the goose doc for info), mount .env file to the /goose-docker directory, for example:

docker run --rm -v ./migrations:/migrations -v my_goose.env:/goose-docker/.env --network host \
  -e GOOSE_DRIVER="postgres" \
  -e GOOSE_DBSTRING="host=localhost port=5432 user=postgres password=postgres dbname=postgres" \
  ghcr.io/kukymbr/goose-docker:3.27.1

Migration Files Directory

The image expects the /migrations directory to be mounted to the container, and it should contain your migration files.

Example Usage

For example, pure docker call:

docker run --rm -v ./migrations:/migrations --network host \
  -e GOOSE_DRIVER="postgres" \
  -e GOOSE_DBSTRING="host=localhost port=5432 user=postgres password=postgres dbname=postgres" \
  ghcr.io/kukymbr/goose-docker:3.27.1

Example with up-to command:

docker run --rm -v ./migrations:/migrations --network host \
  -e GOOSE_COMMAND="up-to" \
  -e GOOSE_COMMAND_ARG="20230607203836" \
  -e GOOSE_DRIVER="postgres" \
  -e GOOSE_DBSTRING="host=localhost port=5432 user=postgres password=postgres dbname=postgres" \
  ghcr.io/kukymbr/goose-docker:3.27.1

Example with create command (works since v3.20.0):

docker run --rm -v ./migrations:/migrations \
  -e GOOSE_COMMAND="create" \
  -e GOOSE_COMMAND_ARG="my_new_migration_name sql" \
  ghcr.io/kukymbr/goose-docker:v3.27.1

docker compose

Docker compose example:

services:
  # ... Add your DB service

  migrations:
    image: ghcr.io/kukymbr/goose-docker:3.27.1
    environment:
      - GOOSE_DRIVER=postgres
      - GOOSE_DBSTRING=host=postgres port=5432 user=postgres password=postgres dbname=postgres
    volumes:
      - ./migrations:/migrations

See the compose.yml file for the full example. Also, the tests/compose.yml file contains an example of usage with multiple databases.

Overriding the environment variables

If you need to dynamically override the environment values provided in the docker compose or in the .env files, add these variables into the environment section with a placeholder as a value, for example:

migrations:
  # ...
  environment:
    - GOOSE_COMMAND=${GOOSE_COMMAND}
    - GOOSE_COMMAND_ARG=${GOOSE_COMMAND_ARG}

When you can override the values:

GOOSE_COMMAND="create" GOOSE_COMMAND_ARG="test_migration sql" docker compose run --rm migrations

Embedding migrations files

If you don't want or can't add migration files as a volume, create a Dockerfile extending the goose-docker image and add your files into it:

FROM ghcr.io/kukymbr/goose-docker:3.27.1

ADD /path/to/migrations /migrations

Then build it and use it instead of the goose-docker image as usual.

amd64/arm64 architecture

The ARM64 architecture support is added since the v3.23.0.

The latest tag notice

The latest tag of this image points to the latest commit to the main branch and not supposed to be used in the production. Always specify a semver tag for production use.

Contributing

Please refer the CONTRIBUTING.md for contribution info.

License

MIT licensed.