diff --git a/src/Database/Postgres/Temp.hs b/src/Database/Postgres/Temp.hs --- a/src/Database/Postgres/Temp.hs +++ b/src/Database/Postgres/Temp.hs @@ -1,8 +1,8 @@ {-| -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. +This module provides functions for creating a temporary @postgres@ instance. +By default it will create a temporary data directory, +choose a random free port and a temporary directory for a UNIX +domain socket for @postgres@ to listen on. Here is an example using the expection safe 'with' function: @@ -13,23 +13,28 @@ To extend or override the defaults use `withPlan` (or `startWith`). -@tmp-postgres@ ultimately calls @initdb@, @postgres@ and @createdb@. +@tmp-postgres@ ultimately calls (optionally) @initdb@, @postgres@ and +(optionally) @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. +In general @tmp-postgres@ is useful if you want a temporary +@postgres@ which will not clash with open ports. +Here are some different use cases for @tmp-postgres@ and there respective +configurations: -* By disabling @initdb@ and @createdb@ one could run a temporary -postgres on a base backup to test a migration. +* The default 'with' and 'start' functions can be used to make a sandboxed +temporary database for testing. +* By disabling @initdb@ one could run a temporary +isolated postgres on a base backup to test a migration. * By using the 'stopPostgres' and 'withRestart' 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. +The level of custom configuration is extensive but with great power comes the +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. @@ -52,6 +57,7 @@ , startWith , stop , defaultConfig + , defaultPostgresConf -- * Starting and Stopping postgres without removing the temporary directory , restart , stopPostgres @@ -93,10 +99,29 @@ {- $options -@postgres@ is started with a default config with the following options: + Based on the value of 'configSocket' 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. This occurs as a side effect of calling 'withPlan'. + + The config can be either appended to replaced. If you replace it you will + have to specify the listen_addresses (or rely on the default) yourself. + Use 'Mappend' if you want to add to the config or the 'Replace' + constructor if you want to replace the config entirely. + +'defaultConfig' appends the following config by default + + @ shared_buffers = 12MB fsync = off synchronous_commit = off @@ -104,24 +129,11 @@ 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 = SOCKET_DIRECTORY - @ - -To add to \"postgresql.conf\" file create a custom 'Config' like the following: +To append additional lines to \"postgresql.conf\" file create a +custom 'Config' like the following. @ let custom = defaultConfig <> mempty @@ -137,10 +149,13 @@ } @ - 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. + This is common enough there is `defaultPostgresConf` which + is a helper to do this. + + In general you'll want to 'mappend' a config to the 'defaultConfig' + since the 'defaultConfig' setups a client connection to the + @postgres@ database. + + As an alternative to using 'defaultConfig' one could create a + config from connections parameters using 'optionsToDefaultConfig' -} diff --git a/src/Database/Postgres/Temp/Internal.hs b/src/Database/Postgres/Temp/Internal.hs --- a/src/Database/Postgres/Temp/Internal.hs +++ b/src/Database/Postgres/Temp/Internal.hs @@ -19,7 +19,8 @@ -- | 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@. +-- @postgres@. See 'toConnectionString' for converting a 'DB' to +-- postgresql connection string. data DB = DB { dbResources :: Resources -- ^ Temporary resources and the final 'Plan'. @@ -51,31 +52,44 @@ , "client_min_messages = ERROR" ] --- | 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. +{-| +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 append the following onto the \"postgresql.conf\" + + @ + 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'. +-} defaultConfig :: Config defaultConfig = mempty { configPlan = mempty { partialPlanLogger = pure mempty , partialPlanConfig = Mappend defaultPostgresConfig - , partialPlanCreateDb = Mappend Nothing , partialPlanInitDb = Mappend $ pure mempty { partialProcessConfigCmdLine = Mappend $ mempty { partialCommandLineArgsKeyBased = Map.singleton "--no-sync" Nothing } } - , partialPlanPostgres = mempty - { partialPostgresPlanClientConfig = mempty - { Client.dbname = pure "postgres" - } - } } } @@ -93,6 +107,26 @@ } } } + +{-| +'mappend' the 'defaultConfig' with a 'Config' that provides additional + \"postgresql.conf\" lines. Equivalent to + +@ +defaultPostgresConf extra = defaultConfig <> mempty + { configPlan = mempty + { partialPlanConfig = Mappend extra + } + } +@ + +-} +defaultPostgresConf :: [String] -> Config +defaultPostgresConf extra = defaultConfig <> mempty + { configPlan = mempty + { partialPlanConfig = Mappend extra + } + } -- | Create temporary resources and use them to make a 'Config'. -- The generated 'Config' is combined with the passed in @extraConfiguration@ diff --git a/src/Database/Postgres/Temp/Internal/Partial.hs b/src/Database/Postgres/Temp/Internal/Partial.hs --- a/src/Database/Postgres/Temp/Internal/Partial.hs +++ b/src/Database/Postgres/Temp/Internal/Partial.hs @@ -410,8 +410,9 @@ } } , partialPostgresPlanClientConfig = mempty - { Client.host = pure $ socketClassToHost socketClass - , Client.port = pure port + { Client.host = pure $ socketClassToHost socketClass + , Client.port = pure port + , Client.dbname = pure "postgres" } } , partialPlanCreateDb = Mappend $ Just $ mempty diff --git a/tmp-postgres.cabal b/tmp-postgres.cabal --- a/tmp-postgres.cabal +++ b/tmp-postgres.cabal @@ -1,5 +1,5 @@ name: tmp-postgres -version: 1.2.0.1 +version: 1.2.1.0 synopsis: Start and stop a temporary postgres description: @tmp-postgres@ provides functions creating a temporary @postgres@ instance.