tmp-postgres 1.2.0.1 → 1.2.1.0

raw patch · 4 files changed

+104/−54 lines, 4 files

Files

• src/Database/Postgres/Temp.hs +50/−35
• src/Database/Postgres/Temp/Internal.hs +50/−16
• src/Database/Postgres/Temp/Internal/Partial.hs +3/−2
• tmp-postgres.cabal +1/−1

@@ -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' -}

@@ -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@

@@ -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

@@ -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.