Module de.softwareforge.testing.postgres

Package de.softwareforge.testing.postgres.embedded

Class EmbeddedPostgres.Builder

java.lang.Object

de.softwareforge.testing.postgres.embedded.EmbeddedPostgres.Builder

Enclosing class:

EmbeddedPostgres

public static class EmbeddedPostgres.Builder
extends Object

Creates a new EmbeddedPostgres instance and starts it.

Method Summary

Modifier and Type	Method	Description
EmbeddedPostgres.Builder	addConnectionProperty(String key, String value)	Adds a connection property.
EmbeddedPostgres.Builder	addInitDbConfiguration(String key, String value)	Adds a configuration parameters for the initdb command.
EmbeddedPostgres.Builder	addLocaleConfiguration(String key, String value)	Deprecated. Use addInitDbConfiguration(String, String).
EmbeddedPostgres.Builder	addServerConfiguration(String key, String value)	Adds a server configuration parameter.
EmbeddedPostgres	build()	Creates and boots a new EmbeddedPostgres instance.
EmbeddedPostgres.Builder	setDataDirectory(File dataDirectory)	Explicitly set the location of the data directory.
EmbeddedPostgres.Builder	setDataDirectory(String dataDirectory)	Explicitly set the location of the data directory.
EmbeddedPostgres.Builder	setDataDirectory(Path dataDirectory)	Explicitly set the location of the data directory.
EmbeddedPostgres.Builder	setErrorRedirector(ProcessBuilder.Redirect errRedirector)	Set a ProcessBuilder.Redirect instance to receive stderr output from the spawned processes.
EmbeddedPostgres.Builder	setInstallationBaseDirectory(File installationBaseDirectory)	Sets the directory where the PostgreSQL distribution is unpacked.
EmbeddedPostgres.Builder	setNativeBinaryManager(NativeBinaryManager nativeBinaryManager)	Sets the NativeBinaryManager that provides the location of the postgres installation.
EmbeddedPostgres.Builder	setOutputRedirector(ProcessBuilder.Redirect outRedirector)	Set a ProcessBuilder.Redirect instance to receive stdout output from the spawned processes.
EmbeddedPostgres.Builder	setPort(int port)	Explicitly set the TCP port for the PostgreSQL server.
EmbeddedPostgres.Builder	setRemoveDataOnShutdown(boolean removeDataOnShutdown)	Whether to remove the data directory on server shutdown.
EmbeddedPostgres.Builder	setServerStartupWait(Duration serverStartupWait)	Sets the time that the builder will wait for the PostgreSQL server instance to start.
EmbeddedPostgres.Builder	setServerVersion(String serverVersion)	Set the version of the PostgreSQL server.
EmbeddedPostgres.Builder	useLocalPostgresInstallation(File directory)	Use a locally installed PostgreSQL server for tests.
EmbeddedPostgres.Builder	withDefaults()	Apply a set of defaults to the database server: timezone: UTC synchronous_commit: off max_connections: 300

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

withDefaults

@NonNull
public EmbeddedPostgres.Builder withDefaults()

Apply a set of defaults to the database server:

• timezone: UTC
• synchronous_commit: off
• max_connections: 300

Returns:

The builder itself.

setServerStartupWait

@NonNull
public EmbeddedPostgres.Builder setServerStartupWait(@NonNull
 Duration serverStartupWait)

Sets the time that the builder will wait for the PostgreSQL server instance to start. Default is 10 seconds.

Parameters:

serverStartupWait - Startup wait time. Must not be null or negative.

Returns:

The builder itself.

setRemoveDataOnShutdown

@NonNull
public EmbeddedPostgres.Builder setRemoveDataOnShutdown(boolean removeDataOnShutdown)

Whether to remove the data directory on server shutdown. If true, the contents of the data directory are deleted when the EmbeddedPostgres instance is closed. Default is true.

Parameters:

removeDataOnShutdown - True removes the contents of the data directory on shutdown.

Returns:

The builder itself.

setDataDirectory

@NonNull
public EmbeddedPostgres.Builder setDataDirectory(@NonNull
 Path dataDirectory)

Explicitly set the location of the data directory. Default is using a managed directory.

Parameters:

dataDirectory - The directory to use. Must not be null. If it exists, the current user must be able to access the directory for reading and writing. If the directory does not exist then the current user must be able to create it for reading and writing.

Returns:

The builder itself.

setDataDirectory

@NonNull
public EmbeddedPostgres.Builder setDataDirectory(@NonNull
 String dataDirectory)

Explicitly set the location of the data directory. Default is using a managed directory.

Parameters:

dataDirectory - The directory to use. Must not be null. If it exists, the current user must be able to access the directory for reading and writing. If the directory does not exist then the current user must be able to create it for reading and writing.

Returns:

The builder itself.

setDataDirectory

@NonNull
public EmbeddedPostgres.Builder setDataDirectory(@NonNull
 File dataDirectory)

Explicitly set the location of the data directory. Default is using a managed directory.

Parameters:

dataDirectory - The directory to use. Must not be null. If it exists, the current user must be able to access the directory for reading and writing. If the directory does not exist then the current user must be able to create it for reading and writing.

Returns:

The builder itself.

addServerConfiguration

@NonNull
public EmbeddedPostgres.Builder addServerConfiguration(@NonNull
 String key,
 @NonNull
 String value)

