persistent-mongoDB-1.3.0.3: Backend for the persistent library using mongoDB.

Safe HaskellNone

Database.Persist.MongoDB

Contents

Description

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.

Synopsis

Entity conversion

collectionName :: PersistEntity record => record -> TextSource

entityToDocument :: PersistEntity record => record -> [Field]Source

convert a PersistEntity into document fields. unlike toInsertFields, nulls are included.

entityToFields :: PersistEntity record => record -> [Field]Source

Deprecated: Please use entityToDocument instead

Deprecated, use the better named entityToDocument

toInsertFields :: forall record. PersistEntity record => record -> [Field]Source

convert a PersistEntity into document fields. for inserts only: nulls are ignored so they will be unset in the document. entityToFields includes nulls

docToEntityEither :: forall record. PersistEntity record => Document -> Either Text (Entity record)Source

docToEntityThrow :: forall m record. (MonadIO m, PersistEntity record) => Document -> m (Entity record)Source

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 recordSource

The normal Persistent equality test (==.) is not generic enough. Instead use this with the drill-down operaters (->.) or (?->.)

multiEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> typ -> Filter recordSource

use to see if an embedded list contains an item

nestBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => NestedField record typ -> Value -> Filter recordSource

same as nestEq, but give a BSON Value

multiBsonEq :: forall record typ. (PersistField typ, PersistEntityBackend record ~ MongoBackend) => EntityField record [typ] -> Value -> Filter recordSource

same as multiEq, but give a BSON Value

(=~.) :: forall record. (PersistEntity record, PersistEntityBackend record ~ MongoBackend) => EntityField record Text -> MongoRegex -> Filter recordSource

Filter using a Regular expression.

(?=~.) :: forall record. (PersistEntity record, PersistEntityBackend record ~ MongoBackend) => EntityField record (Maybe Text) -> MongoRegex -> Filter recordSource

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 typSource

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 typSource

Point to an array field with an embedded object and give a deeper query into the embedded object. This level of nesting is not the final level. Use ->. or &->. to point to the final level.

(?&->.) :: forall record typ nest. PersistEntity nest => EntityField record (Maybe nest) -> EntityField nest typ -> NestedField record typSource

Same as &->., but Works against a Maybe type

(?&~>.) :: forall val nes nes1. PersistEntity nes1 => EntityField val (Maybe nes1) -> NestedField nes1 nes -> NestedField val nesSource

Same as &~>., but works against a Maybe type

(&->.) :: forall record typ nest. PersistEntity nest => EntityField record nest -> EntityField nest typ -> NestedField record typSource

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 nesSource

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

Constructors

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) 

MongoDB specific PersistFields

data Objectid Source

wrapper of ObjectId

  • avoids an orphan instance * works around a Persistent naming issue

genObjectid :: IO ObjectidSource

like genObjectId, but for Objectid

using connections

createMongoDBPoolSource

Arguments

:: (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 

runMongoDBPoolDef :: (MonadIO m, MonadBaseControl IO m) => Action m a -> ConnectionPool -> m aSource

use default AccessMode

data MongoConf Source

Information required to connect to a mongo database

data MongoBackend Source

Instances

Typeable MongoBackend 
PathPiece (KeyBackend MongoBackend entity)

ToPathPiece is used to convert a key to/from text

using raw MongoDB pipes

createMongoDBPipePoolSource

Arguments

:: (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

Key conversion helpers

oidToKey :: PersistEntity entity => ObjectId -> Key entitySource

network type

type HostName = String

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".

data PortID

Instances

MongoDB driver types

type Database = Text

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

data AccessMode

Type of reads and writes to perform

Constructors

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.

Instances

(=:) :: Val v => Label -> v -> Field

Field with given label and typed value

Database.Persist