Repository files navigation

This project is a fork ofOpenTable Embedded PostgreSQL Component created back in 2018. The originalproject continues, but with a very different philosophy - wrapping the postgres instance in a docker container.Whereas this project follows the original approach of using native postgres binaries running directly on the target platform without the overhead of virtualization.

The library allows embedding PostgreSQL into Java application code with no external dependencies.Excellent for allowing you to unit test with a "real" Postgres without requiring end users to install and set up a database cluster.

If you are usingSpring orSpring Boot framework you can also consider using the following more specializedembedded-database-spring-test project.

• All features ofcom.opentable:otj-pg-embedded:0.13.3
• Configurable version ofPostgreSQL binaries
• PostgreSQL 11+ support even for Linux platform
• Support for running inside Docker, including Alpine Linux

Add the following Maven dependency:

<dependency>    <groupId>io.zonky.test</groupId>    <artifactId>embedded-postgres</artifactId>    <version>2.2.0</version>    <scope>test</scope></dependency>

The default version of the embedded postgres isPostgreSQL 14.20, but you can change it by following the instructions described inPostgres version.

In your JUnit test just add:

@RulepublicSingleInstancePostgresRulepg =EmbeddedPostgresRules.singleInstance();

This simply has JUnit manage an instance of EmbeddedPostgres (start, stop). You can then use this to get a DataSource with:pg.getEmbeddedPostgres().getPostgresDatabase();

Additionally you may use theEmbeddedPostgres class directly by manually starting and stopping the instance; seeEmbeddedPostgresTest for an example.

Default username/password is: postgres/postgres and the default database is 'postgres'

You can easily integrate Flyway or Liquibase database schema migration:

@RulepublicPreparedDbRuledb =EmbeddedPostgresRules.preparedDatabase(FlywayPreparer.forClasspathLocation("db/my-db-schema"));

@RulepublicPreparedDbRuledb =EmbeddedPostgresRules.preparedDatabase(LiquibasePreparer.forClasspathLocation("liqui/master.xml"));

This will create an independent database for every test with the given schema loaded from the classpath.Database templates are used so the time cost is relatively small, given the superior isolation trulyindependent databases gives you.

The default version of the embedded postgres isPostgreSQL 14.20, but it can be changed by importingembedded-postgres-binaries-bom in a required version into your dependency management section.

<dependencyManagement>    <dependencies>        <dependency>            <groupId>io.zonky.test.postgres</groupId>            <artifactId>embedded-postgres-binaries-bom</artifactId>            <version>18.1.0</version>            <type>pom</type>            <scope>import</scope>        </dependency>    </dependencies></dependencyManagement>

A list of all available versions of postgres binaries is here:https://mvnrepository.com/artifact/io.zonky.test.postgres/embedded-postgres-binaries-bom

Note that the release cycle of the postgres binaries is independent of the release cycle of this library, so you can upgrade to a new version of postgres binaries immediately after it is released.

By default, only the support foramd64 architecture is enabled.Support for other architectures can be enabled by adding the corresponding Maven dependencies as shown in the example below.

<dependency>    <groupId>io.zonky.test.postgres</groupId>    <artifactId>embedded-postgres-binaries-linux-i386</artifactId>    <scope>test</scope></dependency>

Supported platforms:Darwin,Windows,Linux,Alpine Linux
Supported architectures:amd64,i386,arm32v6,arm32v7,arm64v8,ppc64le

Note that not all architectures are supported by all platforms, look here for an exhaustive list of all available artifacts:https://mvnrepository.com/artifact/io.zonky.test.postgres

SincePostgreSQL 10.0, there are additional artifacts withalpine-lite suffix. These artifacts contain postgres binaries for Alpine Linux with disabledICU support for further size reduction.

Check the console output for aninitdb: cannot be run as root message. If the error is present, try to upgrade to a newer version of the library (1.2.8+), or ensure the build process to be running as a non-root user.

If the error is not present, try to clean up the/tmp/embedded-pg/PG-XYZ directory containing temporary binaries of the embedded database.

You probably need to installMicrosoft Visual C++ 2013 Redistributable Package. The version 2013 is important, installation of other versions will not help. More detailed is the problem discussedhere.

Running builds inside a Docker container is fully supported, including Alpine Linux. However, PostgreSQL has a restriction the database process must run under a non-root user. Otherwise, the database does not start and fails with an error.

So be sure to use a docker image that uses a non-root user. Or, since version1.2.8 you can run the docker container with--privileged option, which allows taking advantage ofunshare command to run the database process in a separate namespace.

Below are some examples of how to prepare a docker image running with a non-root user:

FROM openjdk:8-jdkRUN groupadd --system --gid 1000 testRUN useradd --system --gid test --uid 1000 --shell /bin/bash --create-home testUSER testWORKDIR /home/test

FROM openjdk:8-jdk-alpineRUN addgroup -S -g 1000 testRUN adduser -D -S -G test -u 1000 -s /bin/ash testUSER testWORKDIR /home/test

[[runners]]  executor = "docker"  [runners.docker]    privileged = true

If the above do not resolve your error, verify that the correct locales are available in your container. For example, many variants of AlmaLinux:9 do not come withglibc-langpack-en. This will lead to misleading errors duringinitdb. Additionally, you can optionally set your locale withsetLocaleConfig() when building your EmbeddedPostgres instance.

The project is released under version 2.0 of theApache License.