postgresql-typed-0.5.1: PostgreSQL interface with compile-time SQL type checking, optional HDBC backend

Safe HaskellNone
LanguageHaskell98

Database.PostgreSQL.Typed.Query

Synopsis

Documentation

class PGQuery q a | q -> a where Source #

Minimal complete definition

pgRunQuery, unsafeModifyQuery

Methods

pgRunQuery :: PGConnection -> q -> IO (Int, [a]) Source #

Execute a query and return the number of rows affected (or -1 if not known) and a list of results.

unsafeModifyQuery :: q -> (ByteString -> ByteString) -> q Source #

Change the raw SQL query stored within this query. This is unsafe because the query has already been type-checked, so any change must not change the number or type of results or placeholders (so adding additional static WHERE or ORDER BY clauses is generally safe). This is useful in cases where you need to construct some part of the query dynamically, but still want to infer the result types. If you want to add dynamic values to the query, it's best to use pgSafeLiteral. For example:

[pgSQL|SELECT a FROM t|] `unsafeModifyQuery` (<> (" WHERE a = " <> pgSafeLiteral x))

type PGSimpleQuery = QueryParser SimpleQuery Source #

A simple one-shot query that simply substitutes literal representations of parameters for placeholders.

type PGPreparedQuery = QueryParser PreparedQuery Source #

A prepared query that automatically is prepared in the database the first time it is run and bound with new parameters each subsequent time.

rawPGSimpleQuery :: ByteString -> PGSimpleQuery PGValues Source #

Make a simple query directly from a query string, with no type inference

rawPGPreparedQuery :: ByteString -> PGValues -> PGPreparedQuery PGValues Source #

Make a prepared query directly from a query string and bind parameters, with no type inference

data QueryFlags Source #

Flags affecting how and what type of query to build with makePGQuery.

Constructors

QueryFlags 

Fields

simpleQueryFlags :: QueryFlags Source #

QueryFlags for a default (simple) query.

parseQueryFlags :: String -> (QueryFlags, String) Source #

Parse flags off the beginning of a query string, returning the flags and the remaining string.

makePGQuery :: QueryFlags -> String -> ExpQ Source #

Construct a PGQuery from a SQL string. This is the underlying template function for pgSQL which you can use in largely the same way when you want to construct query strings from other variables. For example:

selectQuery = "SELECT * FROM"
selectFoo = $(makePGQuery simpleQueryFlags (selectQuery ++ " foo"))

The only caveat is that variables or functions like selectQuery need to be defined in a different module (due to TH stage restrictions).

pgSQL :: QuasiQuoter Source #

A quasi-quoter for PGSQL queries.

Used in expression context, it may contain any SQL statement [pgSQL|SELECT ...|]. The statement may contain PostgreSQL-style placeholders ($1, $2, ...) or in-line placeholders (${1+1}) containing any valid Haskell expression (except {}). It will be replaced by a PGQuery object that can be used to perform the SQL statement. If there are more $N placeholders than expressions, it will instead be a function accepting the additional parameters and returning a PGQuery.

Ideally, this mimics postgres' SQL parsing, so that placeholders and expressions will only be expanded when they are in valid positions (i.e., not inside quoted strings). Since ${ is not valid SQL otherwise, there should be no need to escape it.

The statement may start with one of more special flags affecting the interpretation:

?
To disable nullability inference, treating all result values as nullable, thus returning Maybe values regardless of inferred nullability. This makes unexpected NULL errors impossible.
!
To disable nullability inference, treating all result values as not nullable, thus only returning Maybe where requested. This is makes unexpected NULL errors more likely.
$
To create a PGPreparedQuery (using placeholder parameters) rather than the default PGSimpleQuery (using literal substitution).
$(type,...)
To specify specific types for a prepared query (see http://www.postgresql.org/docs/current/static/sql-prepare.html for details), rather than inferring parameter types by default.
#
Only do literal ${} substitution using pgSubstituteLiterals and return a string, not a query.

pgSQL can also be used at the top-level to execute SQL statements at compile-time (without any parameters and ignoring results). Here the query can only be prefixed with ! to make errors non-fatal.

If you want to construct queries out of string variables rather than quasi-quoted strings, you can use the lower-level makePGQuery instead.

pgExecute :: PGQuery q () => PGConnection -> q -> IO Int Source #

Execute a query that does not return results. Return the number of rows affected (or -1 if not known).

pgQuery :: PGQuery q a => PGConnection -> q -> IO [a] Source #

Run a query and return a list of row results.

pgLazyQuery Source #

Arguments

:: PGConnection 
-> PGPreparedQuery a 
-> Word32

Chunk size (1 is common, 0 is all-or-nothing)

-> IO [a] 

Run a prepared query in lazy mode, where only chunk size rows are requested at a time. If you eventually retrieve all the rows this way, it will be far less efficient than using pgQuery, since every chunk requires an additional round-trip. Although you may safely stop consuming rows early, currently you may not interleave any other database operation while reading rows. (This limitation could theoretically be lifted if required.)