| Copyright | Flipstone Technology Partners 2023 |
|---|---|
| License | MIT |
| Stability | Stable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Orville.PostgreSQL.Raw.RawSql
Description
The functions in this module are named with the intent that it is imported
qualified as RawSql.
Since: 1.0.0.0
Synopsis
- data RawSql
- parameter :: SqlValue -> RawSql
- fromString :: String -> RawSql
- fromText :: Text -> RawSql
- fromBytes :: ByteString -> RawSql
- intercalate :: (SqlExpression sql, Foldable f) => RawSql -> f sql -> RawSql
- execute :: SqlExpression sql => Connection -> sql -> IO Result
- executeVoid :: SqlExpression sql => Connection -> sql -> IO ()
- connectionQuoting :: Connection -> Quoting IO
- space :: RawSql
- comma :: RawSql
- commaSpace :: RawSql
- leftParen :: RawSql
- rightParen :: RawSql
- dot :: RawSql
- doubleQuote :: RawSql
- doubleColon :: RawSql
- stringLiteral :: ByteString -> RawSql
- identifier :: ByteString -> RawSql
- parenthesized :: SqlExpression sql => sql -> RawSql
- intDecLiteral :: Int -> RawSql
- int8DecLiteral :: Int8 -> RawSql
- int16DecLiteral :: Int16 -> RawSql
- int32DecLiteral :: Int32 -> RawSql
- int64DecLiteral :: Int64 -> RawSql
- class SqlExpression a where
- toRawSql :: a -> RawSql
- unsafeFromRawSql :: RawSql -> a
- unsafeSqlExpression :: SqlExpression a => String -> a
- toBytesAndParams :: (SqlExpression sql, Monad m) => Quoting m -> sql -> m (ByteString, [Maybe PgTextFormatValue])
- toExampleBytes :: SqlExpression sql => sql -> ByteString
- data Quoting m = Quoting {
- quoteStringLiteral :: ByteString -> m Builder
- quoteIdentifier :: ByteString -> m Builder
- exampleQuoting :: Quoting Identity
Documentation
RawSql provides a type for efficiently constructing raw SQL statements from
smaller parts and then executing them. It also supports using placeholder
values to pass parameters with a query without having to interpolate them as
part of the actual SQL state and being exposed to SQL injection.
Since: 1.0.0.0
parameter :: SqlValue -> RawSql Source #
Includes an input parameter in the RawSql statement that will be passed
using placeholders (e.g. '$1') rather than being included directly in the SQL
statement. This is the correct way to include input from untrusted sources as
part of a RawSql query. The parameter must be formatted in a textual
representation, which the database will interpret. The database type for the
value will be inferred by the database based on its usage in the query.
Since: 1.0.0.0
fromString :: String -> RawSql Source #
fromBytes :: ByteString -> RawSql Source #
Constructs a RawSql from a ByteString value, which is assumed to be
encoded sensibly for the database to handle.
Note that because the string is treated as raw SQL, it is completely up to the caller to protected againt SQL-injection attacks when using this function. Never use this function with input read from an untrusted source.
Since: 1.0.0.0
intercalate :: (SqlExpression sql, Foldable f) => RawSql -> f sql -> RawSql Source #
execute :: SqlExpression sql => Connection -> sql -> IO Result Source #
Executes a RawSql value using the executeRaw function. Make sure
to read the documentation of executeRaw for caveats and warnings.
Use with caution.
Note that because this is done in IO, no callback functions are available
to be called.
Since: 1.0.0.0
executeVoid :: SqlExpression sql => Connection -> sql -> IO () Source #
Executes a RawSql value using the executeRawVoid function. Make sure
to read the documentation of executeRawVoid for caveats and warnings.
Use with caution.
Note that because this is done in IO, no callback functions are available
to be called.
Since: 1.0.0.0
connectionQuoting :: Connection -> Quoting IO Source #
Quoting done in IO using the quoting functions provided by the connection, which can apply quoting based on the specific connection properties.
If you don't have a connection available and are only planning on using the
SQL for explanatory or example purposes, see exampleQuoting.
Since: 1.0.0.0
Fragments provided for convenience
commaSpace :: RawSql Source #
Comma space separator, provided for convenience.
rightParen :: RawSql Source #
Just a plain old right paren, provided for convenience.
doubleQuote :: RawSql Source #
Just a plain double quote, provided for convenience.
doubleColon :: RawSql Source #
Just two colons, provided for convenience.
stringLiteral :: ByteString -> RawSql Source #
Includes a bytestring value as a string literal in the SQL statement. The string literal will be quoted and escaped for you; the value provided should not include surrounding quotes or quote special characters.
Note: It's better to use the parameter function where possible to pass
values to be used as input to a SQL statement. There are some situations
where PostgreSQL does not allow this, however (for instance, in some DDL
statements). This function is provided for those situations.
Since: 1.0.0.0
identifier :: ByteString -> RawSql Source #
Includes a bytestring value as an identifier in the SQL statement. The identifier will be quoted and escaped for you; the value provided should not include surrounding quotes or quote special characters.
Since: 1.0.0.0
parenthesized :: SqlExpression sql => sql -> RawSql Source #
Integer values as literals
intDecLiteral :: Int -> RawSql Source #
int8DecLiteral :: Int8 -> RawSql Source #
int16DecLiteral :: Int16 -> RawSql Source #
int32DecLiteral :: Int32 -> RawSql Source #
int64DecLiteral :: Int64 -> RawSql Source #
Generic interface for generating SQL
class SqlExpression a where Source #
SqlExpression provides a common interface for converting types to and from
RawSql, either via toRawSql and unsafeFromRawSql, or the convenience
function unsafeSqlExpression. Orville defines a large number of types that
represent various fragments of SQL statements as well as functions to help
construct them safely. These functions can be found in
Expr. These types all provide SqlExpression instances
as an escape hatch to allow you to pass any SQL you wish in place of what
Orville directly supports. This should be used with great care as Orville
cannot guarantee that the SQL you pass can be used to generate valid SQL in
conjunction with the rest of the Expr API.
Since: 1.0.0.0
Instances
unsafeSqlExpression :: SqlExpression a => String -> a Source #
A convenience function for creating an arbitrary SqlExpression from a
String. Great care should be exercised when using this function as it cannot
provide any sort of guarantee that the string passed is usable to generate
valid SQL via the rest of Orville's Expr API.
For example, if one wanted build a boolean expression not supported by Orville, you can do it like so:
import qualified Orville.PostgreSQL.Expr as Expr a :: Expr.BooleanExpr a RawSql.unsafeSqlExpression "foo BETWEEN 1 AND 3"
Since: 1.0.0.0
toBytesAndParams :: (SqlExpression sql, Monad m) => Quoting m -> sql -> m (ByteString, [Maybe PgTextFormatValue]) Source #
Constructs the actual SQL bytestring and parameter values that will be passed
to the database to execute a RawSql query. Any string literals that are
included in the SQL expression will be quoted using the given quoting
directive.
Since: 1.0.0.0
toExampleBytes :: SqlExpression sql => sql -> ByteString Source #
Builds the bytes that represent the raw SQL. These bytes may not be executable on their own, because they may contain placeholders that must be filled in, but can be useful for inspecting SQL queries.
Since: 1.0.0.0
Provides procedures for quoting parts of a raw SQL query so that they can be
safely executed. Quoting may be done in some Monad m, allowing for the use
of quoting operations provided by Connection, which operates in the
IO monad.
See connectionQuoting and exampleQuoting.
Since: 1.0.0.0
Constructors
| Quoting | |
Fields
| |
exampleQuoting :: Quoting Identity Source #
Quoting done in pure Haskell that is suitable for showing SQL examples,
but is not guaranteed to be sufficient for all database connections. For
quoting that is based on the actual connection to the database, see
connectionQuoting.
Since: 1.0.0.0