Test.Sandwich.Contexts.PostgreSQL

This module provides tools for introducing PostgreSQL databases, either via a container (Docker or Podman) or via a raw process (typically obtaining the binary from Nix).

The container method is traditional, but the raw method can be nice because it tends to leave less junk on the system such as container images, networks, and volumes.

A note about raw processes and random TCP ports: starting a Postgres process on a randomly chosen port is tricky, because Postgres currently lacks a setting for choosing its own port and reporting it back to us. So, the only way to start it on a random TCP port is to first manually find a free port on the system and then start Postgres with it. Since this procedure is inherently racy, it can cause failures if your tests are starting lots of Postgres instances (or other network-using processes) in parallel. This module takes a different approach: it starts the Postgres instance on a Unix socket, which can never fail. You can connect to it via the Unix socket directly if you like. If you use the TCP-based methods like introducePostgresViaNix, they will open a TCP socket inside the test process and then run a proxy to forward packets to the Postgres server's Unix socket.

Raw PostgreSQL via Nix (TCP socket)

introducePostgresViaNix

Arguments

:: (HasBaseContext context, HasNixContext context, MonadUnliftIO m, MonadMask m)

=> PostgresNixOptions

Options

-> SpecFree (LabelValue "postgres" PostgresContext :> context) m ()

-> SpecFree context m ()

Introduce a PostgreSQL instance, using a suitable package from Nix.

withPostgresViaNix

Arguments

:: (HasBaseContextMonad context m, HasNixContext context, MonadUnliftIO m, MonadMask m, MonadFail m, MonadLogger m)

=> PostgresNixOptions

Options

-> (PostgresContext -> m a)

-> m a

Bracket-style variant of introducePostgresViaNix.

Raw PostgreSQL via Nix (Unix socket)

introducePostgresUnixSocketViaNix

Arguments

:: (HasBaseContext context, HasNixContext context, MonadUnliftIO m, MonadMask m)

=> PostgresNixOptions

Options

-> SpecFree (LabelValue "postgres" PostgresContext :> context) m ()

-> SpecFree context m ()

Same as introducePostgresViaNix, but the postgresAddress of the PostgresContext will be a Unix socket.

withPostgresUnixSocketViaNix

Arguments

:: (HasBaseContextMonad context m, HasNixContext context, MonadUnliftIO m, MonadFail m, MonadMask m, MonadLogger m)

=> PostgresNixOptions

Options

-> (FilePath -> m a)

-> m a

Bracket-style variant of introducePostgresUnixSocketViaNix.

Containerized PostgreSQL

introducePostgresViaContainer

Arguments

:: (HasBaseContext context, MonadUnliftIO m, MonadMask m)

=> PostgresContainerOptions

Options

-> SpecFree (LabelValue "postgres" PostgresContext :> context) m ()

-> SpecFree context m ()

Introduce a PostgresSQL instance via a container (either Docker or Podman).

withPostgresContainer

Arguments

:: (HasCallStack, MonadUnliftIO m, MonadLoggerIO m, MonadMask m, HasBaseContextMonad context m)

=> PostgresContainerOptions

Options

-> (PostgresContext -> m a)

-> m a

Bracket-style variant of introducePostgresViaContainer.

Types

data PostgresNixOptions

Constructors

PostgresNixOptions

Fields

• postgresNixPostgres :: Text

  Postgres version to use within the Nixpkgs snapshot of your NixContext. Defaults to "postgresql", but you can pick specific versions like postgresql_15. See <nixpkgs>/top-level/all-packages.nix for the available versions in your snapshot.

• postgresNixUsername :: Text

  Postgres username. Default to postgres.

• postgresNixPassword :: Text

  Postgres password. Default to postgres.

• postgresNixDatabase :: Text

  Postgres default database. The postgres database is always created, but you can create an additional one here. Defaults to test.

defaultPostgresNixOptions :: PostgresNixOptions

postgres :: Label "postgres" PostgresContext

data PostgresContext

Constructors

PostgresContext

Fields

• postgresUsername :: Text
• postgresPassword :: Text
• postgresDatabase :: Text
• postgresAddress :: NetworkAddress
• postgresConnString :: Text
• postgresContainerAddress :: Maybe NetworkAddress

  The address of the database server within its container (if it was started using a container). Useful when the test is also in a container, and containers are networked together.

Instances

Show PostgresContext

Defined in Test.Sandwich.Contexts.PostgreSQL

Methods

showsPrec :: Int -> PostgresContext -> ShowS

show :: PostgresContext -> String

showList :: [PostgresContext] -> ShowS

data PostgresContainerOptions

Constructors

PostgresContainerOptions

Fields

• postgresContainerUser :: Text
• postgresContainerPassword :: Text
• postgresContainerLabels :: Map Text Text
• postgresContainerContainerName :: Maybe Text
• postgresContainerContainerSystem :: ContainerSystem
• postgresContainerImage :: Text

Instances

Show PostgresContainerOptions

Defined in Test.Sandwich.Contexts.PostgreSQL

Methods

showsPrec :: Int -> PostgresContainerOptions -> ShowS

show :: PostgresContainerOptions -> String

showList :: [PostgresContainerOptions] -> ShowS

Eq PostgresContainerOptions

Defined in Test.Sandwich.Contexts.PostgreSQL

Methods

(==) :: PostgresContainerOptions -> PostgresContainerOptions -> Bool

(/=) :: PostgresContainerOptions -> PostgresContainerOptions -> Bool

defaultPostgresContainerOptions :: PostgresContainerOptions

Re-exports

data NetworkAddress

Constructors

NetworkAddressTCP

Fields

• networkAddressTcpHostname :: String
• networkAddressTcpPort :: PortNumber

NetworkAddressUnix

Fields

• networkAddressUnixPath :: String

Instances

Show NetworkAddress

Defined in Test.Sandwich.Contexts.Types.Network

Methods

showsPrec :: Int -> NetworkAddress -> ShowS

show :: NetworkAddress -> String

showList :: [NetworkAddress] -> ShowS

Eq NetworkAddress

Defined in Test.Sandwich.Contexts.Types.Network

Methods

(==) :: NetworkAddress -> NetworkAddress -> Bool

(/=) :: NetworkAddress -> NetworkAddress -> Bool