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 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.

    • 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.
      Since:
      3.0

    • 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.
      Since:
      3.0

    • 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".
      Returns:
      The builder itself.
      Since:
      3.0

    • setErrorRedirector

      @NonNull public EmbeddedPostgres.Builder setErrorRedirector(@NonNull ProcessBuilder.Redirect errorRedirector)
      Set a ProcessBuilder.Redirect instance to receive stderr output from the spawned processes.
      Parameters:
      errorRedirector - a ProcessBuilder.Redirect instance. Must not be null.
      Returns:
      The builder itself.

    • setOutputRedirector

      @NonNull public EmbeddedPostgres.Builder setOutputRedirector(@NonNull ProcessBuilder.Redirect outputRedirector)
      Set a ProcessBuilder.Redirect instance to receive stdout output from the spawned processes.
      Parameters:
      outputRedirector - 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.
      Since:
      3.0

    • 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.
      Since:
      3.0

    • 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.