Modulepersistent-2.18.1.0Haskell2010

Database.Persist.SqlBackend

This module contains types and information necessary for a SQL database. Database support libraries, like persistent-postgresql, will be responsible for constructing these values.

Contents

The type and construction
Utilities
SqlBackend Getters
SqlBackend Setters
SqlBackendHooks

Synopsis

data SqlBackend
value mkSqlBackend
data MkSqlBackendArgs
newtype SqlBackendHooks
value emptySqlBackendHooks
value getRDBMS
value getEscapedFieldName
value getEscapedRawName
value getEscapeRawNameFunction
value getConnLimitOffset
value getConnUpsertSql
value getConnVault
value getConnHooks
value setConnMaxParams
value setConnRepsertManySql
value setConnInsertManySql
value setConnUpsertSql
value setConnPutManySql
value setConnVault
value modifyConnVault
value setConnHooks

Packagepersistent-2.18.1.0
Exports21
LanguageHaskell2010
LicenceMIT
SourceSqlBackend.hs

The type and construction

datadata SqlBackend

Source#

A SqlBackend represents a handle or connection to a database. It contains functions and values that allow databases to have more optimized implementations, as well as references that benefit performance and sharing.

Instead of using the SqlBackend constructor directly, use the mkSqlBackend function.

A SqlBackend is *not* thread-safe. You should not assume that a SqlBackend can be shared among threads and run concurrent queries. This *will* result in problems. Instead, you should create a Pool SqlBackend, known as a ConnectionPool, and pass that around in multi-threaded applications.

To run actions in the persistent library, you should use the runSqlConn function. If you're using a multithreaded application, use the runSqlPool function.

Instances32PersistQueryRead, PersistQueryWrite, HasPersistBackend, IsPersistBackend, PersistCore, PersistStoreRead, …

