-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Backend for the persistent library using postgresql.
--   
--   Based on the postgresql-simple package
@package persistent-postgresql
@version 2.12.1.0


-- | A postgresql backend for persistent.
module Database.Persist.Postgresql

-- | Create a PostgreSQL connection pool and run the given action. The pool
--   is properly released after the action finishes using it. Note that you
--   should not use the given <a>ConnectionPool</a> outside the action
--   since it may already have been released. The provided action should
--   use <a>runSqlConn</a> and *not* <a>runReaderT</a> because the former
--   brackets the database action with transaction begin/commit.
withPostgresqlPool :: (MonadLoggerIO m, MonadUnliftIO m) => ConnectionString -> Int -> (Pool SqlBackend -> m a) -> m a

-- | Same as <tt>withPostgresPool</tt>, but takes a callback for obtaining
--   the server version (to work around an Amazon Redshift bug).
withPostgresqlPoolWithVersion :: (MonadUnliftIO m, MonadLoggerIO m) => (Connection -> IO (Maybe Double)) -> ConnectionString -> Int -> (Pool SqlBackend -> m a) -> m a

-- | Same as <a>withPostgresqlPool</a>, but instead of opening a pool of
--   connections, only one connection is opened. The provided action should
--   use <a>runSqlConn</a> and *not* <a>runReaderT</a> because the former
--   brackets the database action with transaction begin/commit.
withPostgresqlConn :: (MonadUnliftIO m, MonadLoggerIO m) => ConnectionString -> (SqlBackend -> m a) -> m a

-- | Same as <a>withPostgresqlConn</a>, but takes a callback for obtaining
--   the server version (to work around an Amazon Redshift bug).
withPostgresqlConnWithVersion :: (MonadUnliftIO m, MonadLoggerIO m) => (Connection -> IO (Maybe Double)) -> ConnectionString -> (SqlBackend -> m a) -> m a

-- | Same as <a>withPostgresqlPool</a>, but can be configured with
--   <a>PostgresConf</a> and <a>PostgresConfHooks</a>.
withPostgresqlPoolWithConf :: (MonadUnliftIO m, MonadLoggerIO m) => PostgresConf -> PostgresConfHooks -> (Pool SqlBackend -> m a) -> m a

-- | Create a PostgreSQL connection pool. Note that it's your
--   responsibility to properly close the connection pool when unneeded.
--   Use <a>withPostgresqlPool</a> for an automatic resource control.
createPostgresqlPool :: (MonadUnliftIO m, MonadLoggerIO m) => ConnectionString -> Int -> m (Pool SqlBackend)

-- | Same as <a>createPostgresqlPool</a>, but additionally takes a callback
--   function for some connection-specific tweaking to be performed after
--   connection creation. This could be used, for example, to change the
--   schema. For more information, see:
--   
--   
--   <a>https://groups.google.com/d/msg/yesodweb/qUXrEN_swEo/O0pFwqwQIdcJ</a>
createPostgresqlPoolModified :: (MonadUnliftIO m, MonadLoggerIO m) => (Connection -> IO ()) -> ConnectionString -> Int -> m (Pool SqlBackend)

-- | Same as other similarly-named functions in this module, but takes
--   callbacks for obtaining the server version (to work around an Amazon
--   Redshift bug) and connection-specific tweaking (to change the schema).
createPostgresqlPoolModifiedWithVersion :: (MonadUnliftIO m, MonadLoggerIO m) => (Connection -> IO (Maybe Double)) -> (Connection -> IO ()) -> ConnectionString -> Int -> m (Pool SqlBackend)

-- | Same as <a>createPostgresqlPool</a>, but can be configured with
--   <a>PostgresConf</a> and <a>PostgresConfHooks</a>.
createPostgresqlPoolWithConf :: (MonadUnliftIO m, MonadLoggerIO m) => PostgresConf -> PostgresConfHooks -> m (Pool SqlBackend)

-- | A <tt>libpq</tt> connection string. A simple example of connection
--   string would be <tt>"host=localhost port=5432 user=test dbname=test
--   password=test"</tt>. Please read libpq's documentation at
--   <a>https://www.postgresql.org/docs/current/static/libpq-connect.html</a>
--   for more details on how to create such strings.
type ConnectionString = ByteString

