Snapshot Utilities for PostgreSQL

This library provides Java wrappers to run pg_dump and pg_restore on platforms that do not have this binary installed. We build on top of Testcontainers to spin-up a temporary Docker container that executes the command.

Usage

Add the following Maven dependency to your project:

<dependency>
    <groupId>de.cronn</groupId>
    <artifactId>postgres-snapshot-util</artifactId>
    <version>1.3.3</version>
</dependency>

Simple Schema Dump

String jdbcUrl = "jdbc:postgresql://localhost/my-db";
String schemaDump = PostgresDump.dumpToString(jdbcUrl, "user", "password",
                                              PostgresDumpOption.NO_COMMENTS,
                                              PostgresDumpOption.SCHEMA_ONLY);

Dump and Restore

Path dumpFile = Path.of("/path/to/dump.tar");
String jdbcUrl = "jdbc:postgresql://localhost/my-db";
PostgresDump.dumpToFile(dumpFile, jdbcUrl, "user", "pass", PostgresDumpFormat.TAR);

PostgresRestore.restoreFromFile(dumpFile, jdbcUrl, "user", "pass",
                                PostgresRestoreOption.CLEAN,
                                PostgresRestoreOption.EXIT_ON_ERROR,
                                PostgresRestoreOption.SINGLE_TRANSACTION);

Connect to PostgreSQL using Docker network alias

PostgresDump and PostgresRestore implement a mechanism to connect to a PostgreSQL database that is running in a Docker container by using the network alias. This allows for seamless interaction without the need to expose ports to the host machine or rewriting the JDBC URL.

Example:

Consider the following simple docker-compose.yml file:

services:
  postgres-db:
    image: postgres:17
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: my-db

In this setup the PostgreSQL service is named postgres-db.

PostgresDump and PostgresRestore can connect to the database by using the Docker network alias postgres-db:

String jdbcUrl = "jdbc:postgresql://postgres-db/my-db";
String schemaDump = PostgresDump.dumpToString(jdbcUrl, "user", "password");

Use Cases

Integration / Regression Test

PostgresDump was designed to be used in a JUnit (regression) tests to dump and compare the actual database schema of an application in cases where the schema is managed by a library/framework such as Liquibase. We recommend to use our validation-file-assertions library to write such a test.

Full example:

@SpringBootTest
@Testcontainers
class SchemaTest implements JUnit5ValidationFileAssertions {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17.0");

    @Test
    void schemaExport() {
        String schema = PostgresDump.dumpToString(postgres.getJdbcUrl(),
                                                  postgres.getUsername(),
                                                  postgres.getPassword(),
                                                  PostgresDumpOption.SCHEMA_ONLY);
        assertWithFile(schema);
    }
}

Requirements

• Java 17+
• Docker