| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Database.Postgres.Temp
Contents
Description
This module provides functions creating a temporary postgres instance.
By default it will create a temporary directory for the data,
a random port for listening and a temporary directory for a UNIX
domain socket.
Here is an example using the expection safe with function:
with$ \db ->bracket(connectPostgreSQL(toConnectionStringdb))close$ \conn ->execute_conn "CREATE TABLE foo (id int)"
To extend or override the defaults use withPlan (or startWith).
tmp-postgres ultimately calls initdb, postgres and createdb.
All of the command line, environment variables and configuration files
that are generated by default for the respective executables can be
extended or overrided.
All tmp-postgres by default is most useful for creating tests by
configuring "tmp-postgres" differently it can be used for other purposes.
- By disabling
initdbandcreatedbone could run a temporary postgres on a base backup to test a migration. - By using the
stopPostgresandwithRestartfunctions one can test backup strategies.
The level of custom configuration is extensive but with great power comes
ability to screw everything up. `tmp-postgres` doesn't validate any custom
configuration and one can easily create a Config that would not allow
postgres to start.
WARNING!!
Ubuntu's PostgreSQL installation does not put initdb on the PATH. We need to add it manually.
The necessary binaries are in the /usr/lib/postgresql/VERSION/bin/ directory, and should be added to the PATH
echo "export PATH=$PATH:/usr/lib/postgresql/VERSION/bin/" >> /home/ubuntu/.bashrc
Synopsis
- data DB = DB {}
- with :: (DB -> IO a) -> IO (Either StartError a)
- withPlan :: Config -> (DB -> IO a) -> IO (Either StartError a)
- start :: IO (Either StartError DB)
- startWith :: Config -> IO (Either StartError DB)
- stop :: DB -> IO ()
- defaultConfig :: Config
- restart :: DB -> IO (Either StartError DB)
- stopPostgres :: DB -> IO ExitCode
- withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a)
- reloadConfig :: DB -> IO ()
- toConnectionString :: DB -> ByteString
- data StartError
- data Config = Config {}
- data Lastoid a
- data DirectoryType
- data PartialDirectoryType
- data SocketClass
- data PartialSocketClass
- data PartialProcessConfig = PartialProcessConfig {}
- data ProcessConfig = ProcessConfig {}
- data PartialPostgresPlan = PartialPostgresPlan {}
- data PostgresPlan = PostgresPlan {}
- data PostgresProcess = PostgresProcess {}
- data PartialPlan = PartialPlan {}
- data Plan = Plan {}
Main resource handle
Handle for holding temporary resources, the postgres process handle
and postgres connection information. The DB also includes the
final Plan that was used to start initdb, createdb and
postgres.
Constructors
| DB | |
Fields
| |
Exception safe interface
postgres is started with a default config with the following options:
shared_buffers = 12MB
fsync = off
synchronous_commit = off
full_page_writes = off
log_min_duration_statement = 0
log_connections = on
log_disconnections = on
unix_socket_directories = {DATA_DIRECTORY}
client_min_messages = ERROR
Additionally if an IP address is provide the following line is added:
listen_addresses = 'IP_ADDRESS'
If a UNIX domain socket is specified the following is added:
listen_addresses = ''
unix_socket_directories = {DATA_DIRECTORY}
To add to "postgresql.conf" file create a custom Config like the following:
let custom = defaultConfig <> mempty { configPlan = mempty
{ partialPlanConfig = Mappend
[ "wal_level=replica"
, "archive_mode=on"
, "max_wal_senders=2"
, "fsync=on"
, "synchronous_commit=on"
]
}
}
In general you'll want to mappend a config to the defaultConfig.
The defaultConfig setups a database and connection options for
the created database. However if you want to extend the behavior
of createdb you will probably have to create a Config from
scratch to ensure the final parameter to createdb is the
database name.
Arguments
| :: (DB -> IO a) |
|
| -> IO (Either StartError a) |
Default expectation safe interface. Equivalent to withPlan the
defaultConfig
Arguments
| :: Config |
|
| -> (DB -> IO a) |
|
| -> IO (Either StartError a) |
Exception safe default database create. Takes an action continuation
which is given a DB it can use to connect
to (see toConnectionString or postgresProcessClientConfig).
All of the database resources are automatically cleaned up on
completion even in the face of exceptions.
Separate start and stop interface.
start :: IO (Either StartError DB) Source #
Default start behavior. Equivalent to calling startWith with the
defaultConfig
Arguments
| :: Config |
|
| -> IO (Either StartError DB) |
Create temporary resources and use them to make a Config.
The generated Config is combined with the passed in extraConfiguration
to create a Plan that is used to create a database.
The output DB includes references to the temporary resources for
cleanup and the final plan that was used to generate the database and
processes
Stop the postgres process and cleanup any temporary directories that
might have been created.
defaultConfig :: Config Source #
The default configuration. This will create a database called "test"
and create a temporary directory for the data and a temporary directory
for a unix socket on a random port.
If you would like to customize this behavior you can start with the
defaultConfig and overwrite fields or combine the Config with another
config using <> (mappend).
If you would like complete control over the behavior of initdb,
postgres and createdb you can call the internal function initPlan
directly although this should not be necessary.
Starting and Stopping postgres without removing the temporary directory
stopPostgres :: DB -> IO ExitCode Source #
Only stop the postgres process but leave any temporary resources.
Useful for testing backup strategies when used in conjunction with
restart or withRestart.
withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a) Source #
Exception safe version of restart
Reloading the config
reloadConfig :: DB -> IO () Source #
Reload the configuration file without shutting down. Calls
pg_reload_conf().
DB manipulation
toConnectionString :: DB -> ByteString Source #
Errors
data StartError Source #
A list of failures that can occur when starting. This is not and exhaustive list but covers the errors that the system catches for the user.
Constructors
| StartPostgresFailed ExitCode |
|
| InitDbFailed ExitCode |
|
| CreateDbFailed ExitCode |
|
| CompletePlanFailed [String] | The |
Instances
| Eq StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core | |
| Ord StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core Methods compare :: StartError -> StartError -> Ordering # (<) :: StartError -> StartError -> Bool # (<=) :: StartError -> StartError -> Bool # (>) :: StartError -> StartError -> Bool # (>=) :: StartError -> StartError -> Bool # max :: StartError -> StartError -> StartError # min :: StartError -> StartError -> StartError # | |
| Show StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core Methods showsPrec :: Int -> StartError -> ShowS # show :: StartError -> String # showList :: [StartError] -> ShowS # | |
| Exception StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core Methods toException :: StartError -> SomeException # fromException :: SomeException -> Maybe StartError # displayException :: StartError -> String # | |
Configuration Types
The high level options for overriding default behavior.
Constructors
| Config | |
Fields
| |
Instances
| Generic Config Source # | |
| Semigroup Config Source # | |
| Monoid Config Source # | |
| type Rep Config Source # | |
Defined in Database.Postgres.Temp.Internal.Partial type Rep Config = D1 (MetaData "Config" "Database.Postgres.Temp.Internal.Partial" "tmp-postgres-1.0.0.2-DvnOuejNnGN1mXJO2kDkWd" False) (C1 (MetaCons "Config" PrefixI True) ((S1 (MetaSel (Just "configPlan") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PartialPlan) :*: S1 (MetaSel (Just "configSocket") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PartialSocketClass)) :*: (S1 (MetaSel (Just "configDataDir") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PartialDirectoryType) :*: S1 (MetaSel (Just "configPort") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Last (Maybe Int)))))) | |
General extend or override monoid
Lastoid is helper for overriding configuration values.
It's Semigroup instance let's one either combine the
a of two Lastoids using <> via the Mappend constructor
or one can wholly replace the value with the last value using the Replace
constructor.
Roughly
x <> Replace y = Replace y Replace x <> Mappend y = Replace (x <> y) Mappend x <> Mappend y = Mappend (x <> y)
Directory configuration
data DirectoryType Source #
A type to track whether a file is temporary and needs to be cleaned up.
Instances
| Eq DirectoryType Source # | |
Defined in Database.Postgres.Temp.Internal.Partial Methods (==) :: DirectoryType -> DirectoryType -> Bool # (/=) :: DirectoryType -> DirectoryType -> Bool # | |
| Ord DirectoryType Source # | |
Defined in Database.Postgres.Temp.Internal.Partial Methods compare :: DirectoryType -> DirectoryType -> Ordering # (<) :: DirectoryType -> DirectoryType -> Bool # (<=) :: DirectoryType -> DirectoryType -> Bool # (>) :: DirectoryType -> DirectoryType -> Bool # (>=) :: DirectoryType -> DirectoryType -> Bool # max :: DirectoryType -> DirectoryType -> DirectoryType # min :: DirectoryType -> DirectoryType -> DirectoryType # | |
| Show DirectoryType Source # | |
Defined in Database.Postgres.Temp.Internal.Partial Methods showsPrec :: Int -> DirectoryType -> ShowS # show :: DirectoryType -> String # showList :: [DirectoryType] -> ShowS # | |
data PartialDirectoryType Source #
The monoidial version of DirectoryType. Used to combine overrides with
defaults when creating a DirectoryType. The monoid instance treats
PTemporary as mempty and takes the last PPermanent value.
Constructors
| PPermanent FilePath | A permanent file that should not be generated. |
| PTemporary | A temporary file that needs to generated. |
Instances
Listening socket configuration
data SocketClass Source #
A type for configuring the listening address of the postgres process.
postgres can listen on several types of sockets simulatanously but we
don't support that behavior. One can either listen on a IP based socket
or a UNIX domain socket.
Constructors
| IpSocket String | IP socket type. The |
| UnixSocket DirectoryType | UNIX domain socket |
Instances
data PartialSocketClass Source #
The monoidial version of SocketClass. Used to combine overrides with
defaults when creating a SocketClass. The monoid instance treats
'PUnixSocket mempty' as mempty and combines the
Constructors
| PIpSocket (Last String) | The monoid for combining IP address configuration |
| PUnixSocket PartialDirectoryType | The monoid for combining UNIX socket configuration |
Instances
Process configuration
data PartialProcessConfig Source #
The monoidial version of ProcessConfig. Used to combine overrides with
defaults when creating a ProcessConfig.
Constructors
| PartialProcessConfig | |
Fields
| |
Instances
data ProcessConfig Source #
ProcessConfig contains the configuration necessary for starting a
process. It is essentially a stripped down CreateProcess.
Constructors
| ProcessConfig | |
Fields
| |
postgres process configuration
data PartialPostgresPlan Source #
PartialPostgresPlan
Constructors
| PartialPostgresPlan | |
Fields
| |
Instances
data PostgresPlan Source #
PostgresPlan is used be startPostgresProcess to start the postgres
and then attempt to connect to it.
Constructors
| PostgresPlan | |
Fields
| |
postgres process handle. Includes the client options for connecting
data PostgresProcess Source #
The output of calling startPostgresProcess.
Constructors
| PostgresProcess | |
Fields
| |
Database plans. This is used to call initdb, postgres and createdb
data PartialPlan Source #
The monoidial version of Plan. Used to combine overrides with defaults
when creating a plan.
Constructors
| PartialPlan | |
Instances
Plan is the low level configuration necessary for creating a database
starting postgres and creating a database. There is no validation done
on the Plan. It is recommend that one use the higher level functions
such as start which will generate plans that
are valid. Plans are used internally but are exposed if the higher
level plan generation is not sufficent.
Constructors
| Plan | |
Fields | |