PersistQueryRead SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistQuery · orphan
PersistQueryWrite SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistQuery · orphan
HasPersistBackend SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.SqlBackend.Internal
IsPersistBackend SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.SqlBackend.Internal
PersistCore SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
PersistStoreRead SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
PersistStoreWrite SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
PersistUniqueRead SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistUnique · orphan
PersistUniqueWrite SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistUnique · orphan
BackendCompatible SqlBackend SqlReadBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
BackendCompatible SqlBackend SqlWriteBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
BackendCompatible SqlBackend SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Bounded (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Enum (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Eq (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Integral (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Num (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Ord (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Read (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Real (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Show (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
Generic (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
FromJSON (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
ToJSON (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
FromHttpApiData (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
ToHttpApiData (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
PathPiece (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
PersistField (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
PersistFieldSql (BackendKey SqlBackend)Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
type Rep (BackendKey SqlBackend) = D1 ('MetaData "BackendKey" "Database.Persist.Sql.Orphan.PersistStore" "persistent-2.18.1.0-3nfqmEoifEQWKRFhPRuTO" 'True) (C1 ('MetaCons "SqlBackendKey" 'PrefixI 'True) (S1 ('MetaSel ('Just "unSqlBackendKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int64)))Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
data BackendKey SqlBackend
- SqlBackendKeyunSqlBackendKey :: Int64
Defined in persistent-2.18.1.0 · Database.Persist.Sql.Orphan.PersistStore · orphan
type BaseBackend SqlBackend = SqlBackendDefined in persistent-2.18.1.0 · Database.Persist.SqlBackend.Internal

valuemkSqlBackend :: MkSqlBackendArgs -> SqlBackend

Source#

A function for creating a value of the SqlBackend type. You should prefer to use this instead of the constructor for SqlBackend, because default values for this will be provided for new fields on the record when new functionality is added.

datadata MkSqlBackendArgs

Source#

This type shares many of the same field names as the SqlBackend type. It's useful for library authors to use this when migrating from using the SqlBackend constructor directly to the mkSqlBackend function.

This type will only contain required fields for constructing a SqlBackend. For fields that aren't present on this record, you'll want to use the various set functions or

Constructors

MkSqlBackendArgs
- connPrepare :: Text -> IO Statement
  This function should prepare a Statement in the target database, which should allow for efficient query reuse.
- connInsertSql :: EntityDef -> [PersistValue] -> InsertSqlResult
  This function generates the SQL and values necessary for performing an insert against the database.
- connStmtMap :: IORef (Map Text Statement)
  A reference to the cache of statements. Statements are keyed by the Text queries that generated them.
- connClose :: IO ()
  Close the underlying connection.
- connMigrateSql :: [EntityDef] -> (Text -> IO Statement) -> EntityDef -> IO (Either [Text] [(Bool, Text)])
  This function returns the migrations required to include the EntityDef parameter in the [EntityDef] database. This might include creating a new table if the entity is not present, or altering an existing table if it is.
- connBegin :: (Text -> IO Statement) -> Maybe IsolationLevel -> IO ()
  A function to begin a transaction for the underlying database.
- connCommit :: (Text -> IO Statement) -> IO ()
  A function to commit a transaction to the underlying database.
- connRollback :: (Text -> IO Statement) -> IO ()
  A function to roll back a transaction on the underlying database.
- connEscapeFieldName :: FieldNameDB -> Text
  A function to extract and escape the name of the column corresponding to the provided field.
- connEscapeTableName :: EntityDef -> Text
  A function to extract and escape the name of the table corresponding to the provided entity. PostgreSQL uses this to support schemas.
- connEscapeRawName :: Text -> Text
  A function to escape raw DB identifiers. MySQL uses backticks, while PostgreSQL uses quotes, and so on.
- connNoLimit :: Text
- connRDBMS :: Text
  A tag displaying what database the SqlBackend is for. Can be used to differentiate features in downstream libraries for different database backends.
- connLimitOffset :: (Int, Int) -> Text -> Text
  Attach a 'LIMIT/OFFSET' clause to a SQL query. Note that LIMIT/OFFSET is problematic for performance, and indexed range queries are the superior way to offer pagination.
- connLogFunc :: LogFunc
  A log function for the SqlBackend to use.

newtypenewtype SqlBackendHooks

valueemptySqlBackendHooks :: SqlBackendHooks

Utilities

The functions exported here are a bit more general than the record accessors. The easiest way to use them is to provide the SqlBackend directly to the function. However, you can also use them in a ReaderT context, and you can even use them with any backend type tht has a BackendCompatible SqlBackend backend instance.

SqlBackend Getters

valuegetRDBMS :: (BackendCompatible SqlBackend backend, MonadReader backend m) => m Text

Source#

Get a tag displaying what database the SqlBackend is for. Can be used to differentiate features in downstream libraries for different database backends. @since 2.13.3.0

valuegetEscapedFieldName

:: (BackendCompatible SqlBackend backend, MonadReader backend m)
=> FieldNameDB
-> m Text

Source#

This function can be used directly with a SqlBackend to escape a FieldNameDB.

let conn :: SqlBackend
getEscapedFieldName (FieldNameDB "asdf") conn

Alternatively, you can use it in a ReaderT SqlBackend context, like SqlPersistT:

query :: SqlPersistM Text
query = do
    field <- getEscapedFieldName (FieldNameDB "asdf")
    pure field

valuegetEscapedRawName

:: (BackendCompatible SqlBackend backend, MonadReader backend m)
=> Text
-> m Text

Source#

This function can be used directly with a SqlBackend to escape a raw Text.

let conn :: SqlBackend
getEscapedRawName (FieldNameDB "asdf") conn

Alternatively, you can use it in a ReaderT SqlBackend context, like SqlPersistT:

query :: SqlPersistM Text
query = do
    field <- getEscapedRawName (FieldNameDB "asdf")
    pure field

valuegetEscapeRawNameFunction :: (BackendCompatible SqlBackend backend, MonadReader backend m) => m (Text -> Text)

Source#

Return the function for escaping a raw name.

valuegetConnLimitOffset

:: (BackendCompatible SqlBackend backend, MonadReader backend m)
=> (Int, Int)
The (LIMIT, OFFSET) to put on the query.
-> Text
The SQL query that the LIMIT/OFFSET clause will be attached to.
-> m Text

Source#

Decorate the given SQL query with the (LIMIT, OFFSET) specified.

value

getConnUpsertSql :: (BackendCompatible SqlBackend backend, MonadReader backend m) => m (Maybe (EntityDef -> NonEmpty (FieldNameHS, FieldNameDB) -> Text -> Text))

Source#

Retrieve the function for generating an upsert statement, if the backend supports it.

valuegetConnVault :: (BackendCompatible SqlBackend backend, MonadReader backend m) => m Vault

Source#

Retrieve the vault from the provided database backend.

valuegetConnHooks :: (BackendCompatible SqlBackend backend, MonadReader backend m) => m SqlBackendHooks

Source#

Retrieve instrumentation hooks from the provided database backend.

SqlBackend Setters

valuesetConnMaxParams :: Int -> SqlBackend -> SqlBackend

Source#

Set the maximum parameters that may be issued in a given SQL query. This should be used only if the database backend have this limitation.

valuesetConnRepsertManySql

:: EntityDef -> Int -> Text
-> SqlBackend
-> SqlBackend

Source#

Set the connRepsertManySql field on the SqlBackend. This should only be set by the database backend library. If this is not set, a slow default will be used.

valuesetConnInsertManySql

:: EntityDef -> [[PersistValue]] -> InsertSqlResult
-> SqlBackend
-> SqlBackend

Source#

Set the connInsertManySql field on the SqlBackend. This should only be used by the database backend library to provide an efficient implementation of a bulk insert function. If this is not set, a slow default will be used.

valuesetConnUpsertSql

:: EntityDef -> NonEmpty (FieldNameHS, FieldNameDB) -> Text -> Text
-> SqlBackend
-> SqlBackend

Source#

Set the connUpsertSql field on the SqlBackend. This should only be used by the database backend library to provide an efficient implementation of a bulk insert function. If this is not set, a slow default will be used.

valuesetConnPutManySql :: (EntityDef -> Int -> Text) -> SqlBackend -> SqlBackend

Source#

Set the 'connPutManySql field on the SqlBackend. This should only be used by the database backend library to provide an efficient implementation of a bulk insert function. If this is not set, a slow default will be used.

valuesetConnVault :: Vault -> SqlBackend -> SqlBackend

Source#

Set the vault on the provided database backend.

valuemodifyConnVault :: (Vault -> Vault) -> SqlBackend -> SqlBackend

Source#

Modify the vault on the provided database backend.

valuesetConnHooks :: SqlBackendHooks -> SqlBackend -> SqlBackend

Source#

Set hooks on the provided database backend.