-- | This type is used to determine how to update rows using Postgres'
--   <tt>INSERT ... ON CONFLICT KEY UPDATE</tt> functionality, exposed via
--   <a>upsertWhere</a> and <a>upsertManyWhere</a> in this library.
data HandleUpdateCollision record

-- | Copy the field directly from the record.
copyField :: PersistField typ => EntityField record typ -> HandleUpdateCollision record

-- | Copy the field into the database only if the value in the
--   corresponding record is non-<tt>NULL</tt>.
--   
--   @since 2.12.1.0
copyUnlessNull :: PersistField typ => EntityField record (Maybe typ) -> HandleUpdateCollision record

-- | Copy the field into the database only if the value in the
--   corresponding record is non-empty, where "empty" means the Monoid
--   definition for <a>mempty</a>. Useful for <a>Text</a>, <a>String</a>,
--   <a>ByteString</a>, etc.
--   
--   The resulting <a>HandleUpdateCollision</a> type is useful for the
--   <a>upsertManyWhere</a> function.
--   
--   @since 2.12.1.0
copyUnlessEmpty :: (Monoid typ, PersistField typ) => EntityField record typ -> HandleUpdateCollision record

-- | Copy the field into the database only if the field is not equal to the
--   provided value. This is useful to avoid copying weird nullary data
--   into the database.
--   
--   The resulting <a>HandleUpdateCollision</a> type is useful for the
--   <tt>upsertMany</tt> function.
--   
--   @since 2.12.1.0
copyUnlessEq :: PersistField typ => EntityField record typ -> typ -> HandleUpdateCollision record

-- | Exclude any record field if it doesn't match the filter record. Used
--   only in <a>upsertWhere</a> and <a>upsertManyWhere</a>
--   
--   TODO: we could probably make a sum type for the <a>Filter</a> record
--   that's passed into the <tt>upserWhere</tt> and <a>upsertManyWhere</a>
--   methods that has similar behavior to the HandleCollisionUpdate type.
excludeNotEqualToOriginal :: (PersistField typ, PersistEntity rec) => EntityField rec typ -> Filter rec

-- | Information required to connect to a PostgreSQL database using
--   <tt>persistent</tt>'s generic facilities. These values are the same
--   that are given to <a>withPostgresqlPool</a>.
data PostgresConf
PostgresConf :: ConnectionString -> Int -> Integer -> Int -> PostgresConf

-- | The connection string.
[pgConnStr] :: PostgresConf -> ConnectionString

-- | How many stripes to divide the pool into. See <a>Data.Pool</a> for
--   details. @since 2.11.0.0
[pgPoolStripes] :: PostgresConf -> Int

-- | How long connections can remain idle before being disposed of, in
--   seconds. @since 2.11.0.0
[pgPoolIdleTimeout] :: PostgresConf -> Integer

-- | How many connections should be held in the connection pool.
[pgPoolSize] :: PostgresConf -> Int

-- | Represent Postgres interval using NominalDiffTime
newtype PgInterval
PgInterval :: NominalDiffTime -> PgInterval
[getPgInterval] :: PgInterval -> NominalDiffTime

-- | Postgres specific <a>upsertWhere</a>. This method does the following:
--   It will insert a record if no matching unique key exists. If a unique
--   key exists, it will update the relevant field with a user-supplied
--   value, however, it will only do this update on a user-supplied
--   condition. For example, here's how this method could be called like
--   such:
--   
--   <pre>
--   upsertWhere record [recordField =. newValue] [recordField /= newValue]
--   </pre>
--   
--   Called thusly, this method will insert a new record (if none exists)
--   OR update a recordField with a new value assuming the condition in the
--   last block is met.
upsertWhere :: (backend ~ PersistEntityBackend record, PersistEntity record, PersistEntityBackend record ~ SqlBackend, MonadIO m, PersistStore backend, BackendCompatible SqlBackend backend) => record -> [Update record] -> [Filter record] -> ReaderT backend m ()

