| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
PostgreSQL
Description
PostgreSQL client
Have a look at the individual sub-sections to find out more about the respective concepts.
Synopsis
- data Template a
- renderTemplate :: Template a -> Statement a
- tpl :: QuasiQuoter
- code :: Text -> Template a
- identifier :: Text -> Template a
- string :: Text -> Template a
- param :: forall b a. Param b => (a -> b) -> Template a
- paramWith :: Info (a -> Value) -> Template a
- constant :: forall b a. Param b => b -> Template a
- data Statement a
- stmt :: QuasiQuoter
- data PreparedStatement a
- execute :: (Executable statement, Query query) => statement param -> param -> query (NativeResult query)
- execute_ :: (Executable statement, Query query) => statement param -> param -> query ()
- query :: (Executable statement, Query query, AutoRow row) => statement param -> param -> query (Vector row)
- queryWith :: (Executable statement, Query query) => statement param -> param -> Result row -> query row
- withPreparedStatement :: Query query => Statement a -> (PreparedStatement a -> query r) -> query r
- class Monad query => Query query
- class Query query => RunQuery query m | m -> query where
- runQueryThrow :: (MonadThrow m, RunQuery query m) => query a -> m a
- data ConnectionPoolT m a
- runConnectionPoolT :: (MonadIO m, MonadConc m) => m Connection -> Settings -> ConnectionPoolT m a -> m a
- defaultConnectionPoolSettings :: Settings
- data Result a
- ignored :: Result ()
- single :: Row a -> Result a
- first :: Row a -> Result a
- many :: Row a -> Result (Vector a)
- affectedRows :: Result Integer
- data Row a
- column :: AutoColumn a => Row a
- columnWith :: Column a -> Row a
- fixedColumn :: AutoColumn a => ColumnNum -> Row a
- fixedColumnWith :: ColumnNum -> Column a -> Row a
- namedColumn :: AutoColumn a => ByteString -> Row a
- namedColumnWith :: ByteString -> Column a -> Row a
- class AutoRow a where
- class AutoColumnDelegate a
- genericRow :: (Generic a, AutoRow (Rep a Void)) => Row a
- newtype Named (name :: Symbol) a = Named {
- fromNamed :: a
- newtype Fixed (index :: Nat) a = Fixed {
- fromFixed :: a
- data Column a
- class AutoColumn a where
- autoColumn :: Column a
- newtype Readable a = Readable a
- data Error
- type Errors = NonEmpty Error
- data ProcessorError
- = ColumnParserError { }
- | CellParserError { }
- | NotEnoughColumns { }
- | MissingNamedColumn { }
- type ProcessorErrors = NonEmpty ProcessorError
- data ResultError
- = BadResultStatus { }
- | NoRows
- | MultipleRows { }
- | FailedToParseAffectedRows { }
- type ResultErrors = NonEmpty ResultError
- data ParserError
- type ParserErrors = NonEmpty ParserError
- data Format
- data Oid
- data ColumnNum
- data RowNum
- data Value
- = Null
- | Value ByteString
- data RawValue = RawValue {}
Templates and statements
Writing a statement usually involves writing it as a Template and then rendering it
as a Statement. The latter can optionally be prepared to become a
PreparedStatement.
Templates and statements can take an input. The type of that input is determined by the type
parameter that Template, Statement and 'Statement.PreparedStatement
expose.
Templates
Templates can be constructed using the tpl quasi-quoter or manually using the
provided combinators.
SQL statement template
Since: 0.0.0
Instances
| Contravariant Template Source # | Since: 0.0.0 |
| (HasField n r a, Param a) => IsLabel n (Template r) Source # |
#myParam === param (getField @"myParam") Use this with a database: data MyFoo = MyFoo { bar :: Int, baz :: String }
myStatementTpl :: Template MyFoo
myStatementTpl = "SELECT * FROM my_foo WHERE bar = " <> #bar <> " AND baz = " <> #bazSince: 0.0.0 |
Defined in PostgreSQL.Statement | |
| IsString (Template a) Source # |
"my code" === code "my code" Since: 0.0.0 |
Defined in PostgreSQL.Statement Methods fromString :: String -> Template a # | |
| Semigroup (Template a) Source # | Since: 0.0.0 |
| Monoid (Template a) Source # | Since: 0.0.0 |
renderTemplate :: Template a -> Statement a Source #
Render the SQL statement.
Since: 0.0.0
Quasi-quotation
tpl :: QuasiQuoter Source #
Combinators
Template implements Semigroup and Monoid. These can be used to compose the
following combinators.
It also supports IsString which helps to create templates from string literals.
You may use overloaded labels to refer to parameters.
#my_param === param my_param
my_param shall be a record field of data type.
identifier :: Text -> Template a Source #
Create a code segment that mentions the given identifier (e.g. table or column name).
Since: 0.0.0
string :: Text -> Template a Source #
Encase the given string literal in single quotes. Single quotes in the literal are automatically escaped.
Since: 0.0.0
Statements
Statements are created using the stmt quasi-quoter or by rendering a
Template via renderTemplate.
Rendered SQL statement
Since: 0.0.0
Instances
| Contravariant Statement Source # | Since: 0.0.0 |
| Executable Statement Source # | Since: 0.0.0 |
Defined in PostgreSQL.Query.Class | |
stmt :: QuasiQuoter Source #
Produces a Statement expression.
[stmt| SELECT $param * 2 |]
Use $$ to render a single $.
Parameters
Use $param or ${param} to reference a query parameter.
[stmt| ${x} |] is equivalent to param x
Substitutions
Use $(substr) to embed another Template where substr :: .Template a
[stmt| $(x) |] is equivalent to x.
Examples
data MyParams = MyParams { foo :: Int, bar :: Text }
myStatement :: Statement MyParams
myStatement = [stmt| SELECT baz FROM my_table WHERE foo > ${foo} AND bar = ${bar} |]Since: 0.0.0
Prepared statements
PreparedStatements can be obtained using withPreparedStatement.
This can be useful when executing a statement repeatedly and you want to save some time on parsing and type-checking the statement on the database server.
data PreparedStatement a Source #
Prepared statement
Since: 0.0.0
Instances
| Contravariant PreparedStatement Source # | Since: 0.0.0 |
Defined in PostgreSQL.Statement Methods contramap :: (a -> b) -> PreparedStatement b -> PreparedStatement a # (>$) :: b -> PreparedStatement b -> PreparedStatement a # | |
| Executable PreparedStatement Source # | Since: 0.0.0 |
Defined in PostgreSQL.Query.Class Methods execute :: Query query => PreparedStatement param -> param -> query (NativeResult query) Source # | |
Query execution
Queries are built using any type query that satisfies Query query
In most cases you will use runQuery or runQueryThrow to then actually run the
query.
ConnectionPoolT is a useful interpreter for the RunQuery effect.
Combinators
Arguments
| :: (Executable statement, Query query) | |
| => statement param | Statement |
| -> param | Statement input |
| -> query (NativeResult query) |
Execute a statement.
Since: 0.0.0
Arguments
| :: (Executable statement, Query query) | |
| => statement param | Statement |
| -> param | Statement input |
| -> query () |
Like execute but does not concern itself with the result handle.
Since: 0.0.0
Arguments
| :: (Executable statement, Query query, AutoRow row) | |
| => statement param | Query statement |
| -> param | Query parameter |
| -> query (Vector row) |
Perform a parameterized query.
Since: 0.0.0
Arguments
| :: (Executable statement, Query query) | |
| => statement param | Query statement |
| -> param | Query parameter |
| -> Result row | Result row processor |
| -> query row |
Perform a parameterized query. This also lets you specify the result processor explicitly.
Since: 0.0.0
withPreparedStatement Source #
Arguments
| :: Query query | |
| => Statement a | Statement to prepare |
| -> (PreparedStatement a -> query r) | Scope within the prepared statement may be used |
| -> query r |
Prepare a statement. The prepared statement is only valid within the provided continuation.
Since: 0.0.0
Evaluation
class Monad query => Query query Source #
PostgreSQL query
Since: 0.0.0
Minimal complete definition
executeStatement, executePreparedStatement, withPreparedStatement, processResult
Instances
| (MonadIO m, MonadMask m) => Query (QueryT m) Source # | |
Defined in PostgreSQL.Query Associated Types type NativeResult (QueryT m) Source # Methods executeStatement :: Statement a -> a -> QueryT m (NativeResult (QueryT m)) Source # executePreparedStatement :: PreparedStatement a -> a -> QueryT m (NativeResult (QueryT m)) Source # withPreparedStatement :: Statement a -> (PreparedStatement a -> QueryT m r) -> QueryT m r Source # processResult :: NativeResult (QueryT m) -> Result a -> QueryT m a Source # | |
class Query query => RunQuery query m | m -> query where Source #
PostgreSQL queries can be executed in m
Since: 0.0.0
Instances
| (RunQuery query m, Monad m, MonadTrans t) => RunQuery query (t m) Source # | Since: 0.0.0 |
| (MonadMask m, MonadIO m) => RunQuery (QueryT m) (ConnectionPoolT m) Source # | Since: 0.0.0 |
Defined in PostgreSQL.ConnectionPool | |
runQueryThrow :: (MonadThrow m, RunQuery query m) => query a -> m a Source #
Like runQuery but throws the first error instead.
Since: 0.0.0
Interpreters
data ConnectionPoolT m a Source #
Interpreter for RunQuery which dispatches queries to a pool of database connections
Since: 0.0.0
Instances
Arguments
| :: (MonadIO m, MonadConc m) | |
| => m Connection | Action to establish a new connection |
| -> Settings | Connection pool settings |
| -> ConnectionPoolT m a | Transformer to run |
| -> m a |
Run connection pool transformer.
Since: 0.0.0
defaultConnectionPoolSettings :: Settings Source #
Default settings for the connection pool
Since: 0.0.0
Result processing
Top level
Query result
Since: 0.0.0
first :: Row a -> Result a Source #
Process only the first row. There may be more rows in the result set, but they won't be touched.
Since: 0.0.0
affectedRows :: Result Integer Source #
Get the number of affected rows.
Since: 0.0.0
Row level
Result row parser
Since: 0.0.0
column :: AutoColumn a => Row a Source #
Floating column using the default Column for a
The position of this column is depenend on other floating columns left of it.
For example:
foo = baz <$> column <*> column <*> column -- ^ A ^ B ^ C
Here, A would be at index 0, B at 1 and C at 2.
Other non-floating columns do not impact the column indices.
Since: 0.0.0
fixedColumn :: AutoColumn a => ColumnNum -> Row a Source #
Fixed-position column using the default Column for a
Since: 0.0.0
fixedColumnWith :: ColumnNum -> Column a -> Row a Source #
Same as fixedColumn but lets you specify the Column.
Since: 0.0.0
namedColumn :: AutoColumn a => ByteString -> Row a Source #
Named column using the default Column for a
Since: 0.0.0
namedColumnWith :: ByteString -> Column a -> Row a Source #
Same as namedColumn but lets you specify the Column.
Since: 0.0.0
class AutoRow a where Source #
Default row parser for a type
Since: 0.0.0
Minimal complete definition
Nothing
Methods
Instances
class AutoColumnDelegate a Source #
This class is used to intercept instance heads like Fixed and Named that have special
additional meaning. For most cases it will delegate to AutoColumn.
Use this class instead of AutoColumn when implementing AutoRow instances.
Since: 0.0.0
Minimal complete definition
autoColumnDelegate
Instances
| AutoColumn a => AutoColumnDelegate a Source # | Passthrough to Since: 0.0.0 |
Defined in PostgreSQL.Result.Row Methods autoColumnDelegate :: Row a | |
| (KnownSymbol name, AutoColumn a) => AutoColumnDelegate (Named name a) Source # | Uses Since: 0.0.0 |
Defined in PostgreSQL.Result.Row Methods autoColumnDelegate :: Row (Named name a) | |
| (KnownNat index, AutoColumn a) => AutoColumnDelegate (Fixed index a) Source # | Uses Since: 0.0.0 |
Defined in PostgreSQL.Result.Row Methods autoColumnDelegate :: Row (Fixed index a) | |
genericRow :: (Generic a, AutoRow (Rep a Void)) => Row a Source #
Generic row parser
You can use this with your Generic-implementing data types.
data Foo = Foo
{ bar :: Integer
, baz :: Text
}
deriving Generic
fooRow :: Row Foo
fooRow = genericRowSince: 0.0.0
newtype Named (name :: Symbol) a Source #
Value for a named column
Since: 0.0.0
Instances
| (KnownSymbol name, AutoColumn a) => AutoColumnDelegate (Named name a) Source # | Uses Since: 0.0.0 |
Defined in PostgreSQL.Result.Row Methods autoColumnDelegate :: Row (Named name a) | |
newtype Fixed (index :: Nat) a Source #
Value for a column at a fixed location
Since: 0.0.0
Instances
| (KnownNat index, AutoColumn a) => AutoColumnDelegate (Fixed index a) Source # | Uses Since: 0.0.0 |
Defined in PostgreSQL.Result.Row Methods autoColumnDelegate :: Row (Fixed index a) | |
Column level
Result column parser
Since: 0.0.0
class AutoColumn a where Source #
Default column parser for a type
Since: 0.0.0
Instances
Provides a AutoColumn instance using the Read for a
Since: 0.0.0
Constructors
| Readable a |
Instances
| Read a => AutoColumn (Readable a) Source # | Since: 0.0.0 |
Defined in PostgreSQL.Result.Column Methods autoColumn :: Column (Readable a) Source # | |
Errors
Since: 0.0.0
Constructors
| ErrorDuringProcessing ProcessorError | Occurs when processing the result table |
| ErrorDuringValidation ResultError | Occurs when validating the result object |
Instances
| Eq Error Source # | Since: 0.0.0 |
| Ord Error Source # | Since: 0.0.0 |
| Show Error Source # | Since: 0.0.0 |
| Exception Error Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods toException :: Error -> SomeException # fromException :: SomeException -> Maybe Error # displayException :: Error -> String # | |
| Monad m => MonadError Errors (QueryT m) Source # | Since: 0.0.0 |
Defined in PostgreSQL.Query Methods throwError :: Errors -> QueryT m a # catchError :: QueryT m a -> (Errors -> QueryT m a) -> QueryT m a # | |
data ProcessorError Source #
Error that may occur during processing
Since: 0.0.0
Instances
| Eq ProcessorError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods (==) :: ProcessorError -> ProcessorError -> Bool # (/=) :: ProcessorError -> ProcessorError -> Bool # | |
| Ord ProcessorError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods compare :: ProcessorError -> ProcessorError -> Ordering # (<) :: ProcessorError -> ProcessorError -> Bool # (<=) :: ProcessorError -> ProcessorError -> Bool # (>) :: ProcessorError -> ProcessorError -> Bool # (>=) :: ProcessorError -> ProcessorError -> Bool # max :: ProcessorError -> ProcessorError -> ProcessorError # min :: ProcessorError -> ProcessorError -> ProcessorError # | |
| Show ProcessorError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods showsPrec :: Int -> ProcessorError -> ShowS # show :: ProcessorError -> String # showList :: [ProcessorError] -> ShowS # | |
type ProcessorErrors = NonEmpty ProcessorError Source #
data ResultError Source #
Error that occurs when validating the result
Since: 0.0.0
Constructors
| BadResultStatus | |
Fields | |
| NoRows | |
| MultipleRows | |
Fields | |
| FailedToParseAffectedRows | |
Fields | |
Instances
| Eq ResultError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types | |
| Ord ResultError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods compare :: ResultError -> ResultError -> Ordering # (<) :: ResultError -> ResultError -> Bool # (<=) :: ResultError -> ResultError -> Bool # (>) :: ResultError -> ResultError -> Bool # (>=) :: ResultError -> ResultError -> Bool # max :: ResultError -> ResultError -> ResultError # min :: ResultError -> ResultError -> ResultError # | |
| Show ResultError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods showsPrec :: Int -> ResultError -> ShowS # show :: ResultError -> String # showList :: [ResultError] -> ShowS # | |
type ResultErrors = NonEmpty ResultError Source #
data ParserError Source #
Error that occurs when parsing a column
Since: 0.0.0
Constructors
| UnsupportedFormat Format | |
| UnsupportedOid Oid |
Instances
| Eq ParserError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types | |
| Ord ParserError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods compare :: ParserError -> ParserError -> Ordering # (<) :: ParserError -> ParserError -> Bool # (<=) :: ParserError -> ParserError -> Bool # (>) :: ParserError -> ParserError -> Bool # (>=) :: ParserError -> ParserError -> Bool # max :: ParserError -> ParserError -> ParserError # min :: ParserError -> ParserError -> ParserError # | |
| Show ParserError Source # | Since: 0.0.0 |
Defined in PostgreSQL.Types Methods showsPrec :: Int -> ParserError -> ShowS # show :: ParserError -> String # showList :: [ParserError] -> ShowS # | |
type ParserErrors = NonEmpty ParserError Source #
Common types
Numberic column identifier
Since: 0.0.0
Instances
| Bounded ColumnNum Source # | |
| Enum ColumnNum Source # | |
Defined in PostgreSQL.Types Methods succ :: ColumnNum -> ColumnNum # pred :: ColumnNum -> ColumnNum # fromEnum :: ColumnNum -> Int # enumFrom :: ColumnNum -> [ColumnNum] # enumFromThen :: ColumnNum -> ColumnNum -> [ColumnNum] # enumFromTo :: ColumnNum -> ColumnNum -> [ColumnNum] # enumFromThenTo :: ColumnNum -> ColumnNum -> ColumnNum -> [ColumnNum] # | |
| Eq ColumnNum Source # | |
| Integral ColumnNum Source # | |
Defined in PostgreSQL.Types Methods quot :: ColumnNum -> ColumnNum -> ColumnNum # rem :: ColumnNum -> ColumnNum -> ColumnNum # div :: ColumnNum -> ColumnNum -> ColumnNum # mod :: ColumnNum -> ColumnNum -> ColumnNum # quotRem :: ColumnNum -> ColumnNum -> (ColumnNum, ColumnNum) # divMod :: ColumnNum -> ColumnNum -> (ColumnNum, ColumnNum) # | |
| Num ColumnNum Source # | |
Defined in PostgreSQL.Types | |
| Ord ColumnNum Source # | |
| Read ColumnNum Source # | |
| Real ColumnNum Source # | |
Defined in PostgreSQL.Types Methods toRational :: ColumnNum -> Rational # | |
| Show ColumnNum Source # | |
Numberic row identifier
Since: 0.0.0
Instances
| Bounded RowNum Source # | |
| Enum RowNum Source # | |
Defined in PostgreSQL.Types | |
| Eq RowNum Source # | |
| Integral RowNum Source # | |
Defined in PostgreSQL.Types | |
| Num RowNum Source # | |
| Ord RowNum Source # | |
| Read RowNum Source # | |
| Real RowNum Source # | |
Defined in PostgreSQL.Types Methods toRational :: RowNum -> Rational # | |
| Show RowNum Source # | |
Value
Since: 0.0.0
Constructors
| Null | |
| Value ByteString |
The raw cell value
Since: 0.0.0
Constructors
| RawValue | |
Fields
| |