This project is a library with bindings allowing to use MongoDB from Luna programming language.
It contains two subprojects:
MongoDB
Luna library;MongoHelper
C++ library.
Third party dependencies include:
libbson
— C library with utilities for handling BSON documents;libmongoc
— MongoDB C driver.
Please refer to MongoDB C Driver documentation pages for installation instructions for all platforms.
Obviously, to use the bindings, a running MongoDB server will be needed.
- Procure
luna
compiler. - Make sure that third-party dependencies are installed.
- Build
MongoHelper
, place binary underPATH
or in the repo undernative_libs/$PLATFORM
subdirectory, as described in the Luna Book. - Call
luna path/to/repo
.
Please see the usage in Main.luna.
- Bindings are still rudimentary and experimental.
- Some APIs are not consistent or not well-thought enough.
- Luna's
ManagedPointer a
is not reliable yet, so until the issue if fixed, resource leaks are unevitable. - Tutorial is just a set of random pieces of code I used when developing the library.
- Missing proper build instructions / build system for
MongoHelper
. - Checked only on Windows.
- Devise proper naming scheme for MongoDB C Driver binaries and/or keep them on the repo.
- Build & Install steps are actually for running my "tests", not use the bindings itself.
All public interface of the library is described below. Each class is in a module with its name. For example, to use Client
class you'll need import MongoDB.Client
. All other modules and APIs should be treated as internal to the library and not used by external code.
This class contains a few methods that are "global" for the Mongo bindings. Its objects can be freely constructed using the MongoDB
constructor.
init :: None
— should be called before making any other call into this library. Initializes a global state of the underlying C driver. NOTE: It is not necessary to call this method manually, it will be called automatically when the first client is created.cleanup :: None
— should be called when there will be no more calls into this library. Releases all the resources allocated by the driver. NOTE: It is not allowed to callinit
once again aftercleanup
!newClient uri :: Text -> Client
— creates a newClient
object representing a MongoDB connection.uri
is aText
parameter, for example"mongodb:https://192.168.11.20:27017"
. Please refer to the MongoDB documentation for more information about supported URI syntax.
This class represents a MongoDB connection. It is typically obtained by a MongoDB.newClient "uri"
call. It is reccemended to set the application name (setAppname
) right after creating the client.
setAppname name :: Text -> None
— takes a name that will be sent to the server as part of an initial handshake. Should be called before initializaing connection.collection databaseName collectionName :: Text -> Text -> Collection
— creates aCollection
object providing access to the collection.database databaseName :: Text -> Database
— creates an object accessing database with a given name.databaseNames :: [Text]
— queries the server for the list known database names.defaultDatabase :: Maybe Database
— creates an object accessing the default database. The database in such case is inferred from the URI — e.g. when client's URI wasmongodb:https://host/db_name
then default database name isdb_name
. If URI did not have database name specified (like inmongodb:https://host/
) thenNothing
is returned.simpleCommand databaseName commandJson :: Text -> JSON -> JSON
— runs the command on database under given name, returning the first document from resulting cursor. Please refer to the MongoDB documentation for more information on database commands.
The object of this class allows performing actions on a specific MongoDB database. Note that it is just a handle to the database, not the collection of documents itself.
collectionNames :: [Text]
— fetches names of all the collections contained by the database.collection name :: Collection
— creates aCollection
control object for collection with a given name. Note: this does not actually create the collection if not present (unless collection is written to later). To immediately create collection please usecreateCollection
method.createCollection name :: Collection
— creates aCollection
in the database. Throws an exception if such collection already exists. Please usecollection
if you just want to work on collection of given name.drop :: None
— drops the database from the server.hasCollection name :: Text -> Bool
— checks if collection with a given name exists in the databasename :: Text
— fetches the database name.
The object provides access for MongoDB collection, supporting CRUD operations.
aggregate pipelineJSON :: JSON -> Cursor
— executes an aggregation query on the collection and returnsCursor
for iterating over results. See MongoDB documentation for details.command coomandJSON :: JSON -> JSON
— executes a command on the collection.count query :: JSON -> Int
— executes a count query on the collection and returns the number of matching documents.distinct key query :: Text -> Maybe JSON -> [JSON]
— returns all distinct values of the fieldkey
, optionally limiting documents from which values shall be retrieved only to the ones matching the query.drop :: None
— drops the collection, including all associated indexes.name :: Text
— fetches the name of the collection.insertOne document :: JSON -> None
— inserts given document into the dollcetion.updateOne selector updates :: JSON -> JSON -> UpdateResult
— executes a query looking for a document matching theselector
— if found, performs update described byupdates
. Please refer to MongoDB documentation for more information on update descriptor syntax. Returns object with two numbers — count of matched documents and count of modified documents.updateMany selector updates :: JSON -> JSON -> UpdateResult
— executes a query looking for all documents matching theselector
— if found, performs update described byupdates
. Please refer to MongoDB documentation for more information on update descriptor syntax. Returns object with two numbers — count of matched documents and count of modified documents.find query :: JSON -> Cursor
— queries the collection and returns cursor allowing iteration over matching documents. See theCursor
class documentation.findAll query :: JSON -> [JSON]
— retrieves all documents in the collection matching toquery
.findOne query :: JSON -> Maybe JSON
— returns any document from the collection that matchesquery
orNothing
if there is none.deleteOne query :: JSON -> Int
— looks for a document matching thequery
and deletes it if found. Returns the deleted documents count (0 or 1).deleteMany query :: JSON -> Int
— deletes all documents matching the query. Returns deleted documents count.rename newDatabaseName newCollectionName dropTargetPolicy :: Text -> Text -> RenamePolicy -> None
— renames the collection. It will remain safe to use after rename (object will point to the renamed collection). Drop dropTargetPolicy can be eitherDropTargetBeforeRename
orDontDropTargetBeforeRename
. The latter is selected, an exception will be raised if collection with the same name as target already exists.
Class for iterating over results of MongoDB query.
batchSize :: Int
— returns the maximum number of documents returned per round trip to the server. Zero means that the cursor accepts the server's maximum batch size.clone :: Cursor
— creates a copy of cursor that will be reset to the beginning of the query.current :: Maybe JSON
— obtains the current document under cursor. ReturnsNothing
after all documents were iterated or before thenext
method was called for the first time.error :: Maybe Text
— checks if error has occurred while iterating the cursor.id :: Int
— returns cursor id used by server, number zero is returned: 1) before the driver uses server when executing query; 2) after all results are fetched.limit :: Int
— returns the previously set limit value, seesetLimit
.next :: Maybe JSON
— iterates the cursor setting it to the next document and returning it.Nothing
means that there are no more documents.setBatchSize :: Int -> None
— sets the cursor's batch size — the maximum number of documents returned per round trip to the server. Please refer to MongoDB documentation for more information on cursor batches.setLimit :: Int -> None
— sets the maximum number of documents to be retrieved by this query. Must be called before the first call to thenext
method.toList :: [Json]
— iterates over all the remaining documents and returns them as a list.
Objects of this class are returned by the updateOne
and updateMany
methods of the Collection
class.
matchedCount :: Int
— number of found documents that matches the query, i.e. documets selected for update.modifiedCount :: Int
— number of actually updated documents. If the update operation results in no change for a document (like setting already set value), this value will be lower thanmatchedCount
.
toJSON :: JSON
toText :: Text