-- | Postgres specific <a>upsertManyWhere</a>. This method does the
--   following: It will insert a record if no matching unique key exists.
--   If a unique key exists, it will update the relevant field with a
--   user-supplied value, however, it will only do this update on a
--   user-supplied condition. For example, here's how this method could be
--   called like such:
--   
--   upsertManyWhere [record] [recordField =. newValue] [recordField /=
--   newValue]
--   
--   Called thusly, this method will insert a new record (if none exists)
--   OR update a recordField with a new value assuming the condition in the
--   last block is met.
--   
--   <ul>
--   <li>- @since 2.12.1.0</li>
--   </ul>
upsertManyWhere :: forall record backend m. (backend ~ PersistEntityBackend record, BackendCompatible SqlBackend backend, PersistEntityBackend record ~ SqlBackend, PersistEntity record, MonadIO m) => [record] -> [HandleUpdateCollision record] -> [Update record] -> [Filter record] -> ReaderT backend m ()

-- | Generate a <a>SqlBackend</a> from a <a>Connection</a>.
openSimpleConn :: LogFunc -> Connection -> IO SqlBackend

-- | Generate a <a>SqlBackend</a> from a <a>Connection</a>, but takes a
--   callback for obtaining the server version.
openSimpleConnWithVersion :: (Connection -> IO (Maybe Double)) -> LogFunc -> Connection -> IO SqlBackend

-- | Get the SQL string for the table that a PeristEntity represents.
--   Useful for raw SQL queries.
tableName :: PersistEntity record => record -> Text

-- | Get the SQL string for the field that an EntityField represents.
--   Useful for raw SQL queries.
fieldName :: PersistEntity record => EntityField record typ -> Text

-- | Mock a migration even when the database is not present. This function
--   performs the same functionality of <a>printMigration</a> with the
--   difference that an actual database is not needed.
mockMigration :: Migration -> IO ()

-- | Enable a Postgres extension. See
--   <a>https://www.postgresql.org/docs/current/static/contrib.html</a> for
--   a list.
migrateEnableExtension :: Text -> Migration

-- | Hooks for configuring the Persistent/its connection to Postgres
data PostgresConfHooks
PostgresConfHooks :: (Connection -> IO (NonEmpty Word)) -> (Connection -> IO ()) -> PostgresConfHooks

-- | Function to get the version of Postgres
--   
--   The default implementation queries the server with "show
--   server_version". Some variants of Postgres, such as Redshift, don't
--   support showing the version. It's recommended you return a hardcoded
--   version in those cases.
[pgConfHooksGetServerVersion] :: PostgresConfHooks -> Connection -> IO (NonEmpty Word)

-- | Action to perform after a connection is created.
--   
--   Typical uses of this are modifying the connection (e.g. to set the
--   schema) or logging a connection being created.
--   
--   The default implementation does nothing.
[pgConfHooksAfterCreate] :: PostgresConfHooks -> Connection -> IO ()

-- | Default settings for <a>PostgresConfHooks</a>. See the individual
--   fields of <a>PostgresConfHooks</a> for the default values.
defaultPostgresConfHooks :: PostgresConfHooks
instance GHC.Show.Show Database.Persist.Postgresql.PgInterval
instance GHC.Classes.Eq Database.Persist.Postgresql.PgInterval
instance GHC.Classes.Ord Database.Persist.Postgresql.Unknown
instance GHC.Read.Read Database.Persist.Postgresql.Unknown
instance GHC.Show.Show Database.Persist.Postgresql.Unknown
instance GHC.Classes.Eq Database.Persist.Postgresql.Unknown
instance GHC.Classes.Ord Database.Persist.Postgresql.UnknownLiteral
instance GHC.Read.Read Database.Persist.Postgresql.UnknownLiteral
instance GHC.Show.Show Database.Persist.Postgresql.UnknownLiteral
instance GHC.Classes.Eq Database.Persist.Postgresql.UnknownLiteral
instance GHC.Show.Show Database.Persist.Postgresql.AlterColumn
instance GHC.Show.Show Database.Persist.Postgresql.AlterTable
instance GHC.Show.Show Database.Persist.Postgresql.AlterDB
instance Data.Data.Data Database.Persist.Postgresql.PostgresConf
instance GHC.Read.Read Database.Persist.Postgresql.PostgresConf
instance GHC.Show.Show Database.Persist.Postgresql.PostgresConf
instance Data.Aeson.Types.FromJSON.FromJSON Database.Persist.Postgresql.PostgresConf
instance Database.Persist.Class.PersistConfig.PersistConfig Database.Persist.Postgresql.PostgresConf
instance Database.PostgreSQL.Simple.ToField.ToField Database.Persist.Postgresql.P
instance Database.PostgreSQL.Simple.FromField.FromField Database.Persist.Postgresql.UnknownLiteral
instance Database.PostgreSQL.Simple.ToField.ToField Database.Persist.Postgresql.UnknownLiteral
instance Database.PostgreSQL.Simple.FromField.FromField Database.Persist.Postgresql.Unknown
instance Database.PostgreSQL.Simple.ToField.ToField Database.Persist.Postgresql.Unknown
instance Database.PostgreSQL.Simple.ToField.ToField Database.Persist.Postgresql.PgInterval
instance Database.PostgreSQL.Simple.FromField.FromField Database.Persist.Postgresql.PgInterval
instance Database.Persist.Class.PersistField.PersistField Database.Persist.Postgresql.PgInterval
instance Database.Persist.Sql.Class.PersistFieldSql Database.Persist.Postgresql.PgInterval
instance GHC.Show.Show Database.Persist.Postgresql.PostgresServerVersionError
instance GHC.Exception.Type.Exception Database.Persist.Postgresql.PostgresServerVersionError


