diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,3 +29,9 @@ 1.11.0.0 #90 Extend generated config to provide default Handles and connection timeout. #81 Create public Config module for better documentation organization. + +1.12.0.0 + #64 Add the 'withNewDB' and 'withNewDBConfig' functions + +1.12.0.1 + Documentation fixes diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ with $ \db -> bracket (connectPostgreSQL (toConnectionString db)) close $ - \conn -> PG.execute_ conn "CREATE TABLE foo (id int)" + \conn -> execute_ conn "CREATE TABLE foo (id int)" ``` To extend or override the defaults use `withConfig` (or `startConfig`). 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 @@ -80,7 +80,7 @@ , silentProcessConfig -- ** Custom Config builder helpers , optionsToDefaultConfig - -- ** 'Config' + -- ** Configuration Types , module Database.Postgres.Temp.Config ) where import Database.Postgres.Temp.Internal diff --git a/src/Database/Postgres/Temp/Config.hs b/src/Database/Postgres/Temp/Config.hs --- a/src/Database/Postgres/Temp/Config.hs +++ b/src/Database/Postgres/Temp/Config.hs @@ -63,4 +63,3 @@ ) where import Database.Postgres.Temp.Internal.Config import Database.Postgres.Temp.Internal.Core -import Database.Postgres.Temp.Internal 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 @@ -4,10 +4,8 @@ identifiers that are used for testing but are not exported. -} module Database.Postgres.Temp.Internal where - import Database.Postgres.Temp.Internal.Core import Database.Postgres.Temp.Internal.Config - import Control.Concurrent.Async import Control.Exception import Control.Monad (void) @@ -29,6 +27,8 @@ -- 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 data DB = DB { dbResources :: Resources -- ^ Temporary resources and the final 'CompletePlan'. @@ -47,13 +47,17 @@ <> indent 2 (pretty dbPostgresProcess) -- | Convert a 'DB' to a connection string. Alternatively one can access the --- 'Client.Options' using 'toConnectionOptions' +-- 'Client.Options' using 'toConnectionOptions'. +-- +-- @since 1.12.0.0 toConnectionString :: DB -> ByteString toConnectionString = Client.toConnectionString . toConnectionOptions -- | Convert a 'DB' to a connection 'Client.Options' type. +-- +-- @since 1.12.0.0 toConnectionOptions :: DB -> Client.Options toConnectionOptions = postgresProcessClientOptions @@ -61,6 +65,8 @@ -- | Access the data directory. This was either generated or -- specified explicitly when creating the 'Config' +-- +-- @since 1.12.0.0 toDataDirectory :: DB -> FilePath toDataDirectory = toFilePath . resourcesDataDir . dbResources @@ -74,6 +80,8 @@ bracket (fmap 'makeDataDirPermanent' 'start') (either mempty 'stop') @ + +@since 1.12.0.0 -} makeDataDirPermanent :: DB -> DB makeDataDirPermanent db = db @@ -81,12 +89,16 @@ } -- | Get the directory that is used to create other temporary directories +-- +-- @since 1.12.0.0 toTemporaryDirectory :: DB -> FilePath toTemporaryDirectory = resourcesTemporaryDir . dbResources ------------------------------------------------------------------------------- -- Life Cycle Management ------------------------------------------------------------------------------- -- | Default postgres options +-- +-- @since 1.12.0.0 defaultPostgresConfig :: [String] defaultPostgresConfig = [ "shared_buffers = 12MB" @@ -147,7 +159,7 @@ } @ -Or using the provided lenses and your favorite lens library +Or using the provided lenses and your favorite lens library: @ custom = defaultConfig & 'planL' . 'postgresConfigFile' '<>~' @@ -163,7 +175,10 @@ is a helper to do this. As an alternative to using 'defaultConfig' one could create a - config from connections parameters using 'optionsToDefaultConfig' + config from connections parameters using 'optionsToDefaultConfig'. + + +@since 1.12.0.0 -} defaultConfig :: Config defaultConfig = mempty @@ -181,7 +196,7 @@ {-| 'mappend' the 'defaultConfig' with a 'Config' that provides additional - \"postgresql.conf\" lines. Equivalent to + \"postgresql.conf\" lines. Equivalent to: @ 'defaultPostgresConf' extra = 'defaultConfig' <> mempty @@ -191,12 +206,13 @@ } @ -or with lenses +or with lenses: @ 'defaultPostgresConf' extra = 'defaultConfig' & 'planL' . 'postgresConfigFile' '<>~' extra @ +@since 1.12.0.0 -} defaultPostgresConf :: [String] -> Config defaultPostgresConf extra = defaultConfig <> mempty @@ -205,8 +221,10 @@ } } --- | The same as 'defaultConfig' but all the handles are set to \"\/dev\/null\". +-- | The same as 'defaultConfig' but all the handles are set to @/dev/null@. -- See 'silentProcessConfig' as well. +-- +-- @since 1.12.0.0 silentConfig :: Config silentConfig = defaultConfig <> mempty { plan = mempty @@ -228,13 +246,13 @@ generated '<>' extra @ -Based on the value of 'socketClass' a \"postgresql.conf\" is created with +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 + if it is 'IpSocket'. If is 'UnixSocket' then the lines: @ listen_addresses = '' @@ -248,7 +266,7 @@ * 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 from 'dataDirectory' +* Sets the 'dataDirectoryString' to file path generated from 'dataDirectory'. All of these values can be overrided by the @extra@ config. @@ -264,10 +282,11 @@ or just use 'withConfig'. If you are calling 'startConfig' you probably want 'withConfig' anyway. +@since 1.12.0.0 -} startConfig :: Config -- ^ @extra@ configuration that is 'mappend'ed last to the generated `Config`. - -- @generated <> extra@ + -- @generated@ '<>' @extra@. -> IO (Either StartError DB) startConfig extra = try $ evalContT $ do dbResources@Resources {..} <- @@ -277,12 +296,16 @@ pure DB {..} -- | Default start behavior. Equivalent to calling 'startConfig' with the --- 'defaultConfig' +-- 'defaultConfig'. +-- +-- @since 1.12.0.0 start :: IO (Either StartError DB) start = startConfig defaultConfig -- | Stop the @postgres@ process and cleanup any temporary resources that -- might have been created. +-- +-- @since 1.12.0.0 stop :: DB -> IO () stop DB {..} = do void $ stopPostgresProcess dbPostgresProcess @@ -291,10 +314,14 @@ -- | 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 stopPostgres :: DB -> IO ExitCode stopPostgres = stopPostgresProcess . dbPostgresProcess --- | Restart the @postgres@ from 'DB' using the prior 'Plan' +-- | Restart the @postgres@ from 'DB' using the prior 'Plan'. +-- +-- @since 1.12.0.0 restart :: DB -> IO (Either StartError DB) restart db@DB{..} = try $ do void $ stopPostgres db @@ -306,6 +333,8 @@ -- | Reload the configuration file without shutting down. Calls -- @pg_reload_conf()@. +-- +-- @since 1.12.0.0 reloadConfig :: DB -> IO () reloadConfig db = bracket (PG.connectPostgreSQL $ toConnectionString db) PG.close $ \conn -> @@ -317,12 +346,14 @@ {-| Exception safe database create with options. See 'startConfig' for more details. Calls 'stop' even in the face of exceptions. + +@since 1.12.0.0 -} withConfig :: Config -- ^ @extra@. 'Config' combined with the generated 'Config'. See - -- 'startConfig' for more info + -- 'startConfig' for more info. -> (DB -> IO a) - -- ^ @action@ continuation + -- ^ @action@ continuation. -> IO (Either StartError a) withConfig extra f = bracket (startConfig extra) (either mempty stop) $ either (pure . Left) (fmap Right . f) @@ -333,13 +364,16 @@ 'with' = 'withConfig' 'defaultConfig' @ +@since 1.12.0.0 -} with :: (DB -> IO a) -- ^ @action@ continuation. -> IO (Either StartError a) with = withConfig defaultConfig --- | Exception safe version of 'restart' +-- | Exception safe version of 'restart'. +-- +-- @since 1.12.0.0 withRestart :: DB -> (DB -> IO a) -> IO (Either StartError a) withRestart db f = bracket (restart db) (either mempty stop) $ either (pure . Left) (fmap Right . f) @@ -347,6 +381,8 @@ -- | Attempt to create a 'Config' from a 'Client.Options'. Useful if you -- want to create a database owned by a specific user you will also login -- with among other use cases. +-- +-- @since 1.12.0.0 optionsToDefaultConfig :: Client.Options -> Config optionsToDefaultConfig opts@Client.Options {..} = let generated = optionsToConfig opts @@ -363,11 +399,9 @@ ------------------------------------------------------------------------------- -- Pretty Printing ------------------------------------------------------------------------------- --- | Display a 'Config'. -prettyPrintConfig :: Config -> String -prettyPrintConfig = show . pretty - --- | Display a 'DB' +-- | Display a 'DB'. +-- +-- @since 1.12.0.0 prettyPrintDB :: DB -> String prettyPrintDB = show . pretty @@ -375,6 +409,8 @@ -- withNewDb ------------------------------------------------------------------------------- -- | Drop the db if it exists. Terminates all connections to the db first. +-- +-- @since 1.12.0.0 dropDbIfExists :: Client.Options -> String -> IO () dropDbIfExists options dbName = do let theConnectionString = Client.toConnectionString options @@ -399,10 +435,13 @@ @ See 'withNewDbConfig' for more details. + +@since 1.12.0.0 -} withNewDb :: DB - -- ^ The original 'DB' handle. The connection options database + -- ^ The original 'DB' handle. The database name specified in the + -- connection options -- is used as the template for the @generated@ 'ProcessConfig' -> (DB -> IO a) -- ^ The modified 'DB' handle that has the new database name @@ -437,13 +476,16 @@ 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. + +@since 1.12.0.0 -} withNewDbConfig :: ProcessConfig - -- ^ @extra@ @createdb@ 'ProcessConfig' + -- ^ @extra@ @createdb@ 'ProcessConfig'. -> DB - -- ^ The original 'DB' handle. The connection options database - -- is used as the template for the @generated@ 'ProcessConfig' + -- ^ The original 'DB' handle. The database name specified in the + -- connection options + -- is used as the template for the @generated@ 'ProcessConfig'. -> (DB -> IO a) -- ^ The modified 'DB' handle that has the new database name -- in it's connection options. diff --git a/src/Database/Postgres/Temp/Internal/Config.hs b/src/Database/Postgres/Temp/Internal/Config.hs --- a/src/Database/Postgres/Temp/Internal/Config.hs +++ b/src/Database/Postgres/Temp/Internal/Config.hs @@ -46,6 +46,8 @@ -- | The environment variables can be declared to -- inherit from the running process or they -- can be specifically added. +-- +-- @since 1.12.0.0 data EnvironmentVariables = EnvironmentVariables { inherit :: Last Bool , specific :: Map String String @@ -74,7 +76,9 @@ -- | Combine the current environment -- (if indicated by 'inherit') --- with 'specific' +-- with 'specific'. +-- +-- @since 1.12.0.0 completeEnvironmentVariables :: [(String, String)] -> EnvironmentVariables @@ -85,6 +89,8 @@ <> Map.toList specific -- | A type to help combine command line Args. +-- +-- @since 1.12.0.0 data CommandLineArgs = CommandLineArgs { keyBased :: Map String (Maybe String) -- ^ Args of the form @-h foo@, @--host=foo@ and @--switch@. @@ -130,7 +136,9 @@ | otherwise = [] takeWhileInSequence _ = [] --- | This convert the 'CommandLineArgs' to ' +-- | This convert the 'CommandLineArgs' to '[String]'. +-- +-- @since 1.12.0.0 completeCommandLineArgs :: CommandLineArgs -> [String] completeCommandLineArgs CommandLineArgs {..} = map (\(name, mvalue) -> maybe name (name <>) mvalue) @@ -138,18 +146,20 @@ <> takeWhileInSequence (Map.toList indexBased) -- | Process configuration +-- +-- @since 1.12.0.0 data ProcessConfig = ProcessConfig { environmentVariables :: EnvironmentVariables -- ^ A monoid for combine environment variables or replacing them. -- for the maps the 'Dual' monoid is used. So the last key wins. , commandLine :: CommandLineArgs - -- ^ A monoid for combine command line Args or replacing them + -- ^ A monoid for combine command line Args or replacing them. , stdIn :: Last Handle - -- ^ A monoid for configuring the standard input 'Handle' + -- ^ A monoid for configuring the standard input 'Handle'. , stdOut :: Last Handle - -- ^ A monoid for configuring the standard output 'Handle' + -- ^ A monoid for configuring the standard output 'Handle'. , stdErr :: Last Handle - -- ^ A monoid for configuring the standard error 'Handle' + -- ^ A monoid for configuring the standard error 'Handle'. } deriving stock (Generic, Eq, Show) deriving Semigroup via GenericSemigroup ProcessConfig @@ -181,6 +191,8 @@ -- | The 'standardProcessConfig' sets the handles to 'stdin', 'stdout' and -- 'stderr' and inherits the environment variables from the calling -- process. +-- +-- @since 1.12.0.0 standardProcessConfig :: ProcessConfig standardProcessConfig = mempty { environmentVariables = mempty @@ -191,12 +203,17 @@ , stdErr = pure stderr } +-- | A global reference to @/dev/null@ 'Handle'. +-- +-- @since 1.12.0.0 devNull :: Handle devNull = unsafePerformIO (openFile "/dev/null" WriteMode) {-# NOINLINE devNull #-} --- | 'silentProcessConfig' sets the handles to \"\/dev\/null\" and --- inherits the environment variables from the calling process +-- | 'silentProcessConfig' sets the handles to @/dev/null@ and +-- inherits the environment variables from the calling process. +-- +-- @since 1.12.0.0 silentProcessConfig :: ProcessConfig silentProcessConfig = mempty { environmentVariables = mempty @@ -219,6 +236,8 @@ -- | Turn a 'ProcessConfig' into a 'ProcessConfig'. Fails if -- any values are missing. +-- +-- @since 1.12.0.0 completeProcessConfig :: [(String, String)] -> ProcessConfig -> Either [String] CompleteProcessConfig completeProcessConfig envs ProcessConfig {..} = runErrors $ do @@ -235,11 +254,15 @@ pure CompleteProcessConfig {..} -- | A type to track whether a file is temporary and needs to be cleaned up. +-- +-- @since 1.12.0.0 data CompleteDirectoryType = CPermanent FilePath | CTemporary FilePath deriving(Show, Eq, Ord) -- | Get the file path of a 'CompleteDirectoryType', regardless if it is a -- 'CPermanent' or 'CTemporary' type. +-- +-- @since 1.12.0.0 toFilePath :: CompleteDirectoryType -> FilePath toFilePath = \case CPermanent x -> x @@ -258,6 +281,8 @@ -- | Used to specify a 'Temporary' folder that is automatically -- cleaned up or a 'Permanent' folder which is not -- automatically cleaned up. +-- +-- @since 1.12.0.0 data DirectoryType = Permanent FilePath -- ^ A permanent file that should not be generated. @@ -282,6 +307,8 @@ -- | Either create a'CTemporary' directory or do nothing to a 'CPermanent' -- one. +-- +-- @since 1.12.0.0 setupDirectoryType :: String -- ^ Temporary directory configuration @@ -313,6 +340,8 @@ -- @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. +-- +-- @since 1.12.0.0 data CompleteSocketClass = CIpSocket String -- ^ IP socket type. The 'String' is either an IP address or @@ -326,7 +355,7 @@ CIpSocket x -> text "CIpSocket:" <+> pretty x CUnixSocket x -> text "CUnixSocket:" <+> pretty x --- | Create the extra config lines for listening based on the 'CompleteSocketClass' +-- | Create the extra config lines for listening based on the 'CompleteSocketClass'. socketClassToConfig :: CompleteSocketClass -> [String] socketClassToConfig = \case CIpSocket ip -> ["listen_addresses = '" <> ip <> "'"] @@ -341,7 +370,7 @@ socketClassToHostFlag x = [("-h", Just (socketClassToHost x))] -- | Get the IP address, host name or UNIX domain socket directory --- as a 'String' +-- as a 'String'. socketClassToHost :: CompleteSocketClass -> String socketClassToHost = \case CIpSocket ip -> ip @@ -353,11 +382,13 @@ -- specify 'UnixSocket' for a UNIX domain socket. If a directory is -- specified the socket will live in that folder. Otherwise a -- temporary folder will get created for the socket. +-- +-- @since 1.12.0.0 data SocketClass = IpSocket (Last String) - -- ^ The monoid for combining IP address configuration + -- ^ The monoid for combining IP address configuration. | UnixSocket DirectoryType - -- ^ The monoid for combining UNIX socket configuration + -- ^ The monoid for combining UNIX socket configuration. deriving stock (Show, Eq, Ord, Generic, Typeable) instance Pretty SocketClass where @@ -374,7 +405,7 @@ (UnixSocket _, a@(IpSocket _)) -> a (UnixSocket a, UnixSocket b) -> UnixSocket $ a <> b --- | Treats 'UnixSocket' 'mempty' as 'mempty' +-- | Treats 'UnixSocket' 'mempty' as 'mempty'. instance Monoid SocketClass where mempty = UnixSocket mempty @@ -383,9 +414,9 @@ -- optionally create a temporary directory if configured to do so. setupSocketClass :: String - -- ^ Temporary directory + -- ^ Temporary directory. -> SocketClass - -- ^ The type of socket + -- ^ The type of socket. -> IO CompleteSocketClass setupSocketClass tempDir theClass = case theClass of IpSocket mIp -> pure $ CIpSocket $ fromMaybe "127.0.0.1" $ @@ -401,6 +432,8 @@ -- | @postgres@ process config and corresponding client connection -- 'Client.Options'. +-- +-- @since 1.12.0.0 data PostgresPlan = PostgresPlan { postgresConfig :: ProcessConfig -- ^ Monoid for the @postgres@ ProcessConfig. @@ -435,6 +468,8 @@ -- Plan ------------------------------------------------------------------------------- -- | Describe how to run @initdb@, @createdb@ and @postgres@ +-- +-- @since 1.12.0.0 data Plan = Plan { logger :: Last Logger , initDbConfig :: Maybe ProcessConfig @@ -491,31 +526,33 @@ pure CompletePlan {..} -- Returns 'True' if the 'Plan' has a --- 'Just' 'initDbConfig' +-- 'Just' 'initDbConfig'. hasInitDb :: Plan -> Bool hasInitDb Plan {..} = isJust initDbConfig -- Returns 'True' if the 'Plan' has a --- 'Just' 'createDbConfig' +-- 'Just' 'createDbConfig'. hasCreateDb :: Plan -> Bool hasCreateDb Plan {..} = isJust createDbConfig -- | The high level options for overriding default behavior. +-- +-- @since 1.12.0.0 data Config = Config { plan :: Plan -- ^ Extend or replace any of the configuration used to create a final - -- 'CompletePlan' + -- 'CompletePlan'. , socketClass :: SocketClass -- ^ Override the default 'CompleteSocketClass' by setting this. , dataDirectory :: DirectoryType -- ^ Override the default temporary data directory by passing in - -- 'Permanent' @DIRECTORY@ + -- 'Permanent' @DIRECTORY@. , port :: Last (Maybe Int) -- ^ A monoid for using an existing port (via 'Just' @PORT_NUMBER@) or - -- requesting a free port (via a 'Nothing') + -- requesting a free port (via a 'Nothing'). , temporaryDirectory :: Last FilePath -- ^ The directory used to create other temporary directories. Defaults - -- to \"/tmp\". + -- to @/tmp@. } deriving stock (Generic) deriving Semigroup via GenericSemigroup Config @@ -542,7 +579,9 @@ <> pretty (getLast temporaryDirectory) -- | Create a 'Plan' that sets the command line options of all processes --- (@initdb@, @postgres@ and @createdb@) using a +-- (@initdb@, @postgres@ and @createdb@). This the @generated@ plan +-- that is combined with the @extra@ plan from +-- 'Database.Postgres.Temp.startConfig'. toPlan :: Bool -- ^ Make @initdb@ options @@ -597,10 +636,10 @@ -- | Create all the temporary resources from a 'Config'. This also combines the --- 'Plan' from 'toPlan' with the @extraConfig@ passed in. +-- 'Plan' from 'toPlan' with the @extra@ 'Config' passed in. setupConfig :: Config - -- ^ @extraConfig@ to 'mappend' after the default config + -- ^ @extra@ 'Config' to 'mappend' after the @generated@ 'Config'. -> IO Resources setupConfig Config {..} = evalContT $ do envs <- lift getEnvironment @@ -622,18 +661,26 @@ completePlan envs finalPlan pure Resources {..} --- | Free the temporary resources created by 'setupConfig' +-- | Free the temporary resources created by 'setupConfig'. cleanupConfig :: Resources -> IO () cleanupConfig Resources {..} = do cleanupSocketConfig resourcesSocket cleanupDirectoryType resourcesDataDir +-- | Display a 'Config'. +-- +-- @since 1.12.0.0 +prettyPrintConfig :: Config -> String +prettyPrintConfig = show . pretty + -- | 'Resources' holds a description of the temporary folders (if there are any) -- and includes the final 'CompletePlan' that can be used with 'startPlan'. -- See 'setupConfig' for an example of how to create a 'Resources'. +-- +-- @since 1.12.0.0 data Resources = Resources { resourcesPlan :: CompletePlan - -- ^ Final 'CompletePlan'. See 'startPlan' for information on 'CompletePlan's + -- ^ Final 'CompletePlan'. See 'startPlan' for information on 'CompletePlan's. , resourcesSocket :: CompleteSocketClass -- ^ The 'CompleteSocketClass'. Used to track if a temporary directory was made -- as the socket location. @@ -641,7 +688,7 @@ -- ^ The data directory. Used to track if a temporary directory was used. , resourcesTemporaryDir :: FilePath -- ^ The directory where other temporary directories are created. - -- Usually \"/tmp\". + -- Usually @/tmp. } instance Pretty Resources where @@ -658,6 +705,8 @@ -- | Make the 'resourcesDataDir' 'CPermanent' so it will not -- get cleaned up. +-- +-- @since 1.12.0.0 makeResourcesDataDirPermanent :: Resources -> Resources makeResourcesDataDirPermanent r = r { resourcesDataDir = makePermanent $ resourcesDataDir r @@ -686,7 +735,7 @@ <> clientOptionsToPlan opts -- Wrap the 'Client.Options' in an appropiate --- 'PostgresPlan' +-- 'PostgresPlan'. clientOptionsToPlan :: Client.Options -> Plan clientOptionsToPlan opts = mempty { postgresPlan = mempty @@ -694,7 +743,7 @@ } } --- Create a 'Plan' given a user +-- Create a 'Plan' given a user. userToPlan :: String -> Plan userToPlan user = mempty { createDbConfig = pure $ mempty @@ -731,26 +780,32 @@ -- Lenses -- Most this code was generated with microlens-th ------------------------------------------------------------------------------- --- | Local Lens alias +-- | Local Lens alias. type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t --- | Local Lens' alias +-- | Local Lens' alias. type Lens' s a = Lens s s a a -- | Lens for 'inherit' +-- +-- @since 1.12.0.0 inheritL :: Lens' EnvironmentVariables (Last Bool) inheritL f_aj5e (EnvironmentVariables x_aj5f x_aj5g) = fmap (`EnvironmentVariables` x_aj5g) (f_aj5e x_aj5f) {-# INLINE inheritL #-} --- | Lens for 'specific' +-- | Lens for 'specific'. +-- +-- @since 1.12.0.0 specificL :: Lens' EnvironmentVariables (Map String String) specificL f_aj5i (EnvironmentVariables x_aj5j x_aj5k) = fmap (EnvironmentVariables x_aj5j) (f_aj5i x_aj5k) {-# INLINE specificL #-} --- | Lens for 'commandLine' +-- | Lens for 'commandLine'. +-- +-- @since 1.12.0.0 commandLineL :: Lens' ProcessConfig CommandLineArgs commandLineL @@ -763,7 +818,9 @@ (f_allv x_allx) {-# INLINE commandLineL #-} --- | Lens for 'environmentVariables' +-- | Lens for 'environmentVariables'. +-- +-- @since 1.12.0.0 environmentVariablesL :: Lens' ProcessConfig EnvironmentVariables environmentVariablesL @@ -777,6 +834,8 @@ {-# INLINE environmentVariablesL #-} -- | Lens for 'stdErr' +-- +-- @since 1.12.0.0 stdErrL :: Lens' ProcessConfig (Last Handle) stdErrL @@ -787,7 +846,9 @@ (f_allJ x_allO) {-# INLINE stdErrL #-} --- | Lens for 'stdIn' +-- | Lens for 'stdIn'. +-- +-- @since 1.12.0.0 stdInL :: Lens' ProcessConfig (Last Handle) stdInL @@ -800,7 +861,9 @@ (f_allQ x_allT) {-# INLINE stdInL #-} --- | Lens for 'stdOut' +-- | Lens for 'stdOut'. +-- +-- @since 1.12.0.0 stdOutL :: Lens' ProcessConfig (Last Handle) stdOutL @@ -813,7 +876,9 @@ (f_allX x_alm1) {-# INLINE stdOutL #-} --- | Lens for 'connectionOptions' +-- | Lens for 'connectionOptions'. +-- +-- @since 1.12.0.0 connectionOptionsL :: Lens' PostgresPlan Client.Options connectionOptionsL @@ -823,7 +888,9 @@ (f_am1y x_am1A) {-# INLINE connectionOptionsL #-} --- | Lens for 'postgresConfig' +-- | Lens for 'postgresConfig'. +-- +-- @since 1.12.0.0 postgresConfigL :: Lens' PostgresPlan ProcessConfig postgresConfigL @@ -833,14 +900,18 @@ (f_am1C x_am1D) {-# INLINE postgresConfigL #-} --- | Lens for 'postgresConfigFile' +-- | Lens for 'postgresConfigFile'. +-- +-- @since 1.12.0.0 postgresConfigFileL :: Lens' Plan [String] postgresConfigFileL f (plan@Plan{..}) = fmap (\x -> plan { postgresConfigFile = x }) (f postgresConfigFile) {-# INLINE postgresConfigFileL #-} --- | Lens for 'createDbConfig' +-- | Lens for 'createDbConfig'. +-- +-- @since 1.12.0.0 createDbConfigL :: Lens' Plan (Maybe ProcessConfig) createDbConfigL f (plan@Plan{..}) @@ -848,98 +919,126 @@ (f createDbConfig) {-# INLINE createDbConfigL #-} --- | Lens for 'dataDirectoryString' +-- | Lens for 'dataDirectoryString'. +-- +-- @since 1.12.0.0 dataDirectoryStringL :: Lens' Plan (Last String) dataDirectoryStringL f (plan@Plan{..}) = fmap (\x -> plan { dataDirectoryString = x }) (f dataDirectoryString) {-# INLINE dataDirectoryStringL #-} --- | Lens for 'initDbConfig' +-- | Lens for 'initDbConfig'. +-- +-- @since 1.12.0.0 initDbConfigL :: Lens' Plan (Maybe ProcessConfig) initDbConfigL f (plan@Plan{..}) = fmap (\x -> plan { initDbConfig = x }) (f initDbConfig) {-# INLINE initDbConfigL #-} --- | Lens for 'logger' +-- | Lens for 'logger'. +-- +-- @since 1.12.0.0 loggerL :: Lens' Plan (Last Logger) loggerL f (plan@Plan{..}) = fmap (\x -> plan { logger = x }) (f logger) {-# INLINE loggerL #-} --- | Lens for 'postgresPlan' +-- | Lens for 'postgresPlan'. +-- +-- @since 1.12.0.0 postgresPlanL :: Lens' Plan PostgresPlan postgresPlanL f (plan@Plan{..}) = fmap (\x -> plan { postgresPlan = x }) (f postgresPlan) {-# INLINE postgresPlanL #-} --- | Lens for 'connectionTimeout' +-- | Lens for 'connectionTimeout'. +-- +-- @since 1.12.0.0 connectionTimeoutL :: Lens' Plan (Last Int) connectionTimeoutL f (plan@Plan{..}) = fmap (\x -> plan { connectionTimeout = x }) (f connectionTimeout) {-# INLINE connectionTimeoutL #-} --- | Lens for 'resourcesDataDir' +-- | Lens for 'resourcesDataDir'. +-- +-- @since 1.12.0.0 resourcesDataDirL :: Lens' Resources CompleteDirectoryType resourcesDataDirL f (resources@Resources {..}) = fmap (\x -> resources { resourcesDataDir = x }) (f resourcesDataDir) {-# INLINE resourcesDataDirL #-} --- | Lens for 'resourcesPlan' +-- | Lens for 'resourcesPlan'. +-- +-- @since 1.12.0.0 resourcesPlanL :: Lens' Resources CompletePlan resourcesPlanL f (resources@Resources {..}) = fmap (\x -> resources { resourcesPlan = x }) (f resourcesPlan) {-# INLINE resourcesPlanL #-} --- | Lens for 'resourcesSocket' +-- | Lens for 'resourcesSocket'. +-- +-- @since 1.12.0.0 resourcesSocketL :: Lens' Resources CompleteSocketClass resourcesSocketL f (resources@Resources {..}) = fmap (\x -> resources { resourcesSocket = x }) (f resourcesSocket) {-# INLINE resourcesSocketL #-} --- | Lens for 'dataDirectory' +-- | Lens for 'dataDirectory'. +-- +-- @since 1.12.0.0 dataDirectoryL :: Lens' Config DirectoryType dataDirectoryL f (config@Config{..}) = fmap (\ x -> config { dataDirectory = x } ) (f dataDirectory) {-# INLINE dataDirectoryL #-} --- | Lens for 'plan' +-- | Lens for 'plan'. +-- +-- @since 1.12.0.0 planL :: Lens' Config Plan planL f (config@Config{..}) = fmap (\ x -> config { plan = x } ) (f plan) {-# INLINE planL #-} --- | Lens for 'port' +-- | Lens for 'port'. +-- +-- @since 1.12.0.0 portL :: Lens' Config (Last (Maybe Int)) portL f (config@Config{..}) = fmap (\ x -> config { port = x } ) (f port) {-# INLINE portL #-} --- | Lens for 'socketClass' +-- | Lens for 'socketClass'. +-- +-- @since 1.12.0.0 socketClassL :: Lens' Config SocketClass socketClassL f (config@Config{..}) = fmap (\ x -> config { socketClass = x } ) (f socketClass) {-# INLINE socketClassL #-} --- | Lens for 'socketClass' +-- | Lens for 'socketClass'. +-- +-- @since 1.12.0.0 temporaryDirectoryL :: Lens' Config (Last FilePath) temporaryDirectoryL f (config@Config{..}) = fmap (\ x -> config { temporaryDirectory = x } ) (f temporaryDirectory) {-# INLINE temporaryDirectoryL #-} --- | Lens for 'indexBased' +-- | Lens for 'indexBased'. +-- +-- @since 1.12.0.0 indexBasedL :: Lens' CommandLineArgs (Map Int String) indexBasedL @@ -949,7 +1048,9 @@ (f_amNr x_amNt) {-# INLINE indexBasedL #-} --- | Lens for 'keyBased' +-- | Lens for 'keyBased'. +-- +-- @since 1.12.0.0 keyBasedL :: Lens' CommandLineArgs (Map String (Maybe String)) keyBasedL diff --git a/src/Database/Postgres/Temp/Internal/Core.hs b/src/Database/Postgres/Temp/Internal/Core.hs --- a/src/Database/Postgres/Temp/Internal/Core.hs +++ b/src/Database/Postgres/Temp/Internal/Core.hs @@ -27,6 +27,8 @@ import Text.PrettyPrint.ANSI.Leijen hiding ((<$>)) -- | Internal events for debugging +-- +-- @since 1.12.0.0 data Event = StartPlan String -- ^ The first event. This useful for debugging @@ -46,6 +48,8 @@ -- | 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. +-- +-- @since 1.12.0.0 data StartError = StartPostgresFailed ExitCode -- ^ @postgres@ failed before a connection succeeded. Most likely this @@ -78,6 +82,8 @@ instance Exception StartError -- | A way to log internal 'Event's +-- +-- @since 1.12.0.0 type Logger = Event -> IO () -- | @postgres@ is not ready until we are able to successfully connect. @@ -329,7 +335,7 @@ ExitSuccess -> pure () e -> throwIO $ f e --- | Call 'createdb' and tee the output to return if there is an +-- | Call @createdb@ and tee the output to return if there is an -- an exception. Throws 'CreateDbFailed'. executeCreateDb :: CompleteProcessConfig -> IO () executeCreateDb config = do 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.12.0.0 +version: 1.12.0.1 synopsis: Start and stop a temporary postgres description: Start and stop a temporary postgres. See README.md homepage: https://github.com/jfischoff/tmp-postgres#readme