Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
(toConnectionString
db))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
initdb
andcreatedb
one could run a temporary postgres on a base backup to test a migration. - By using the
stopPostgres
andwithRestart
functions 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
.
DB | |
|
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.
:: (DB -> IO a) |
|
-> IO (Either StartError a) |
Default expectation safe interface. Equivalent to withPlan
the
defaultConfig
:: 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
:: 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.
StartPostgresFailed ExitCode |
|
InitDbFailed ExitCode |
|
CreateDbFailed ExitCode |
|
CompletePlanFailed [String] | The |
Instances
Eq StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core (==) :: StartError -> StartError -> Bool # (/=) :: StartError -> StartError -> Bool # | |
Ord StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core 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 showsPrec :: Int -> StartError -> ShowS # show :: StartError -> String # showList :: [StartError] -> ShowS # | |
Exception StartError Source # | |
Defined in Database.Postgres.Temp.Internal.Core toException :: StartError -> SomeException # fromException :: SomeException -> Maybe StartError # displayException :: StartError -> String # |
Configuration Types
The high level options for overriding default behavior.
Config | |
|
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 Lastoid
s 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 (==) :: DirectoryType -> DirectoryType -> Bool # (/=) :: DirectoryType -> DirectoryType -> Bool # | |
Ord DirectoryType Source # | |
Defined in Database.Postgres.Temp.Internal.Partial 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 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.
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.
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
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
.
PartialProcessConfig | |
|
Instances
data ProcessConfig Source #
ProcessConfig
contains the configuration necessary for starting a
process. It is essentially a stripped down CreateProcess
.
ProcessConfig | |
|
postgres
process configuration
data PartialPostgresPlan Source #
PartialPostgresPlan
PartialPostgresPlan | |
|
Instances
data PostgresPlan Source #
PostgresPlan is used be startPostgresProcess
to start the postgres
and then attempt to connect to it.
PostgresPlan | |
|
postgres
process handle. Includes the client options for connecting
data PostgresProcess Source #
The output of calling startPostgresProcess
.
PostgresProcess | |
|
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.
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. Plan
s are used internally but are exposed if the higher
level plan generation is not sufficent.