Database.PostgreSQL.Devel

Functions for initializing self-contained local postgreSQL database clusters (useful in development more than production).

Documentation

createLocalDB :: FilePath -> IO ()

Create a directory for a local database cluster entirely self-contained within one directory. This is accomplished by creating a new PostgreSQL database cluster in the directory and setting the following configuration options in postgresql.conf:

• listen_address is set to empty (i.e., ''), so that no TCP socket is bound, avoiding conflicts with any other running instaces of PostgreSQL.
• logging_collector is set to yes, so that all message logs are kept in the pg_log subdirectory of the directory you specified.

Note this function does not start a postgres server after creating the directory. You will seperately need to start the server using startLocalDB or initLocalDB. (And note that initLocalDB already calls createLocalDB if the directory does not exist or is empty. Hence the primary use of this function is if you want to call configLocalDB between createLocalDB and startLocalDB.)

configLocalDB :: FilePath -> [(String, String)] -> IO ()

Set configuration parameters on a database by editing the postgresql.conf file. Takes the database directory and a list of (parameter, full-line) pairs. For example, when creating a throw-away database cluster you later intend to discard, you might say:

configLocalDB dbpath [("fsync", "fsync = off")]

Note that the second element of each pair is the complete configuration line. It is not correct to say:

configLocalDB dbpath [("fsync", "off")]   -- INCORRECT

startLocalDB :: FilePath -> IO ConnectInfo

Start a local database if the server is not already running. Otherwise, does nothing, but returns a ConnectInfo in either case. The database server will continue running after the current process exits (but see stopLocalDB).

initLocalDB :: FilePath -> IO ConnectInfo

A combination of createLocalDB and startLocalDB.

The parameter is a PostgreSQL data directory. If the directory is empty or does not exist, this function creates a new database cluster (via createLocalDB). Then, if a database server is not already running for the directory, starts a server. No matter what, returns a ConnectInfo that will connect to the server running on this local database.

Note that if initLocalDB starts a postgres server, the server process will continue running after the process that called initLocalDB exits. This is normally fine. Since multiple client processes may access the same PostgreSQL database, it makes sense for the first client to start the database and no one to stop it. See stopLocalDB if you wish to stop the server process (which you should always do before deleting a test cluster). See also withTempDB to create a temporary cluster for the purposes of running a test suite.

stopLocalDB :: FilePath -> IO ()

Stop the server for a local database cluster entirely self-contained within one directory. You must call this before deleting the directory, or else stray postgres processes will linger forever. If the argument is the empty string, looks for the database directory in the PGDATA environment variable.

setLocalDB :: FilePath -> IO String

Set environment variables to make a local database cluster the default. Also returns shell commands you can eval or cut-and-paste into your shell to make pg_ctl and psql access a local database cluster.

withTempDB :: (ConnectInfo -> IO a) -> IO a

Run a function with a completely fresh database cluster that gets deleted on return. Since the entire database is blown away when the function returns, withTempDB is obviously only useful for test suites.

resetConnection :: Connection -> IO ()

Reset a connection to its default state before re-cycling it for another thread or request.