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
- 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)
- startNewDb :: DB -> IO (Either StartError DB)
- startNewDbConfig :: ProcessConfig -> DB -> IO (Either StartError DB)
- stopNewDb :: DB -> IO ()
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.
Since: 1.12.0.0
DB | |
|
toConnectionString :: DB -> ByteString Source #
Convert a DB
to a connection string. Alternatively one can access the
Options
using toConnectionOptions
.
Since: 1.12.0.0
toConnectionOptions :: DB -> Options Source #
toDataDirectory :: DB -> FilePath Source #
Access the data directory. This was either generated or
specified explicitly when creating the Config
Since: 1.12.0.0
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
)
Since: 1.12.0.0
toTemporaryDirectory :: DB -> FilePath Source #
Get the directory that is used to create other temporary directories
Since: 1.12.0.0
defaultPostgresConfig :: [String] Source #
Default postgres options
Since: 1.12.0.0
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
.
Since: 1.12.0.0
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
Since: 1.12.0.0
silentConfig :: Config Source #
The same as defaultConfig
but all the handles are set to devnull
.
See silentProcessConfig
as well.
Since: 1.12.0.0
:: 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.
Since: 1.12.0.0
start :: IO (Either StartError DB) Source #
Default start behavior. Equivalent to calling startConfig
with the
defaultConfig
.
Since: 1.12.0.0
Stop the postgres
process and cleanup any temporary resources that
might have been created.
Since: 1.12.0.0
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
.
Since: 1.12.0.0
reloadConfig :: DB -> IO () Source #
Reload the configuration file without shutting down. Calls
pg_reload_conf()
.
Since: 1.12.0.0
:: 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.
Since: 1.12.0.0
:: (DB -> IO a) |
|
-> IO (Either StartError a) |
withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a) Source #
Exception safe version of restart
.
Since: 1.12.0.0
dropDbIfExists :: Options -> String -> IO () Source #
Drop the db if it exists. Terminates all connections to the db first.
Since: 1.12.0.0
:: 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 startNewDbConfig
for more details.
Since: 1.12.0.0
:: ProcessConfig |
|
-> DB | The original |
-> (DB -> IO a) | The modified |
-> IO (Either StartError a) |
Exception safe version of startNewDbConfig
. Creates a
temporary database using the current database as a template.
See startNewDbConfig
for more details.
Since: 1.12.0.0
:: DB | The original |
-> IO (Either StartError DB) |
Use the current database as a template and make a copy. Give the copy a random name.
Equivalent to:
startNewDb
=startNewDbConfig
mempty
See startNewDbConfig
for more details.
Since: 1.13.0.0
:: ProcessConfig |
|
-> DB | The original |
-> IO (Either StartError DB) |
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.
startNewDbConfig
requires cleanup so it best to use a bracket
along
with stopNewDb
. This is equivalient to withNewDbConfig
.
The only reason to use startNewDbConfig
over withNewDbConfig
is
if you are unable to use withNewDbConfig
for some reason.
Since: 1.13.0.0
stopNewDb :: DB -> IO () Source #
Cleanup the temporary database created by startNewDbConfig
or startNewDb
.
Since: 1.13.0.0