Orville.PostgreSQL.Raw.Connection

Since: 1.0.0.0

Documentation

data ConnectionOptions

Configuration options to pass to createConnectionPool to specify the parameters for the pool and the connections that it creates.

Since: 1.0.0.0

Constructors

ConnectionOptions

Fields

• connectionString :: String

  A PostgreSQL connection string.

• connectionNoticeReporting :: NoticeReporting

  Whether or not notice reporting from LibPQ should be enabled.

• connectionPoolStripes :: StripeOption

  Number of stripes in the connection pool.

• connectionPoolLingerTime :: NominalDiffTime

  Linger time before closing an idle connection.

• connectionPoolMaxConnections :: MaxConnections

  Controls the number of connections available in the ConnectionPool.

data NoticeReporting

An option for createConnectionPool that indicates whether LibPQ should print notice reports for warnings to the console.

Since: 1.0.0.0

Constructors

EnableNoticeReporting

DisableNoticeReporting

data MaxConnections

Values for the connectionMaxConnections field of ConnectionOptions.

Since: 1.0.0.0

Constructors

MaxConnectionsTotal Int

MaxConnectionsTotal creates a connection pool that will never allocate more than the specified number of connections. The total count of connections will be spread evenly across the all the stripes in the pool. If the number of stripes does not divide the total count evenly, any remainder will be unused.

MaxConnectionsPerStripe Int

MaxConnectionsPerStripe creates a connection pool that will allocate up to the specified number of connections in each stripe. In this case the total possible number of simultaneous connections will be this value multiplied by the number of stripes.

data StripeOption

Values for the connectionPoolStripes field of ConnectionOptions.

Since: 1.0.0.0

Constructors

OneStripePerCapability

OneStripePerCapability will cause the connection pool to be set up with one stripe for each capability (processor thread) available to the runtime. This is the best option for multi-threaded connection pool performance.

StripeCount Int

StripeCount will cause the connection pool to be set up with the specified number of stripes, regardless of how many capabilities the runtime has.

data ConnectionPool

Orville always uses a connection pool to manage the number of open connections to the database. See ConnectionConfig and createConnectionPool to find how to create a ConnectionPool.

Since: 1.0.0.0

createConnectionPool :: ConnectionOptions -> IO ConnectionPool

createConnectionPool allocates a pool of connections to a PostgreSQL server.

Since: 1.0.0.0

data Connection

An Orville handler for a LibPQ connection.

Since: 1.0.0.0

withPoolConnection :: ConnectionPool -> (Connection -> IO a) -> IO a

Allocates a connection from the pool and performs an action with it. This function will block if the maximum number of connections is reached.

Since: 1.0.0.0

executeRaw :: Connection -> ByteString -> [Maybe PgTextFormatValue] -> IO Result

executeRaw runs a given SQL statement returning the raw underlying result.

All handling of stepping through the result set is left to the caller. This potentially leaves connections open much longer than one would expect if all of the results are not iterated through immediately *and* the data copied. Use with caution.

Since: 1.0.0.0

quoteStringLiteral :: Connection -> ByteString -> IO Builder

Escapes and quotes a string for use as a literal within a SQL command that will be executed on the given connection. This uses the PQescapeStringConn function from LibPQ, which takes the character encoding of the connection into account. Note that while PQescapeStringConn does not surround the literal with quotes, this function does for the sake of symmetry with quoteIdentifier.

This function returns a Builder so that the result can be included in a builder being constructed for the surrounding SQL command without making an additional copy of the ByteString returned by LibPQ for the sake of adding the surrounding quotes.

Since: 1.0.0.0

quoteIdentifier :: Connection -> ByteString -> IO Builder

Escapes and quotes a string for use as an identifier within a SQL command that will be executed on the given connection. This uses the PQescapeIdentifier function from LibPQ, which takes the character encoding of the connection into account and also applies the quotes.

Although this function does not need to copy the ByteString returned by LibPQ to add the quotes (since LibPQ already added them), it returns a Builder nonetheless to maintain symmetry with quoteStringLiteral.

Since: 1.0.0.0

data ConnectionUsedAfterCloseError

Orville throws as ConnectionUsedAfterCloseError if it attempts to use a Connection value after it has already been closed. If this occurs, it is a bug in Orville.

Since: 1.0.0.0

Instances

Exception ConnectionUsedAfterCloseError

Defined in Orville.PostgreSQL.Raw.Connection

Methods

toException :: ConnectionUsedAfterCloseError -> SomeException

fromException :: SomeException -> Maybe ConnectionUsedAfterCloseError

displayException :: ConnectionUsedAfterCloseError -> String

Show ConnectionUsedAfterCloseError

Defined in Orville.PostgreSQL.Raw.Connection

Methods

showsPrec :: Int -> ConnectionUsedAfterCloseError -> ShowS

show :: ConnectionUsedAfterCloseError -> String

showList :: [ConnectionUsedAfterCloseError] -> ShowS

data ConnectionError

Orville throws a ConnectionError on an error reported by the underlying LibPQ connection that does not come directly from executing SQL. This could could represent an inability to open a new database connection, but could also represent other errors such as an error while quoting a database identifier.

Since: 1.0.0.0

Instances

Exception ConnectionError

Defined in Orville.PostgreSQL.Raw.Connection

Methods

toException :: ConnectionError -> SomeException

fromException :: SomeException -> Maybe ConnectionError

displayException :: ConnectionError -> String

Show ConnectionError

Defined in Orville.PostgreSQL.Raw.Connection

Methods

showsPrec :: Int -> ConnectionError -> ShowS

show :: ConnectionError -> String

showList :: [ConnectionError] -> ShowS

data SqlExecutionError

Orville throws a SqlExecutionError when an error is reported by the underlying LibPQ connection during an attempt to execute SQL.

Since: 1.0.0.0

Constructors

SqlExecutionError

Fields

• sqlExecutionErrorExecStatus :: Maybe ExecStatus

  The underlying LibPQ execution status.

• sqlExecutionErrorMessage :: ByteString

  Error message reported by PostgreSQL.

• sqlExecutionErrorSqlState :: Maybe ByteString

  Any SQL state value reported by PostgreSQL. This can be used to determine what kind of error happened without needing to parse the error message. See https://www.postgresql.org/docs/current/errcodes-appendix.html.

• sqlExecutionErrorSqlQuery :: ByteString

  The SQL query that was being run when the error occurred.

Instances

Exception SqlExecutionError

Defined in Orville.PostgreSQL.Raw.Connection

Methods

toException :: SqlExecutionError -> SomeException

fromException :: SomeException -> Maybe SqlExecutionError

displayException :: SqlExecutionError -> String

Show SqlExecutionError

Defined in Orville.PostgreSQL.Raw.Connection

Methods

showsPrec :: Int -> SqlExecutionError -> ShowS

show :: SqlExecutionError -> String

showList :: [SqlExecutionError] -> ShowS