Safe Haskell | None |
---|---|
Language | Haskell98 |
Use persistent-mongodb the same way you would use other persistent libraries and refer to the general persistent documentation. There are some new MongoDB specific filters under the filters section. These help extend your query into a nested document.
However, at some point you will find the normal Persistent APIs lacking. and want lower level-level MongoDB access. There are functions available to make working with the raw driver easier: they are under the Entity conversion section. You should still use the same connection pool that you are using for Persistent.
MongoDB is a schema-less database. The MongoDB Persistent backend does not help perform migrations. Unlike SQL backends, uniqueness constraints cannot be created for you. You must place a unique index on unique fields.
- collectionName :: PersistEntity record => record -> Text
- docToEntityEither :: forall record. PersistEntity record => Document -> Either Text (Entity record)
- docToEntityThrow :: forall m record. (MonadIO m, PersistEntity record) => Document -> m (Entity record)
- entityToDocument :: PersistEntity record => record -> Document
- toInsertDoc :: forall record. PersistEntity record => record -> Document
- updatesToDoc :: PersistEntity entity => [Update entity] -> Document
- filtersToDoc :: (PersistEntity val, PersistEntityBackend val ~ MongoBackend) => [Filter val] -> Document
- toUniquesDoc :: forall record. PersistEntity record => Unique record -> [Field]
- toInsertFields :: forall record. PersistEntity record => record -> [Field]
- entityToFields :: PersistEntity record => record -> [Field]
- nestEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record
- nestNe :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record
- nestGe :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record
- nestLe :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record
- nestIn :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record
- nestNotIn :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record
- anyEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> typ -> Filter record
- multiEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> typ -> Filter record
- nestBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> Value -> Filter record
- anyBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> Value -> Filter record
- multiBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> Value -> Filter record
- (=~.) :: forall record searchable. (MongoRegexSearchable searchable, PersistEntity record, PersistEntityBackend record ~ MongoBackend) => EntityField record searchable -> MongoRegex -> Filter record
- (?=~.) :: forall record. (PersistEntity record, PersistEntityBackend record ~ MongoBackend) => EntityField record (Maybe Text) -> MongoRegex -> Filter record
- type MongoRegex = (Text, Text)
- (->.) :: forall record emb typ. PersistEntity emb => EntityField record [emb] -> EntityField emb typ -> NestedField record typ
- (~>.) :: forall record typ emb. PersistEntity emb => EntityField record [emb] -> NestedField emb typ -> NestedField record typ
- (?&->.) :: forall record typ nest. PersistEntity nest => EntityField record (Maybe nest) -> EntityField nest typ -> NestedField record typ
- (?&~>.) :: forall val nes nes1. PersistEntity nes1 => EntityField val (Maybe nes1) -> NestedField nes1 nes -> NestedField val nes
- (&->.) :: forall record typ nest. PersistEntity nest => EntityField record nest -> EntityField nest typ -> NestedField record typ
- (&~>.) :: forall val nes nes1. PersistEntity nes1 => EntityField val nes1 -> NestedField nes1 nes -> NestedField val nes
- data NestedField record typ
- = forall emb . PersistEntity emb => (EntityField record [emb]) `LastEmbFld` (EntityField emb typ)
- | forall emb . PersistEntity emb => (EntityField record [emb]) `MidEmbFld` (NestedField emb typ)
- | forall nest . PersistEntity nest => (EntityField record nest) `MidNestFlds` (NestedField nest typ)
- | forall nest . PersistEntity nest => (EntityField record (Maybe nest)) `MidNestFldsNullable` (NestedField nest typ)
- | forall nest . PersistEntity nest => (EntityField record nest) `LastNestFld` (EntityField nest typ)
- | forall nest . PersistEntity nest => (EntityField record (Maybe nest)) `LastNestFldNullable` (EntityField nest typ)
- class PersistField typ => MongoRegexSearchable typ
- data Objectid
- genObjectid :: IO Objectid
- keyToOid :: (PersistEntity entity, PersistEntityBackend entity ~ MongoBackend) => Key entity -> ObjectId
- oidToKey :: PersistEntity entity => ObjectId -> Key entity
- recordTypeFromKey :: KeyBackend MongoBackend v -> v
- fieldName :: forall record typ. PersistEntity record => EntityField record typ -> Label
- withConnection :: (MonadIO m, Applicative m) => MongoConf -> (ConnectionPool -> m b) -> m b
- withMongoPool :: (MonadIO m, Applicative m) => MongoConf -> (ConnectionPool -> m b) -> m b
- withMongoDBConn :: (MonadIO m, Applicative m) => Database -> HostName -> PortID -> Maybe MongoAuth -> NominalDiffTime -> (ConnectionPool -> m b) -> m b
- withMongoDBPool :: (MonadIO m, Applicative m) => Database -> HostName -> PortID -> Maybe MongoAuth -> Int -> Int -> NominalDiffTime -> (ConnectionPool -> m b) -> m b
- createMongoDBPool :: (MonadIO m, Applicative m) => Database -> HostName -> PortID -> Maybe MongoAuth -> Int -> Int -> NominalDiffTime -> m ConnectionPool
- runMongoDBPool :: (MonadIO m, MonadBaseControl IO m) => AccessMode -> Action m a -> ConnectionPool -> m a
- runMongoDBPoolDef :: (MonadIO m, MonadBaseControl IO m) => Action m a -> ConnectionPool -> m a
- type ConnectionPool = Pool Connection
- data Connection
- data MongoBackend
- data MongoAuth = MongoAuth Username Password
- data MongoConf = MongoConf {
- mgDatabase :: Text
- mgHost :: Text
- mgPort :: PortID
- mgAuth :: Maybe MongoAuth
- mgAccessMode :: AccessMode
- mgPoolStripes :: Int
- mgStripeConnections :: Int
- mgConnectionIdleTime :: NominalDiffTime
- mgReplicaSetConfig :: Maybe ReplicaSetConfig
- defaultMongoConf :: Text -> MongoConf
- defaultHost :: Text
- defaultAccessMode :: AccessMode
- defaultPoolStripes :: Int
- defaultConnectionIdleTime :: NominalDiffTime
- defaultStripeConnections :: Int
- applyDockerEnv :: MongoConf -> IO MongoConf
- type PipePool = Pool Pipe
- createMongoDBPipePool :: (MonadIO m, Applicative m) => HostName -> PortID -> Int -> Int -> NominalDiffTime -> m PipePool
- runMongoDBPipePool :: (MonadIO m, MonadBaseControl IO m) => AccessMode -> Database -> Action m a -> PipePool -> m a
- type HostName = String
- data PortID :: *
- type Database = Text
- data Action m a :: (* -> *) -> * -> *
- data AccessMode :: *
- master :: AccessMode
- slaveOk :: AccessMode
- (=:) :: Val v => Label -> v -> Field
- module Database.Persist
Entity conversion
collectionName :: PersistEntity record => record -> Text Source
docToEntityEither :: forall record. PersistEntity record => Document -> Either Text (Entity record) Source
docToEntityThrow :: forall m record. (MonadIO m, PersistEntity record) => Document -> m (Entity record) Source
entityToDocument :: PersistEntity record => record -> Document Source
convert a PersistEntity into document fields.
unlike toInsertDoc
, nulls are included.
toInsertDoc :: forall record. PersistEntity record => record -> Document Source
convert a PersistEntity into document fields.
for inserts only: nulls are ignored so they will be unset in the document.
entityToDocument
includes nulls
updatesToDoc :: PersistEntity entity => [Update entity] -> Document Source
filtersToDoc :: (PersistEntity val, PersistEntityBackend val ~ MongoBackend) => [Filter val] -> Document Source
toUniquesDoc :: forall record. PersistEntity record => Unique record -> [Field] Source
toInsertFields :: forall record. PersistEntity record => record -> [Field] Source
Deprecated: Please use toInsertDoc instead
entityToFields :: PersistEntity record => record -> [Field] Source
Deprecated: Please use entityToDocument instead
Deprecated, use the better named entityToDocument
MongoDB specific Filters
You can find example usage for all of Persistent in our test cases: https://github.com/yesodweb/persistent/blob/master/persistent-test/EmbedTest.hs#L144
These filters create a query that reaches deeper into a document with nested fields.
nestEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record infixr 4 Source
nestNe :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record infixr 4 Source
nestGe :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record infixr 4 Source
nestLe :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record infixr 4 Source
nestIn :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record infixr 4 Source
nestNotIn :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> typ -> Filter record infixr 4 Source
anyEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> typ -> Filter record infixr 4 Source
Like nestEq, but for an embedded list. Checks to see if the list contains an item.
In Haskell we need different equality functions for embedded fields that are lists or non-lists to keep things type-safe.
using this as the only query filter is similar to the following in the mongoDB shell
db.Collection.find({arrayField: arrayItem})
multiEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> typ -> Filter record infixr 4 Source
Deprecated: Please use anyEq instead
nestBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> Value -> Filter record infixr 4 Source
same as nestEq
, but give a BSON Value
anyBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> Value -> Filter record infixr 4 Source
same as anyEq
, but give a BSON Value
multiBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> Value -> Filter record infixr 4 Source
Deprecated: Please use anyBsonEq instead
(=~.) :: forall record searchable. (MongoRegexSearchable searchable, PersistEntity record, PersistEntityBackend record ~ MongoBackend) => EntityField record searchable -> MongoRegex -> Filter record infixr 4 Source
Filter using a Regular expression.
(?=~.) :: forall record. (PersistEntity record, PersistEntityBackend record ~ MongoBackend) => EntityField record (Maybe Text) -> MongoRegex -> Filter record infixr 4 Source
Deprecated: Use =~. instead
Filter using a Regular expression against a nullable field.
type MongoRegex = (Text, Text) Source
A MongoRegex represetns a Regular expression.
It is a tuple of the expression and the options for the regular expression, respectively
Options are listed here: http://docs.mongodb.org/manual/reference/operator/query/regex/
If you use the same options you may want to define a helper such as r t = (t, "ims")
(->.) :: forall record emb typ. PersistEntity emb => EntityField record [emb] -> EntityField emb typ -> NestedField record typ infixr 6 Source
Point to an array field with an embedded object and give a deeper query into the embedded object.
Use with nestEq
.
(~>.) :: forall record typ emb. PersistEntity emb => EntityField record [emb] -> NestedField emb typ -> NestedField record typ infixr 5 Source
(?&->.) :: forall record typ nest. PersistEntity nest => EntityField record (Maybe nest) -> EntityField nest typ -> NestedField record typ infixr 6 Source
Same as &->.
, but Works against a Maybe type
(?&~>.) :: forall val nes nes1. PersistEntity nes1 => EntityField val (Maybe nes1) -> NestedField nes1 nes -> NestedField val nes infixr 5 Source
Same as &~>.
, but works against a Maybe type
(&->.) :: forall record typ nest. PersistEntity nest => EntityField record nest -> EntityField nest typ -> NestedField record typ infixr 6 Source
Point to a nested field to query. This field is not an array type.
Use with nestEq
.
(&~>.) :: forall val nes nes1. PersistEntity nes1 => EntityField val nes1 -> NestedField nes1 nes -> NestedField val nes infixr 5 Source
Point to a nested field to query. This field is not an array type.
This level of nesting is not the final level.
Use ->.
or &>.
to point to the final level.
data NestedField record typ Source
forall emb . PersistEntity emb => (EntityField record [emb]) `LastEmbFld` (EntityField emb typ) | |
forall emb . PersistEntity emb => (EntityField record [emb]) `MidEmbFld` (NestedField emb typ) | |
forall nest . PersistEntity nest => (EntityField record nest) `MidNestFlds` (NestedField nest typ) | |
forall nest . PersistEntity nest => (EntityField record (Maybe nest)) `MidNestFldsNullable` (NestedField nest typ) | |
forall nest . PersistEntity nest => (EntityField record nest) `LastNestFld` (EntityField nest typ) | |
forall nest . PersistEntity nest => (EntityField record (Maybe nest)) `LastNestFldNullable` (EntityField nest typ) |
class PersistField typ => MongoRegexSearchable typ Source
Mark the subset of PersistField
s that can be searched by a mongoDB regex
Anything stored as PersistText or an array of PersistText would be valid
MongoRegexSearchable Text | |
MongoRegexSearchable rs => MongoRegexSearchable [rs] | |
MongoRegexSearchable rs => MongoRegexSearchable (Maybe rs) |
MongoDB specific PersistFields
wrapper of ObjectId
- avoids an orphan instance
- works around a Persistent naming issue
genObjectid :: IO Objectid Source
like genObjectId
, but for Objectid
Key conversion helpers
keyToOid :: (PersistEntity entity, PersistEntityBackend entity ~ MongoBackend) => Key entity -> ObjectId Source
oidToKey :: PersistEntity entity => ObjectId -> Key entity Source
recordTypeFromKey :: KeyBackend MongoBackend v -> v Source
PersistField conversion
fieldName :: forall record typ. PersistEntity record => EntityField record typ -> Label Source
using connections
withConnection :: (MonadIO m, Applicative m) => MongoConf -> (ConnectionPool -> m b) -> m b Source
withMongoPool :: (MonadIO m, Applicative m) => MongoConf -> (ConnectionPool -> m b) -> m b Source
withMongoDBConn :: (MonadIO m, Applicative m) => Database -> HostName -> PortID -> Maybe MongoAuth -> NominalDiffTime -> (ConnectionPool -> m b) -> m b Source
withMongoDBPool :: (MonadIO m, Applicative m) => Database -> HostName -> PortID -> Maybe MongoAuth -> Int -> Int -> NominalDiffTime -> (ConnectionPool -> m b) -> m b Source
:: (MonadIO m, Applicative m) | |
=> Database | |
-> HostName | |
-> PortID | |
-> Maybe MongoAuth | |
-> Int | pool size (number of stripes) |
-> Int | stripe size (number of connections per stripe) |
-> NominalDiffTime | time a connection is left idle before closing |
-> m ConnectionPool |
runMongoDBPool :: (MonadIO m, MonadBaseControl IO m) => AccessMode -> Action m a -> ConnectionPool -> m a Source
runMongoDBPoolDef :: (MonadIO m, MonadBaseControl IO m) => Action m a -> ConnectionPool -> m a Source
use default AccessMode
type ConnectionPool = Pool Connection Source
data Connection Source
data MongoBackend Source
Typeable * MongoBackend | |
PathPiece (KeyBackend MongoBackend entity) | ToPathPiece is used to convert a key to/from text |
type BackendSpecificFilter MongoBackend record |
Connection configuration
Information required to connect to a mongo database
MongoConf | |
|
defaultMongoConf :: Text -> MongoConf Source
applyDockerEnv :: MongoConf -> IO MongoConf Source
docker integration: change the host to the mongodb link
using raw MongoDB pipes
:: (MonadIO m, Applicative m) | |
=> HostName | |
-> PortID | |
-> Int | pool size (number of stripes) |
-> Int | stripe size (number of connections per stripe) |
-> NominalDiffTime | time a connection is left idle before closing |
-> m PipePool |
A pool of plain MongoDB pipes. The database parameter has not yet been applied yet. This is useful for switching between databases (on the same host and port) Unlike the normal pool, no authentication is available
runMongoDBPipePool :: (MonadIO m, MonadBaseControl IO m) => AccessMode -> Database -> Action m a -> PipePool -> m a Source
run a pool created with createMongoDBPipePool
network type
Either a host name e.g., "haskell.org"
or a numeric host
address string consisting of a dotted decimal IPv4 address or an
IPv6 address e.g., "192.168.0.1"
.
MongoDB driver types
data Action m a :: (* -> *) -> * -> *
A monad on top of m (which must be a MonadIO) that may access the database and may fail with a DB Failure
MonadTrans Action | |
MonadTransControl Action | |
(MonadIO m, MonadBaseControl b m) => MonadBaseControl b (Action m) | |
MonadBase b m => MonadBase b (Action m) | |
Monad m => MonadError Failure (Action m) | |
Monad m => Monad (Action m) | |
Functor m => Functor (Action m) | |
(Monad m, Functor m) => Applicative (Action m) | |
MonadThrow m => MonadThrow (Action m) | |
(MonadBaseControl IO m, Applicative m, Functor m) => MonadDB (Action m) | |
MonadIO m => MonadIO (Action m) | |
(Applicative m, Functor m, MonadIO m, MonadBaseControl IO m) => PersistUnique (Action m) | |
(Applicative m, Functor m, MonadIO m, MonadBaseControl IO m) => PersistQuery (Action m) | |
(Applicative m, Functor m, MonadIO m, MonadBaseControl IO m) => PersistStore (Action m) | |
data StT Action = StActionT {} | |
data StM (Action m) = StMT {} | |
type BaseMonad (Action m) = m | |
type PersistMonadBackend (Action m) = MongoBackend |
data AccessMode :: *
Type of reads and writes to perform
ReadStaleOk | Read-only action, reading stale data from a slave is OK. |
UnconfirmedWrites | Read-write action, slave not OK, every write is fire & forget. |
ConfirmWrites GetLastError | Read-write action, slave not OK, every write is confirmed with getLastError. |
master :: AccessMode
Same as ConfirmWrites
[]
Same as ReadStaleOk
Database.Persist
module Database.Persist