{"id":13529891,"url":"https://github.com/Fantom-Factory/afMongo","last_synced_at":"2025-04-01T17:31:21.824Z","repository":{"id":94375840,"uuid":"134714213","full_name":"Fantom-Factory/afMongo","owner":"Fantom-Factory","description":"A pure Fantom driver for MongoDB","archived":false,"fork":false,"pushed_at":"2024-02-24T12:48:28.000Z","size":503,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-02T16:35:38.745Z","etag":null,"topics":["fantom","mongodb-driver"],"latest_commit_sha":null,"homepage":"http://eggbox.fantomfactory.org/pods/afMongo/","language":"Fantom","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fantom-Factory.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-24T12:45:58.000Z","updated_at":"2022-01-06T11:28:38.000Z","dependencies_parsed_at":"2024-04-13T03:49:15.689Z","dependency_job_id":null,"html_url":"https://github.com/Fantom-Factory/afMongo","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fantom-Factory%2FafMongo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fantom-Factory%2FafMongo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fantom-Factory%2FafMongo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fantom-Factory%2FafMongo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fantom-Factory","download_url":"https://codeload.github.com/Fantom-Factory/afMongo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246680264,"owners_count":20816665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fantom","mongodb-driver"],"created_at":"2024-08-01T07:00:40.351Z","updated_at":"2025-04-01T17:31:21.416Z","avatar_url":"https://github.com/Fantom-Factory.png","language":"Fantom","funding_links":[],"categories":["Libraries"],"sub_categories":["Fantom"],"readme":"# Mongo v2.1.8\n---\n\n[![Written in: Fantom](http://img.shields.io/badge/written%20in-Fantom-lightgray.svg)](https://fantom-lang.org/)\n[![pod: v2.1.8](http://img.shields.io/badge/pod-v2.1.8-yellow.svg)](http://eggbox.fantomfactory.org/pods/afMongo)\n[![Licence: ISC](http://img.shields.io/badge/licence-ISC-blue.svg)](https://choosealicense.com/licenses/isc/)\n\n## Overview\n\nMongo is a pure Fantom driver for [MongoDB](http://www.mongodb.org/).\n\nMongo driver features:\n\n* Developed against the MongoDB Stable API v1 from MongoDB 5.2+ (compatible with MongoDB 3.6+)\n* Support for multi-document, multi-collection transactions\n* Support for retryable read and write operations\n* Support for Replica Set connection URLs\n* Pooled Connection Manager for multi-threaded use and automatic topology scanning and connection fail over\n* Pluggable authentication with a default [SCRAM-SHA-1 over SASL](http://www.alienfactory.co.uk/articles/mongodb-scramsha1-over-sasl) implementation\n* `zlib` wire compression\n\n\nMongo API features:\n\n* Standard CRUD commands: `insert()`, `find()`, `update()`, `replace()`, and `delete()`\n* Special commands: `count()`, `aggregate()`, `findAndUpdate()`, `findAndDelete()`\n* Index support commands: `create()`, `ensure()` and `drop()`\n* Large query cursor support\n* Text indexes and text searching\n* Simplified Query DSL syntax\u003e \n    **ALIEN-AID:** See [Morphia](http://eggbox.fantomfactory.org/pods/afMorphia) for a complete Fantom to MongoDB object mapping library!\n\n\n\n\n## \u003ca name=\"Install\"\u003e\u003c/a\u003eInstall\n\nInstall `Mongo` with the Fantom Pod Manager ( [FPM](http://eggbox.fantomfactory.org/pods/afFpm) ):\n\n    C:\\\u003e fpm install afMongo\n\nOr install `Mongo` with [fanr](https://fantom.org/doc/docFanr/Tool.html#install):\n\n    C:\\\u003e fanr install -r http://eggbox.fantomfactory.org/fanr/ afMongo\n\nTo use in a [Fantom](https://fantom-lang.org/) project, add a dependency to `build.fan`:\n\n    depends = [\"sys 1.0\", ..., \"afMongo 2.1\"]\n\n## \u003ca name=\"documentation\"\u003e\u003c/a\u003eDocumentation\n\nFull API \u0026 fandocs are available on the [Eggbox](http://eggbox.fantomfactory.org/pods/afMongo/) - the Fantom Pod Repository.\n\n## \u003ca name=\"quickStart\"\u003e\u003c/a\u003eQuick Start\n\n1. Start up an instance of MongoDB:    C:\\\u003e mongod\n    \n    MongoDB starting\n    db version v5.2.0\n    waiting for connections on port 27017\n\n\n2. Create a text file called `Example.fan`    using afBson::BsonIO\n    using afMongo\n    \n    class Example {\n    \n        Void main() {\n            mongoClient := MongoClient(`mongodb://localhost:27017`)\n            collection  := mongoClient.db(\"friends\").collection(\"birds\")\n    \n            documentIn  := [\n                \"_id\"   : ObjectId(),\n                \"name\"  : \"Emma\",\n                \"score\" : 9\n            ]\n            collection.insert(documentIn)\n    \n            emma        := collection.find.toList.first\n    \n            echo(\"Emma:\")\n            echo(BsonIO().print(emma, 20))\n    \n            mongoClient.shutdown\n        }\n    }\n\n\n3. Run `Example.fan` as a Fantom script from the command line:    C:\\\u003e fan Example.fan\n    \n          Fantom-Factory\n      _____ ___ ___ ___ ___\n     |     | . |   | . | . |\n     |_|_|_|___|_|_|_  |___|\n                  |___|2.1.0\n    \n    Connected to MongoDB v5.2.0 (at mongodb://localhost:27017)\n    \n    Emma:\n    {\n      \"_id\"   : ObjectId(\"57fe499fa81320d933000001\"),\n      \"name\"  : \"Emma\"\n      \"score\" : 9,\n    }\n\n\n\n\n## Usage\n\n[MongoClient](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoClient) is the main entry point into `Mongo`, with [MongoConnMgr](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoConnMgr) underpinning everything. From there you can access all other components of MongoDB, namely [MongoDb](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoDb), [MongoColl](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoColl), [MongoIdx](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoIdx).\n\n    MongoConnMgr                  : Connection Pool\n      +-- MongoClient             : Client\n           +-- MongoDb            : Database\n                +-- MongoColl     : Collection\n                     +-- MongoIdx : Index\n    \n\n## Connecting\n\n`MongoClient` may be created with a [MongoConnMgr](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoConnMgr), which manages your connections to MongoDB for application wide, multi-threaded use:\n\n    connMgr := MongoConnMgr(`mongodb://localhost:27017`)\n    client  := MongoClient(connMgr)\n    \n\nWhen you create a `MongoClient` it immediately connects to MongoDB and verifies the version:\n\n    .    Fantom-Factory\n     _____ ___ ___ ___ ___\n    |     | . |   | . | . |\n    |_|_|_|___|_|_|_  |___|\n                  |___|2.1.0\n    \n    Connected to MongoDB v5.2.0\n    \n\nNote that `MongoConnMgrPool` will always query the supplied MongoDB host(s) to find the primary node, on which all read and write operations are performed.\n\n## Queries\n\nMongo works with BSON documents.\n\nBSON documents are represented in Fantom as a Map of type `[Str:Obj?]`. All document keys must be strings. Document values can be any valid [BSON](http://eggbox.fantomfactory.org/pods/afBson) type.\n\nMongoDB stores BSON documents in Collections. Use the `find()` methods to query a collection. Using the `friends` database in the [QuickStart Example](#quickStart) we could do:\n\n    collection.findOne( [\"name\":\"Emma\"] )       // --\u003e return the doc where 'name == Emma'\n                                                //     ('Emma' must be unique)\n    \n    collection.find                             // --\u003e return ALL docs in the collection\n    collection.find( [\"name\":\"Emma\"] )          // --\u003e return all docs where 'name == Emma'\n    collection.find( [\"score\": [\"\\$gt\":7]] )    // --\u003e return all docs with 'score \u003e 7'\n    \n\nThe `$gt` expression is an example of a [Query operator](http://docs.mongodb.org/manual/reference/operator/query/).\n\nThis driver also supplies a little DSL for creating queries, in the form of [MongoQ](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoQ), which can make Mongo queries much easier to write.\n\n    // query using standard BSON\n    query := [\n        \"\\$and\" : [\n            [\"\\$or\": [[\"price\": 0.99f], [\"price\": 1.99f]]],\n            [\"\\$or\": [[\"sale\" : true ], [\"qty\"  : [\"\\$lt\": 20]]]]\n        ]\n    ]\n    \n    // same query using afMongo's DSL\n    query := MongoQ {\n        and(\n            or( eq(\"price\", 0.99f), eq(\"price\", 1.99f)  ),\n            or( eq(\"sale\", true),   lessThan(\"qty\", 29) )\n        )\n    }.query\n    \n    collection.find(query)\n    \n\nTo iterate over *large* result sets without loading it all into memory, use a [Cursor](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoCur). `Cursors` download documents in batches, behind the scenes, as and when required. Create and use a `Cursor` by using the `find()` method:\n\n    cursor := coll.find( [\"score\": [\"\\$gt\":2]] )\n    cursor.batchSize = 10\n    \n    while (cursor.isAlive)\n        doc := cursor.next\n        ...\n    }\n    \n    cursor.kill\n    \n\n## Write Commands\n\nThe `insert()` command is simple enough and is demonstrated in the [QuickStart example](#quickStart).\n\n`update()`, `replace()`, and `delete()` are similar in that they both take a query that describes which document(s) are to be updated / deleted. For most usages this will a simply be the id of the document in question:\n\n    collection.replace( [\"_id\": objId], [ ...new doc...] )\n    \n\nMongo will throw a `MongoErr` should a write error occur.\n\n## ObjectId\n\nAll documents held in a collection need a unique id, held in a field named `_id`. If the `_id` field does not exist, MongoDB will create one for you of type [ObjectId](http://eggbox.fantomfactory.org/pods/afBson/api/ObjectId).\n\nNote that `_id` does not need to an `ObjectId`, it can be any BSON type. It just needs to be unique in the collection.\n\nLike [marmite](http://www.ilovemarmite.com/), people tend to have a love / hate relationship with the `ObjectId`. The good comments revolve around it having a natural sort that (roughly) corresponds to creation time. The bad is that it's a large human-unfriendly 24 char identifier, and in *humongous* collections it eats up precious bytes which means the [index may not fit into RAM](http://docs.mongodb.org/manual/tutorial/ensure-indexes-fit-ram/).\n\nIf sequential integers are more your thing when it comes to IDs, then [MongoSeqs](http://eggbox.fantomfactory.org/pods/afMongo/api/MongoSeqs) contains helper methods that use atomic updates on a named Collection to keep track of generated IDs.\n\n## Connection Fail Over\n\nThe `MongoConnMgrPool` accepts a replica set URL with multiple hosts (with optional ports):\n\n    mongodb://db1.example.net,db2.example.net:2500/?connectTimeoutMS=30000\n\nWhen  `startup()` is called, the hosts are queried to find the primary / master node. All read and write operations are then performed on this primary node.\n\nWhen a connection to the master node is lost, all hosts are automatically re-queried to find a new master.\n\n## Remarks\n\nThe Fantom-Factory MongoDB driver was inspired by [fantomongo](https://bitbucket.org/liamstask/fantomongo) by Liam Staskawicz.\n\nIf you're looking for cross-platform MongoDB GUI client then look no further than [Robomongo](http://robomongo.org/) / Robo 3T / Studio 3T Free!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFantom-Factory%2FafMongo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFantom-Factory%2FafMongo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFantom-Factory%2FafMongo/lists"}