Safe Haskell | None |
---|---|
Language | Haskell2010 |
This module provides the high level functions that are re-exported
by Database.Postgres.Temp
. Additionally it includes some
identifiers that are used for testing but are not exported.
Synopsis
- data DB = DB {}
- toConnectionString :: DB -> ByteString
- toConnectionOptions :: DB -> Options
- toDataDirectory :: DB -> FilePath
- makeDataDirPermanent :: DB -> DB
- toTemporaryDirectory :: DB -> FilePath
- defaultPostgresConfig :: [String]
- defaultConfig :: Config
- defaultPostgresConf :: [String] -> Config
- silentConfig :: Config
- startConfig :: Config -> IO (Either StartError DB)
- start :: IO (Either StartError DB)
- stop :: DB -> IO ()
- stopPostgres :: DB -> IO ExitCode
- restart :: DB -> IO (Either StartError DB)
- reloadConfig :: DB -> IO ()
- withConfig :: Config -> (DB -> IO a) -> IO (Either StartError a)
- with :: (DB -> IO a) -> IO (Either StartError a)
- withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a)
- optionsToDefaultConfig :: Options -> Config
- prettyPrintConfig :: Config -> String
- prettyPrintDB :: DB -> String
- dropDbIfExists :: Options -> String -> IO ()
- withNewDb :: DB -> (DB -> IO a) -> IO (Either StartError a)
- withNewDbConfig :: ProcessConfig -> DB -> (DB -> IO a) -> IO (Either StartError a)
Documentation
Handle for holding temporary resources, the postgres
process handle
and postgres connection information. The DB
also includes the
final plan used to start initdb
, createdb
and
postgres
. See toConnectionString
or toConnectionOptions
for converting a DB
to postgresql connection string.
DB | |
|
toConnectionString :: DB -> ByteString Source #
Convert a DB
to a connection string. Alternatively one can access the
Options
using toConnectionOptions
toDataDirectory :: DB -> FilePath Source #
Access the data directory. This was either generated or
specified explicitly when creating the Config
makeDataDirPermanent :: DB -> DB Source #
Make the data directory permanent. Useful for debugging.
If you are using with
or withConfig
this function will
not modify the DB
that is passed for cleanup. You will
need to setup your own bracket like
bracket (fmapmakeDataDirPermanent
start
) (either memptystop
)
toTemporaryDirectory :: DB -> FilePath Source #
Get the directory that is used to create other temporary directories
defaultPostgresConfig :: [String] Source #
Default postgres options
defaultConfig :: Config Source #
The default configuration. This will create a database called "postgres"
via initdb
(it's default behavior).
It will create a temporary directory for the data and a temporary directory
for a unix socket on a random port.
Additionally it will use the following "postgresql.conf"
which is optimized for performance.
shared_buffers = 12MB fsync = off synchronous_commit = off full_page_writes = off log_min_duration_statement = 0 log_connections = on log_disconnections = on client_min_messages = ERROR
defaultConfig
also passes the --no-sync
flag to initdb
.
If you would like to customize this behavior you can start with the
defaultConfig
and overwrite fields or combine a defaultConfig
with another Config
using <>
(mappend
).
Alternatively you can eschew defaultConfig
altogether, however
your postgres
might start and run faster if you use
defaultConfig
.
The defaultConfig
also disables the logging of internal Event
s.
To append additional lines to "postgresql.conf" file create a
custom Config
like the following.
custom = defaultConfig <> mempty {plan
= mempty {postgresConfigFile
= [ "wal_level = replica" , "archive_mode = on" , "max_wal_senders = 2" , "fsync = on" , "synchronous_commit = on" ] } }
Or using the provided lenses and your favorite lens library
custom = defaultConfig &planL
.postgresConfigFile
<>~
[ "wal_level = replica" , "archive_mode = on" , "max_wal_senders = 2" , "fsync = on" , "synchronous_commit = on" ]
This is common enough there is defaultPostgresConf
which
is a helper to do this.
As an alternative to using defaultConfig
one could create a
config from connections parameters using optionsToDefaultConfig
defaultPostgresConf :: [String] -> Config Source #
mappend
the defaultConfig
with a Config
that provides additional
"postgresql.conf" lines. Equivalent to
defaultPostgresConf
extra =defaultConfig
<> mempty {plan
= mempty {postgresConfigFile
= extra } }
or with lenses
defaultPostgresConf
extra =defaultConfig
&planL
.postgresConfigFile
<>~
extra
silentConfig :: Config Source #
The same as defaultConfig
but all the handles are set to "/dev/null".
See silentProcessConfig
as well.
:: Config |
|
-> IO (Either StartError DB) |
Create zero or more temporary resources and use them to make a Config
.
The passed in config is inspected and a generated config is created. The final config is built by
generated <>
extra
Based on the value of socketClass
a "postgresql.conf" is created with
listen_addresses = 'IP_ADDRESS'
if it is IpSocket
. If is UnixSocket
then the lines
listen_addresses = '' unix_socket_directories = 'SOCKET_DIRECTORY'
are added.
Additionally the generated
Config
also does the following:
- Sets a
connectionTimeout
of one minute. - Logs internal
Event
s. - Sets the processes to use the standard input and output handles.
- Sets the
dataDirectoryString
to file path generated fromdataDirectory
All of these values can be overrided by the extra
config.
The returned DB
requires cleanup. startConfig
should be
used with a bracket
and stop
, e.g.
withConfig
::Config
-> (DB
-> IO a) -> IO (EitherStartError
a)withConfig
plan f =bracket
(startConfig
plan) (either memptystop
) $ either (pure . Left) (fmap Right . f)
or just use withConfig
. If you are calling startConfig
you
probably want withConfig
anyway.
start :: IO (Either StartError DB) Source #
Default start behavior. Equivalent to calling startConfig
with the
defaultConfig
Stop the postgres
process and cleanup any temporary resources that
might have been created.
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
.
reloadConfig :: DB -> IO () Source #
Reload the configuration file without shutting down. Calls
pg_reload_conf()
.
:: Config |
|
-> (DB -> IO a) |
|
-> IO (Either StartError a) |
Exception safe database create with options. See startConfig
for more
details. Calls stop
even in the face of exceptions.
:: (DB -> IO a) |
|
-> IO (Either StartError a) |
Default expectation safe interface. Equivalent to
with
=withConfig
defaultConfig
withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a) Source #
Exception safe version of restart
dropDbIfExists :: Options -> String -> IO () Source #
Drop the db if it exists. Terminates all connections to the db first.
:: DB | The original |
-> (DB -> IO a) | The modified |
-> IO (Either StartError a) |
Use the current database as a template and make a copy. Give the copy a random name.
Equivalent to:
withNewDb
=withNewDbConfig
mempty
See withNewDbConfig
for more details.
:: ProcessConfig |
|
-> DB | The original |
-> (DB -> IO a) | The modified |
-> IO (Either StartError a) |
Use the current database as a template and make a copy. Give the copy a random name.
Copying a database from a template can be faster than creating a new
postgres
and migrating a database from scratch. In artifical benchmarks
it appears to be about 2x faster.
To use the current database as a template all connections to the database must be terminated first.
To override the arguments passed to createdb
one can pass in extra
ProcessConfig
. The combined
process is created by mappend
ed the
generated
with the extra
ProcessConfig
, e.g.
combined = generated <>
extra
The current implementation has a few known issues.
If a connection is made between the termination command and the createdb
call the createdb
call will fail.
Additionally the generated name is 32 character random name of characters "a" to "z". It is possible, although unlikeily that a duplicate database name could be generated and this would also cause a failure.