Adds a server configuration parameter. All parameters are passed to the PostgreSQL server a startup using the postgres command.

Values and their function are specific to the PostgreSQL version selected.

See the PostgreSQL runtime configuration for more information.

Parameters:

key - Configuration parameter name. Must not be null.

value - Configuration parameter value. Must not be null.

Returns:

The builder itself.

addLocaleConfiguration

@Deprecated
@NonNull
public EmbeddedPostgres.Builder addLocaleConfiguration(@NonNull
 String key,
 @NonNull
 String value)

Deprecated.

Use addInitDbConfiguration(String, String).

addInitDbConfiguration

@NonNull
public EmbeddedPostgres.Builder addInitDbConfiguration(@NonNull
 String key,
 @NonNull
 String value)

Adds a configuration parameters for the initdb command. The initdb command is used to create the PostgreSQL server.

Each value is added as a command line parameter to the command.

See the PostgreSQL initdb documentation for an overview of possible values.

Parameters:

key - initdb parameter name. Must not be null.

value - initdb parameter value. Must not be null. When the empty string is used as the value, the resulting command line parameter will not have a equal sign and a value assigned.

Returns:

The builder itself.

addConnectionProperty

@NonNull
public EmbeddedPostgres.Builder addConnectionProperty(@NonNull
 String key,
 @NonNull
 String value)

Adds a connection property. These properties are set on every connection handed out by the data source. See the PostgreSQL JDBC driver documentation for possible values.

Parameters:

key - connection property name. Must not be null.

value - connection property value. Must not be null.

Returns:

The builder itself.

setInstallationBaseDirectory

@NonNull
public EmbeddedPostgres.Builder setInstallationBaseDirectory(@NonNull
 File installationBaseDirectory)

Sets the directory where the PostgreSQL distribution is unpacked. Setting the installation base directory resets the NativeBinaryManager used to locate the postgres installation back to the default (which is to download the zonky.io Postgres archive and unpack it in the installation directory. The default is using a managed directory.

Parameters:

installationBaseDirectory - The directory to unpack the postgres distribution. The current user must be able to create and write this directory. Must not be null.

Returns:

The builder itself.

setPort

@NonNull
public EmbeddedPostgres.Builder setPort(int port)

Explicitly set the TCP port for the PostgreSQL server. If the port is not available, starting the server will fail. Default is to find and use an available TCP port.

Parameters:

port - The port to use. Must be > 1023 and < 65536.

Returns:

The builder itself.

setServerVersion

@NonNull
public EmbeddedPostgres.Builder setServerVersion(@NonNull
 String serverVersion)

Set the version of the PostgreSQL server. This value is passed to the default binary manager which will try to resolve this version from existing Maven artifacts. The value is ignored if setNativeBinaryManager(NativeBinaryManager) is called.

Not every PostgreSQL version is supported by pg-embedded. Some older versions lack the necessary options for the command line parameters and will fail at startup. Currently, every version 10 or newer should be working.

Parameters:

serverVersion - A partial or full version. Valid values are e.g. "12" or "11.3".

setErrorRedirector

@NonNull
public EmbeddedPostgres.Builder setErrorRedirector(@NonNull
 ProcessBuilder.Redirect errRedirector)

Set a ProcessBuilder.Redirect instance to receive stderr output from the spawned processes.

Parameters:

errRedirector - a ProcessBuilder.Redirect instance. Must not be null.

Returns:

The builder itself.

setOutputRedirector

@NonNull
public EmbeddedPostgres.Builder setOutputRedirector(@NonNull
 ProcessBuilder.Redirect outRedirector)

Set a ProcessBuilder.Redirect instance to receive stdout output from the spawned processes.

Parameters:

outRedirector - a ProcessBuilder.Redirect instance. Must not be null.

Returns:

The builder itself.

setNativeBinaryManager

@NonNull
public EmbeddedPostgres.Builder setNativeBinaryManager(@NonNull
 NativeBinaryManager nativeBinaryManager)

Sets the NativeBinaryManager that provides the location of the postgres installation. Explicitly setting a binary manager overrides the installation base directory location set with setInstallationBaseDirectory(File) as this is only used by the default binary manager. Calling setInstallationBaseDirectory(File) after this method undoes setting the binary manager.

Parameters:

nativeBinaryManager - A NativeBinaryManager implementation. Must not be null.

Returns:

The builder itself.

useLocalPostgresInstallation

@NonNull
public EmbeddedPostgres.Builder useLocalPostgresInstallation(@NonNull
 File directory)

Use a locally installed PostgreSQL server for tests. The tests will still spin up a new instance and locate the data in the data directory but it will use the locally installed binaries for starting and stopping. Calling this method sets a binary manager, so it overrides setNativeBinaryManager(NativeBinaryManager). Calling this method makes the builder ignore the setInstallationBaseDirectory(File) setting.

Parameters:

directory - A local directory that contains a standard PostgreSQL installation. The directory must exist and read and executable.

Returns:

The builder itself.

build

@NonNull
public EmbeddedPostgres build()
                       throws IOException

Creates and boots a new EmbeddedPostgres instance.

Returns:

A EmbeddedPostgres instance representing a started PostgreSQL server.

Throws:

IOException - If the server could not be installed or started.