-- | Filter operators for JSON values added to PostgreSQL 9.4
module Database.Persist.Postgresql.JSON

-- | This operator checks inclusion of the JSON value on the right hand
--   side in the JSON value on the left hand side.
--   
--   <h3><b>Objects</b></h3>
--   
--   An empty Object matches any object
--   
--   <pre>
--   {}                @&gt; {} == True
--   {"a":1,"b":false} @&gt; {} == True
--   </pre>
--   
--   Any key-value will be matched top-level
--   
--   <pre>
--   {"a":1,"b":{"c":true"}} @&gt; {"a":1}         == True
--   {"a":1,"b":{"c":true"}} @&gt; {"b":1}         == False
--   {"a":1,"b":{"c":true"}} @&gt; {"b":{}}        == True
--   {"a":1,"b":{"c":true"}} @&gt; {"c":true}      == False
--   {"a":1,"b":{"c":true"}} @&gt; {"b":{c":true}} == True
--   </pre>
--   
--   <h3><b>Arrays</b></h3>
--   
--   An empty Array matches any array
--   
--   <pre>
--   []                    @&gt; [] == True
--   [1,2,"hi",false,null] @&gt; [] == True
--   </pre>
--   
--   Any array has to be a sub-set. Any object or array will also be
--   compared as being a subset of.
--   
--   <pre>
--   [1,2,"hi",false,null] @&gt; [1]                       == True
--   [1,2,"hi",false,null] @&gt; [null,"hi"]               == True
--   [1,2,"hi",false,null] @&gt; ["hi",true]               == False
--   [1,2,"hi",false,null] @&gt; ["hi",2,null,false,1]     == True
--   [1,2,"hi",false,null] @&gt; [1,2,"hi",false,null,{}]  == False
--   </pre>
--   
--   Arrays and objects inside arrays match the same way they'd be matched
--   as being on their own.
--   
--   <pre>
--   [1,"hi",[false,3],{"a":[null]}] @&gt; [{}]            == True
--   [1,"hi",[false,3],{"a":[null]}] @&gt; [{"a":[]}]      == True
--   [1,"hi",[false,3],{"a":[null]}] @&gt; [{"b":[null]}]  == False
--   [1,"hi",[false,3],{"a":[null]}] @&gt; [[]]            == True
--   [1,"hi",[false,3],{"a":[null]}] @&gt; [[3]]           == True
--   [1,"hi",[false,3],{"a":[null]}] @&gt; [[true,3]]      == False
--   </pre>
--   
--   A regular value has to be a member
--   
--   <pre>
--   [1,2,"hi",false,null] @&gt; 1      == True
--   [1,2,"hi",false,null] @&gt; 5      == False
--   [1,2,"hi",false,null] @&gt; "hi"   == True
--   [1,2,"hi",false,null] @&gt; false  == True
--   [1,2,"hi",false,null] @&gt; "2"    == False
--   </pre>
--   
--   An object will never match with an array
--   
--   <pre>
--   [1,2,"hi",[false,3],{"a":null}] @&gt; {}          == False
--   [1,2,"hi",[false,3],{"a":null}] @&gt; {"a":null}  == False
--   </pre>
--   
--   <h3><b>Other values</b></h3>
--   
--   For any other JSON values the <tt>(\@&gt;.)</tt> operator functions
--   like an equivalence operator.
--   
--   <pre>
--   "hello" @&gt; "hello"     == True
--   "hello" @&gt; "Hello"     == False
--   "hello" @&gt; "h"         == False
--   "hello" @&gt; {"hello":1} == False
--   "hello" @&gt; ["hello"]   == False
--   
--   5       @&gt; 5       == True
--   5       @&gt; 5.00    == True
--   5       @&gt; 1       == False
--   5       @&gt; 7       == False
--   12345   @&gt; 1234    == False
--   12345   @&gt; 2345    == False
--   12345   @&gt; "12345" == False
--   12345   @&gt; [1,2,3,4,5] == False
--   
--   true    @&gt; true    == True
--   true    @&gt; false   == False
--   false   @&gt; true    == False
--   true    @&gt; "true"  == False
--   
--   null    @&gt; null    == True
--   null    @&gt; 23      == False
--   null    @&gt; "null"  == False
--   null    @&gt; {}      == False
--   </pre>
(@>.) :: EntityField record Value -> Value -> Filter record
infix 4 @>.

-- | Same as <a>@&gt;.</a> except the inclusion check is reversed. i.e. is
--   the JSON value on the left hand side included in the JSON value of the
--   right hand side.
(<@.) :: EntityField record Value -> Value -> Filter record
infix 4 <@.

-- | This operator takes a column and a string to find a top-level
--   key/field in an object.
--   
--   <pre>
--   column ?. string
--   </pre>
--   
--   N.B. This operator might have some unexpected interactions with
--   non-object values. Please reference the examples.
--   
--   <h3><b>Objects</b></h3>
--   
--   <pre>
--   {"a":null}             ? "a"  == True
--   {"test":false,"a":500} ? "a"  == True
--   {"b":{"a":[]}}         ? "a"  == False
--   {}                     ? "a"  == False
--   {}                     ? "{}" == False
--   {}                     ? ""   == False
--   {"":9001}              ? ""   == True
--   </pre>
--   
--   <h3><b>Arrays</b></h3>
--   
--   This operator will match an array if the string to be matched is an
--   element of that array, but nothing else.
--   
--   <pre>
--   ["a"]              ? "a"   == True
--   [["a"]]            ? "a"   == False
--   [9,false,"1",null] ? "1"   == True
--   []                 ? "[]"  == False
--   [{"a":true}]       ? "a"   == False
--   </pre>
--   
--   <h3><b>Other values</b></h3>
--   
--   This operator functions like an equivalence operator on strings only.
--   Any other value does not match.
--   
--   <pre>
--   "a"  ? "a"    == True
--   "1"  ? "1"    == True
--   "ab" ? "a"    == False
--   1    ? "1"    == False
--   null ? "null" == False
--   true ? "true" == False
--   1.5  ? "1.5"  == False
--   </pre>
(?.) :: EntityField record Value -> Text -> Filter record
infix 4 ?.

-- | This operator takes a column and a list of strings to test whether ANY
--   of the elements of the list are top level fields in an object.
--   
--   <pre>
--   column ?|. list
--   </pre>
--   
--   <i>N.B. An empty list <b>will never match anything</b>. Also, this</i>
--   <i>operator might have some unexpected interactions with</i>
--   <i>non-object values. Please reference the examples.</i>
--   
--   <h3><b>Objects</b></h3>
--   
--   <pre>
--   {"a":null}                 ?| ["a","b","c"] == True
--   {"test":false,"a":500}     ?| ["a","b","c"] == True
--   {}                         ?| ["a","{}"]    == False
--   {"b":{"a":[]}}             ?| ["a","c"]     == False
--   {"b":{"a":[]},"test":null} ?| []            == False
--   </pre>
--   
--   <h3><b>Arrays</b></h3>
--   
--   This operator will match an array if <b>any</b> of the elements of the
--   list are matching string elements of the array.
--   
--   <pre>
--   ["a"]              ?| ["a","b","c"] == True
--   [["a"]]            ?| ["a","b","c"] == False
--   [9,false,"1",null] ?| ["a","false"] == False
--   []                 ?| ["a","b","c"] == False
--   []                 ?| []            == False
--   [{"a":true}]       ?| ["a","b","c"] == False
--   [null,4,"b",[]]    ?| ["a","b","c"] == True
--   </pre>
--   
--   <h3><b>Other values</b></h3>
--   
--   This operator functions much like an equivalence operator on strings
--   only. If a string matches with <b>any</b> element of the given list,
--   the comparison matches. No other values match.
--   
--   <pre>
--   "a"  ?| ["a","b","c"] == True
--   "1"  ?| ["a","b","1"] == True
--   "ab" ?| ["a","b","c"] == False
--   1    ?| ["a","1"]     == False
--   null ?| ["a","null"]  == False
--   true ?| ["a","true"]  == False
--   "a"  ?| []            == False
--   </pre>
(?|.) :: EntityField record Value -> [Text] -> Filter record
infix 4 ?|.

-- | This operator takes a column and a list of strings to test whether ALL
--   of the elements of the list are top level fields in an object.
--   
--   <pre>
--   column ?&amp;. list
--   </pre>
--   
--   <i>N.B. An empty list <b>will match anything</b>. Also, this</i>
--   <i>operator might have some unexpected interactions with</i>
--   <i>non-object values. Please reference the examples.</i>
--   
--   <h3><b>Objects</b></h3>
--   
--   <pre>
--   {"a":null}                 ?&amp; ["a"]         == True
--   {"a":null}                 ?&amp; ["a","a"]     == True
--   {"test":false,"a":500}     ?&amp; ["a"]         == True
--   {"test":false,"a":500}     ?&amp; ["a","b"]     == False
--   {}                         ?&amp; ["{}"]        == False
--   {"b":{"a":[]}}             ?&amp; ["a"]         == False
--   {"b":{"a":[]},"c":false}   ?&amp; ["a","c"]     == False
--   {"a":1,"b":2,"c":3,"d":4}  ?&amp; ["b","d"]     == True
--   {}                         ?&amp; []            == True
--   {"b":{"a":[]},"test":null} ?&amp; []            == True
--   </pre>
--   
--   <h3><b>Arrays</b></h3>
--   
--   This operator will match an array if <b>all</b> of the elements of the
--   list are matching string elements of the array.
--   
--   <pre>
--   ["a"]                   ?&amp; ["a"]         == True
--   ["a"]                   ?&amp; ["a","a"]     == True
--   [["a"]]                 ?&amp; ["a"]         == False
--   ["a","b","c"]           ?&amp; ["a","b","d"] == False
--   [9,"false","1",null]    ?&amp; ["1","false"] == True
--   []                      ?&amp; ["a","b"]     == False
--   [{"a":true}]            ?&amp; ["a"]         == False
--   ["a","b","c","d"]       ?&amp; ["b","c","d"] == True
--   [null,4,{"test":false}] ?&amp; []            == True
--   []                      ?&amp; []            == True
--   </pre>
--   
--   <h3><b>Other values</b></h3>
--   
--   This operator functions much like an equivalence operator on strings
--   only. If a string matches with all elements of the given list, the
--   comparison matches.
--   
--   <pre>
--   "a"   ?&amp; ["a"]     == True
--   "1"   ?&amp; ["a","1"] == False
--   "b"   ?&amp; ["b","b"] == True
--   "ab"  ?&amp; ["a","b"] == False
--   1     ?&amp; ["1"]     == False
--   null  ?&amp; ["null"]  == False
--   true  ?&amp; ["true"]  == False
--   31337 ?&amp; []        == True
--   true  ?&amp; []        == True
--   null  ?&amp; []        == True
--   </pre>
(?&.) :: EntityField record Value -> [Text] -> Filter record
infix 4 ?&.

-- | A JSON value represented as a Haskell value.
data Value
instance Database.Persist.Class.PersistField.PersistField a => Database.Persist.Class.PersistField.PersistField (Database.Persist.Postgresql.JSON.PostgresArray a)
instance Database.Persist.Class.PersistField.PersistField Data.Aeson.Types.Internal.Value
instance Database.Persist.Sql.Class.PersistFieldSql Data.Aeson.Types.Internal.Value