Safe Haskell | None |
---|---|
Language | Haskell2010 |
This is a client library for PostgreSQL Database which has following features.
faster and less CPU load
- especially on multi-core environments
pure Haskell implementations
- no libpq dependency
- easy to build even on Windows
implements extended query protocol
- about extended query protocol, see https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY
Typical Example
Prepare a following table.
CREATE TABLE person ( id serial PRIMARY KEY, name varchar(255) NOT NULL ); INSERT INTO person (name) VALUES ('Ada');
You can run like following to get the record whose ID is 1.
>>>
:set -XOverloadedStrings
>>>
:set -XFlexibleContexts
>>>
:set -XDataKinds
>>>
:set -XTypeFamilies
>>>
:set -XTypeApplications
>>>
>>>
import Database.PostgreSQL.Pure
>>>
import Data.Default.Class (def)
>>>
import Data.Int (Int32)
>>>
import Data.ByteString (ByteString)
>>>
import Data.Tuple.Only (Only (Only))
>>>
import Data.Tuple.List.Only ()
>>>
import Data.Tuple.Homotuple.Only ()
>>>
>>>
conn <- connect def
>>>
preparedStatementProcedure = parse "" "SELECT id, name FROM person WHERE id = $1" Nothing
>>>
portalProcedure <- bind @_ @2 @_ @_ "" BinaryFormat BinaryFormat (parameters conn) (const $ fail "") (Only (1 :: Int32)) preparedStatementProcedure
>>>
executedProcedure = execute @_ @_ @(Int32, ByteString) 0 (const $ fail "") portalProcedure
>>>
((_, _, e, _), _) <- sync conn executedProcedure
>>>
records e
[(1,"Ada")]
Hints for Type Errors
This module uses type level natural numbers as the number of columns of parameters and results.
If you have constranit errors about tuples, you may forget to import Data.Tuple.List
, Data.Tuple.Homotuple
and so on, because tuples are treated as vecters with typle level lengths.
You can use list interfaces with Database.PostgreSQL.Pure.List
, if these errors bother you.
Synopsis
- data Config = Config {}
- data Connection
- $sel:pid:Connection :: Connection -> Pid
- $sel:parameters:Connection :: Connection -> BackendParameters
- $sel:config:Connection :: Connection -> Config
- data Address
- type BackendParameters = Map ShortByteString ShortByteString
- type Pid = Int32
- withConnection :: Config -> (Connection -> IO a) -> IO a
- connect :: Config -> IO Connection
- disconnect :: Connection -> IO ()
- parse :: forall plen rlen. (KnownNat plen, KnownNat rlen, IsHomotupleItem plen Oid, IsHomotupleItem rlen ColumnInfo, IsHomotupleItem rlen Oid, IsHomolisttuple rlen Oid, IsHomolisttuple plen Oid, IsHomolisttuple rlen ColumnInfo) => PreparedStatementName -> Query -> Maybe (Homotuple plen Oid, Homotuple rlen Oid) -> PreparedStatementProcedure plen rlen
- bind :: forall rlen param m. (Bind ps, ToRecord param, KnownNat rlen, HasLength (Homotuple rlen ColumnInfo), MonadFail m) => PortalName -> FormatCode -> FormatCode -> BackendParameters -> StringEncoder -> param -> ps (Length param) rlen -> m (PortalProcedure (Length param) rlen)
- execute :: forall plen result. (Execute p, FromRecord result, IsHomotupleItem (Length result) ColumnInfo, IsHomolisttuple (Length result) ColumnInfo) => Word -> StringDecoder -> p plen (Length result) -> ExecutedProcedure plen (Length result) result
- flush :: Message m => Connection -> m -> IO (MessageResult m)
- sync :: Message m => Connection -> m -> IO (MessageResult m, TransactionState)
- close :: Close p => p -> CloseProcedure
- data PreparedStatement (parameterLength :: Nat) (resultLength :: Nat)
- data PreparedStatementProcedure (parameterLength :: Nat) (resultLength :: Nat)
- newtype PreparedStatementName = PreparedStatementName ByteString
- data Portal (parameterLength :: Nat) (resultLength :: Nat)
- data PortalProcedure (parameterLength :: Nat) (resultLength :: Nat)
- newtype PortalName = PortalName ByteString
- data Executed (parameterLength :: Nat) (resultLength :: Nat) r
- data ExecutedProcedure (parameterLength :: Nat) (resultLength :: Nat) r
- data ExecuteResult
- data CloseProcedure
- data CommandTag
- newtype Query = Query ByteString
- data FormatCode
- data ColumnInfo
- class Message m
- type family MessageResult m :: Type
- class Bind ps
- class Execute p
- class Close p
- type StringEncoder = String -> Either String ByteString
- type StringDecoder = ByteString -> Either String String
- class HasName r
- type family Name r :: Type
- class HasParameterOids r a
- name :: HasName r => r -> Name r
- parameterOids :: HasParameterOids r a => r -> a
- resultInfos :: (IsHomolisttuple m ColumnInfo, IsHomotupleItem m ColumnInfo) => PreparedStatement n m -> Homotuple m ColumnInfo
- result :: Executed n m r -> ExecuteResult
- records :: Executed n m r -> [r]
- begin :: ExecutedProcedure 0 0 ()
- commit :: ExecutedProcedure 0 0 ()
- rollback :: ExecutedProcedure 0 0 ()
- data TransactionState
- class FromField a where
- fromField :: MonadFail m => StringDecoder -> ColumnInfo -> Maybe ByteString -> m a
- class FromRecord a where
- fromRecord :: StringDecoder -> [ColumnInfo] -> Parser a
- class ToField a where
- toField :: MonadFail m => BackendParameters -> StringEncoder -> Maybe Oid -> FormatCode -> a -> m (Maybe ByteString)
- class ToRecord a where
- toRecord :: MonadFail m => BackendParameters -> StringEncoder -> Maybe [Oid] -> [FormatCode] -> a -> m [Maybe ByteString]
- data Raw where
- pattern Value :: ByteString -> Raw
- pattern Null :: Raw
- data Exception = Exception e => Exception e
- data ErrorResponse = ErrorResponse {}
- newtype ResponseParsingFailed = ResponseParsingFailed {}
- data Oid
Connection
A configuration of a connection.
Default configuration is def
, which is following.
Config
{ address =AddressResolved
$SockAddrInet
5432 $tupleToHostAddress
(127, 0, 0, 1) , user = "postgres" , password = "" , database = "" , sendingBufferSize = 2 ^ (12 ::Int
) , receptionBufferSize = 2 ^ (12 ::Int
) }
data Connection Source #
PostgreSQL connection.
$sel:pid:Connection :: Connection -> Pid Source #
The process ID of the server.
$sel:parameters:Connection :: Connection -> BackendParameters Source #
Set of server parameters.
$sel:config:Connection :: Connection -> Config Source #
Configuration of this connection.
IP address.
AddressResolved SockAddr | Address which is DNS resolved. |
AddressNotResolved HostName ServiceName | Address which is not DNS resolved. |
type BackendParameters = Map ShortByteString ShortByteString Source #
Set of server parameters.
withConnection :: Config -> (Connection -> IO a) -> IO a Source #
Bracket function for a connection.
disconnect :: Connection -> IO () Source #
To disconnect to the server.
Extended Query
:: (KnownNat plen, KnownNat rlen, IsHomotupleItem plen Oid, IsHomotupleItem rlen ColumnInfo, IsHomotupleItem rlen Oid, IsHomolisttuple rlen Oid, IsHomolisttuple plen Oid, IsHomolisttuple rlen ColumnInfo) | |
=> PreparedStatementName | A new name of prepared statement. |
-> Query | SQL whose placeoholder style is dollar style. |
-> Maybe (Homotuple plen Oid, Homotuple rlen Oid) | On |
-> PreparedStatementProcedure plen rlen |
To get the procedure to build the message of parsing SQL query and to parse its response.
:: (Bind ps, ToRecord param, KnownNat rlen, HasLength (Homotuple rlen ColumnInfo), MonadFail m) | |
=> PortalName | A new name of portal. |
-> FormatCode | Binary format or text format for the parameter. |
-> FormatCode | Binary format or text format for the results. |
-> BackendParameters | The set of the server parameters. |
-> StringEncoder | How to encode strings. |
-> param | Parameter for this query. |
-> ps (Length param) rlen | Prepared statement. |
-> m (PortalProcedure (Length param) rlen) |
To get the procedure to build the message of binding the parameter and to parse its response.
:: (Execute p, FromRecord result, IsHomotupleItem (Length result) ColumnInfo, IsHomolisttuple (Length result) ColumnInfo) | |
=> Word | How many records to get. “0” means unlimited. |
-> StringDecoder | How to decode strings. |
-> p plen (Length result) | Portal. |
-> ExecutedProcedure plen (Length result) result |
To get the procedure to build the message of execution and to parse its response.
flush :: Message m => Connection -> m -> IO (MessageResult m) Source #
To build and send the given message and a “Flush” message and to receive and parse those responses.
sync :: Message m => Connection -> m -> IO (MessageResult m, TransactionState) Source #
To build and send the given message and a “Sync” message and to receive and parse those responses.
close :: Close p => p -> CloseProcedure Source #
To build and send the “Close” message and to receive and parse its response.
data PreparedStatement (parameterLength :: Nat) (resultLength :: Nat) Source #
This represents a prepared statement which is already processed by a server.
parameterLength
is the number of columns of the parameter and resultLength
is the number of columns of the results.
This is the same with PreparedStatementProcedure
, Portal
, PortalProcedure
, Executed
and ExecutedProcedure
.
Instances
data PreparedStatementProcedure (parameterLength :: Nat) (resultLength :: Nat) Source #
This represents a prepared statemnt which is not yet processed by a server.
Instances
newtype PreparedStatementName Source #
Name of a prepared statement.
Instances
data Portal (parameterLength :: Nat) (resultLength :: Nat) Source #
This represents a portal which is already processed by a server.
Instances
Execute Portal Source # | |
Defined in Database.PostgreSQL.Pure execute :: (FromRecord result, IsHomotupleItem (Length result) ColumnInfo, IsHomolisttuple (Length result) ColumnInfo) => Word -> StringDecoder -> Portal plen (Length result) -> ExecutedProcedure plen (Length result) result Source # | |
HasField "name" (Portal n m) PortalName Source # | |
Defined in Database.PostgreSQL.Pure getField :: Portal n m -> PortalName # | |
Eq (Portal parameterLength resultLength) Source # | |
Show (Portal parameterLength resultLength) Source # | |
Close (Portal parameterLength resultLength) Source # | |
Defined in Database.PostgreSQL.Pure close :: Portal parameterLength resultLength -> CloseProcedure Source # | |
HasName (Portal n m) Source # | |
type Name (Portal n m) Source # | |
Defined in Database.PostgreSQL.Pure |
data PortalProcedure (parameterLength :: Nat) (resultLength :: Nat) Source #
This represents a portal which is not yet processed by a server.
Instances
newtype PortalName Source #
Name of a portal.
Instances
data Executed (parameterLength :: Nat) (resultLength :: Nat) r Source #
This represents a result of a “Execute” message which is already processed by a server.
data ExecutedProcedure (parameterLength :: Nat) (resultLength :: Nat) r Source #
This represents a result of a “Execute” message which is not yet processed by a server.
Instances
Show (ExecutedProcedure parameterLength resultLength r) Source # | |
Defined in Database.PostgreSQL.Pure showsPrec :: Int -> ExecutedProcedure parameterLength resultLength r -> ShowS # show :: ExecutedProcedure parameterLength resultLength r -> String # showList :: [ExecutedProcedure parameterLength resultLength r] -> ShowS # | |
Message (ExecutedProcedure parameterLength resultLength r) Source # | |
Defined in Database.PostgreSQL.Pure builder :: ExecutedProcedure parameterLength resultLength r -> Builder parser :: ExecutedProcedure parameterLength resultLength r -> Parser (MessageResult (ExecutedProcedure parameterLength resultLength r)) | |
type MessageResult (ExecutedProcedure n m r) Source # | |
Defined in Database.PostgreSQL.Pure |
data ExecuteResult Source #
Result of a “Execute” message.
ExecuteComplete CommandTag | All records gotten. |
ExecuteEmptyQuery | No records. |
ExecuteSuspended | Records are left yet. |
Instances
Eq ExecuteResult Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data (==) :: ExecuteResult -> ExecuteResult -> Bool # (/=) :: ExecuteResult -> ExecuteResult -> Bool # | |
Read ExecuteResult Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data readsPrec :: Int -> ReadS ExecuteResult # readList :: ReadS [ExecuteResult] # | |
Show ExecuteResult Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data showsPrec :: Int -> ExecuteResult -> ShowS # show :: ExecuteResult -> String # showList :: [ExecuteResult] -> ShowS # |
data CloseProcedure Source #
This represents a result of a “Close” message which is not yet processed by a server.
Instances
Show CloseProcedure Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data showsPrec :: Int -> CloseProcedure -> ShowS # show :: CloseProcedure -> String # showList :: [CloseProcedure] -> ShowS # | |
Message CloseProcedure Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Query | |
type MessageResult CloseProcedure Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data |
data CommandTag Source #
Command tag, which means which SQL command is completed.
InsertTag Oid Int | |
DeleteTag Int | |
UpdateTag Int | |
SelectTag Int | |
MoveTag Int | |
FetchTag Int | |
CopyTag Int | |
CreateTableTag | |
DropTableTag | |
BeginTag | |
CommitTag | |
RollbackTag | |
SetTag |
Instances
Eq CommandTag Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data (==) :: CommandTag -> CommandTag -> Bool # (/=) :: CommandTag -> CommandTag -> Bool # | |
Read CommandTag Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data readsPrec :: Int -> ReadS CommandTag # readList :: ReadS [CommandTag] # readPrec :: ReadPrec CommandTag # readListPrec :: ReadPrec [CommandTag] # | |
Show CommandTag Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data showsPrec :: Int -> CommandTag -> ShowS # show :: CommandTag -> String # showList :: [CommandTag] -> ShowS # |
SQL query.
This fromString
counts only ASCII, becouse it is the same with ByteString
.
data FormatCode Source #
Format code of patameters of results.
Instances
Enum FormatCode Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data succ :: FormatCode -> FormatCode # pred :: FormatCode -> FormatCode # toEnum :: Int -> FormatCode # fromEnum :: FormatCode -> Int # enumFrom :: FormatCode -> [FormatCode] # enumFromThen :: FormatCode -> FormatCode -> [FormatCode] # enumFromTo :: FormatCode -> FormatCode -> [FormatCode] # enumFromThenTo :: FormatCode -> FormatCode -> FormatCode -> [FormatCode] # | |
Eq FormatCode Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data (==) :: FormatCode -> FormatCode -> Bool # (/=) :: FormatCode -> FormatCode -> Bool # | |
Read FormatCode Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data readsPrec :: Int -> ReadS FormatCode # readList :: ReadS [FormatCode] # readPrec :: ReadPrec FormatCode # readListPrec :: ReadPrec [FormatCode] # | |
Show FormatCode Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data showsPrec :: Int -> FormatCode -> ShowS # show :: FormatCode -> String # showList :: [FormatCode] -> ShowS # |
data ColumnInfo Source #
Metadata of a column.
Instances
Eq ColumnInfo Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data (==) :: ColumnInfo -> ColumnInfo -> Bool # (/=) :: ColumnInfo -> ColumnInfo -> Bool # | |
Read ColumnInfo Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data readsPrec :: Int -> ReadS ColumnInfo # readList :: ReadS [ColumnInfo] # readPrec :: ReadPrec ColumnInfo # readListPrec :: ReadPrec [ColumnInfo] # | |
Show ColumnInfo Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Data showsPrec :: Int -> ColumnInfo -> ShowS # show :: ColumnInfo -> String # showList :: [ColumnInfo] -> ShowS # |
Instances
type family MessageResult m :: Type Source #
To convert a type which means that is is not prcessed by the server to a respective type which means that it is processed by the server.
Instances
This means that ps
is a objective of bind
.
Instances
Bind PreparedStatementProcedure Source # | |
Defined in Database.PostgreSQL.Pure bind :: (ToRecord param, KnownNat rlen, HasLength (Homotuple rlen ColumnInfo), MonadFail m) => PortalName -> FormatCode -> FormatCode -> BackendParameters -> StringEncoder -> param -> PreparedStatementProcedure (Length param) rlen -> m (PortalProcedure (Length param) rlen) Source # | |
Bind PreparedStatement Source # | |
Defined in Database.PostgreSQL.Pure bind :: (ToRecord param, KnownNat rlen, HasLength (Homotuple rlen ColumnInfo), MonadFail m) => PortalName -> FormatCode -> FormatCode -> BackendParameters -> StringEncoder -> param -> PreparedStatement (Length param) rlen -> m (PortalProcedure (Length param) rlen) Source # |
This means that p
is a objective of execute
.
Instances
Execute PortalProcedure Source # | |
Defined in Database.PostgreSQL.Pure execute :: (FromRecord result, IsHomotupleItem (Length result) ColumnInfo, IsHomolisttuple (Length result) ColumnInfo) => Word -> StringDecoder -> PortalProcedure plen (Length result) -> ExecutedProcedure plen (Length result) result Source # | |
Execute Portal Source # | |
Defined in Database.PostgreSQL.Pure execute :: (FromRecord result, IsHomotupleItem (Length result) ColumnInfo, IsHomolisttuple (Length result) ColumnInfo) => Word -> StringDecoder -> Portal plen (Length result) -> ExecutedProcedure plen (Length result) result Source # |
This means that p
is a objective of close
.
Instances
Close Portal Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Query close :: Portal -> CloseProcedure Source # | |
Close PreparedStatement Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Query | |
Close (Portal parameterLength resultLength) Source # | |
Defined in Database.PostgreSQL.Pure close :: Portal parameterLength resultLength -> CloseProcedure Source # | |
Close (PreparedStatement parameterLength resultLength) Source # | |
Defined in Database.PostgreSQL.Pure close :: PreparedStatement parameterLength resultLength -> CloseProcedure Source # |
type StringEncoder = String -> Either String ByteString Source #
Encoder of strings which may fail.
type StringDecoder = ByteString -> Either String String Source #
Decoder of strings which may fail.
This means that r
has a name
accesser.
Instances
HasName (PortalProcedure n m) Source # | |
Defined in Database.PostgreSQL.Pure type Name (PortalProcedure n m) :: Type Source # name :: PortalProcedure n m -> Name (PortalProcedure n m) Source # | |
HasName (Portal n m) Source # | |
HasName (PreparedStatementProcedure n m) Source # | |
Defined in Database.PostgreSQL.Pure type Name (PreparedStatementProcedure n m) :: Type Source # name :: PreparedStatementProcedure n m -> Name (PreparedStatementProcedure n m) Source # | |
HasName (PreparedStatement n m) Source # | |
Defined in Database.PostgreSQL.Pure type Name (PreparedStatement n m) :: Type Source # name :: PreparedStatement n m -> Name (PreparedStatement n m) Source # |
type family Name r :: Type Source #
Type of name of r
.
Instances
type Name (PortalProcedure n m) Source # | |
Defined in Database.PostgreSQL.Pure | |
type Name (Portal n m) Source # | |
Defined in Database.PostgreSQL.Pure | |
type Name (PreparedStatementProcedure n m) Source # | |
Defined in Database.PostgreSQL.Pure | |
type Name (PreparedStatement n m) Source # | |
Defined in Database.PostgreSQL.Pure |
class HasParameterOids r a Source #
This means that r
has a parameterOids
accesser.
Instances
(oids ~ Homotuple n Oid, Item oids ~ Oid, IsList oids) => HasParameterOids (PreparedStatement n m) oids Source # | |
Defined in Database.PostgreSQL.Pure parameterOids :: PreparedStatement n m -> oids Source # | |
(oids ~ Homotuple n Oid, Item oids ~ Oid, IsList oids) => HasParameterOids (PreparedStatementProcedure n m) (Maybe oids) Source # | |
Defined in Database.PostgreSQL.Pure parameterOids :: PreparedStatementProcedure n m -> Maybe oids Source # |
parameterOids :: HasParameterOids r a => r -> a Source #
To get OIDs of a parameter.
resultInfos :: (IsHomolisttuple m ColumnInfo, IsHomotupleItem m ColumnInfo) => PreparedStatement n m -> Homotuple m ColumnInfo Source #
To get a list of column infos of the result record.
Transaction
begin :: ExecutedProcedure 0 0 () Source #
To send BEGIN
SQL statement.
commit :: ExecutedProcedure 0 0 () Source #
To send COMMIT
SQL statement.
rollback :: ExecutedProcedure 0 0 () Source #
To send ROLLBACK
SQL statement.
data TransactionState Source #
Transaction state of a server.
Instances
Record
class FromField a where Source #
This means that a field can be decoded as a
.
fromField :: MonadFail m => StringDecoder -> ColumnInfo -> Maybe ByteString -> m a Source #
Decoder of a field.
Instances
class FromRecord a where Source #
This means that a record can be parsed as a
.
fromRecord :: StringDecoder -> [ColumnInfo] -> Parser a Source #
Decoder of a record.
Instances
class ToField a where Source #
This means that a
can be encoded to a field.
toField :: MonadFail m => BackendParameters -> StringEncoder -> Maybe Oid -> FormatCode -> a -> m (Maybe ByteString) Source #
Encoder of a field.
Instances
class ToRecord a where Source #
This means that a
can be encoded to a record.
toRecord :: MonadFail m => BackendParameters -> StringEncoder -> Maybe [Oid] -> [FormatCode] -> a -> m [Maybe ByteString] Source #
Encoder of a field.
Instances
Data without encoding nor decoding of a field.
pattern Value :: ByteString -> Raw | Not |
pattern Null :: Raw |
|
Exception
Root exception.
Exception
├ErrorResponse
└ResponseParsingFailed
Instances
data ErrorResponse Source #
This means that the server responds an error.
Instances
Eq ErrorResponse Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Exception (==) :: ErrorResponse -> ErrorResponse -> Bool # (/=) :: ErrorResponse -> ErrorResponse -> Bool # | |
Read ErrorResponse Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Exception readsPrec :: Int -> ReadS ErrorResponse # readList :: ReadS [ErrorResponse] # | |
Show ErrorResponse Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Exception showsPrec :: Int -> ErrorResponse -> ShowS # show :: ErrorResponse -> String # showList :: [ErrorResponse] -> ShowS # | |
Exception ErrorResponse Source # | |
newtype ResponseParsingFailed Source #
This means that the server responds an unknown message.
Instances
OID
OID.
Constant values are listed in Database.PostgreSQL.Pure.Oid
.
Instances
Eq Oid Source # | |
Num Oid Source # | |
Read Oid Source # | |
Show Oid Source # | |
ToField Oid Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Builder toField :: MonadFail m => BackendParameters -> StringEncoder -> Maybe Oid -> FormatCode -> Oid -> m (Maybe ByteString) Source # | |
FromField Oid Source # | |
Defined in Database.PostgreSQL.Pure.Internal.Parser fromField :: MonadFail m => StringDecoder -> ColumnInfo -> Maybe ByteString -> m Oid Source # | |
Convertible Oid SqlTypeId Source # | |
Defined in Database.HDBC.PostgreSQL.Pure safeConvert :: Oid -> ConvertResult SqlTypeId # |