{"id":14956794,"url":"https://github.com/neoxic/lua-mongo","last_synced_at":"2025-10-03T18:57:24.529Z","repository":{"id":55074243,"uuid":"75911384","full_name":"neoxic/lua-mongo","owner":"neoxic","description":"MongoDB Driver for Lua","archived":false,"fork":false,"pushed_at":"2023-03-31T21:52:22.000Z","size":258,"stargazers_count":145,"open_issues_count":2,"forks_count":40,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-01-29T09:51:16.972Z","etag":null,"topics":["bson","lua","lua-mongo","mongo","mongodb","mongodb-driver"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neoxic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2016-12-08T06:50:30.000Z","updated_at":"2024-12-30T17:43:36.000Z","dependencies_parsed_at":"2024-09-02T15:41:41.840Z","dependency_job_id":null,"html_url":"https://github.com/neoxic/lua-mongo","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neoxic%2Flua-mongo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neoxic%2Flua-mongo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neoxic%2Flua-mongo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neoxic%2Flua-mongo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neoxic","download_url":"https://codeload.github.com/neoxic/lua-mongo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237950861,"owners_count":19392667,"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":["bson","lua","lua-mongo","mongo","mongodb","mongodb-driver"],"created_at":"2024-09-24T13:13:32.526Z","updated_at":"2025-10-03T18:57:19.506Z","avatar_url":"https://github.com/neoxic.png","language":"C","readme":"MongoDB Driver for Lua\n======================\n\n[lua-mongo] is a binding to [MongoDB C Driver] 1.16 or higher for Lua:\n- Unified API for MongoDB commands, CRUD operations and GridFS in [MongoDB C Driver].\n- Support for data transformation metamethods/handlers when converting to/from BSON documents.\n- Transparent conversion from Lua/JSON to BSON for convenience.\n- Automatic conversion of Lua numbers to/from BSON Int32, Int64 and Double types depending on their\n  capacity without precision loss (when Lua allows it). Manual conversion is also available.\n\n\nDependencies\n------------\n\n+ lua \u003e= 5.1 (or luajit)\n+ mongo-c-driver \u003e= 1.16\n\n\nBuilding and installing with LuaRocks\n-------------------------------------\n\nTo build and install, run:\n\n    luarocks make\n\nTo install the latest release using [luarocks.org], run:\n\n    luarocks install lua-mongo\n\n\nBuilding and installing with CMake\n----------------------------------\n\nTo build and install, run:\n\n    cmake .\n    make\n    make install\n\nTo build for a specific Lua version, set `USE_LUA_VERSION`. For example:\n\n    cmake -D USE_LUA_VERSION=5.1 .\n\nor for LuaJIT:\n\n    cmake -D USE_LUA_VERSION=jit .\n\nTo build in a separate directory, replace `.` with a path to the source.\n\nTo check your build, run:\n\n    make test\n\nA local MongoDB server at `mongodb://127.0.0.1` will be used for testing by default. Test settings\ncan be configured in `test/test.lua`.\n\n\nGetting started\n---------------\n\nPreparing the playground:\n\n```Lua\nlocal mongo = require 'mongo'\nlocal client = mongo.Client('mongodb://127.0.0.1')\nlocal collection = client:getCollection('lua-mongo-test', 'test')\ncollection:drop() -- Clear collection\n\n-- Common variables\nlocal id = mongo.ObjectID()\nlocal query1 = mongo.BSON('{ \"age\" : { \"$gt\" : 25 } }')\nlocal query2 = mongo.BSON{_id = id}\n```\n\n\nBasic features and operations:\n\n```Lua\n-- Implicit Lua/JSON to BSON conversion where BSON is required\ncollection:insert{_id = id, name = 'John Smith', age = 50}\ncollection:insert('{ \"name\" : \"Bobby\", \"age\" : 3 }')\n\n-- Iterate documents in a for-loop\nfor person in collection:find({}, {sort = {age = -1}}):iterator() do\n    print(person.name, person.age)\nend\n\n-- Fetch single document\nlocal person = collection:findOne(query1):value()\nprint(person.name, person.age)\n\n-- Access to BSON where needed\nlocal bson = collection:findOne(query1)\nprint(bson) -- BSON is converted to JSON using tostring()\n\n-- Explicit BSON to Lua conversion\nlocal person = bson:value()\nprint(person.name, person.age)\n\n-- Transparently include BSON documents in other documents\ncollection:update(query2, {age = 60, old = bson}) -- Update document\ncollection:remove(query2) -- Remove document\n```\n\n\nBulk write operations can be used to execute multiple insert, update, replace and remove operations\ntogether. Executing write operations in batches reduces the number of network round trips increasing\nwrite throughput.\n\n```Lua\nlocal bulk = collection:createBulkOperation()\n\n-- Multiple insertions\nbulk:insert{a = 1}\nbulk:insert{b = 2}\nbulk:insert{c = 3}\n\n-- Multiple modifications\nbulk:replaceOne({a = 1}, {b = 1})\nbulk:updateMany('{}', '{ \"$inc\" : { \"b\" : 2 } }')\nbulk:removeOne{c = 3}\n\n-- Execute queued operations\nbulk:execute()\n```\n\n\nThe use of `__toBSON` metamethods and BSON handlers gives full control over how Lua values are\nrepresented in BSON documents and vice versa. In particular, this API facilitates support for\nLua classes (tables with metatables) on their way to and/or from MongoDB.\n\n```Lua\nlocal TestClass = {} -- Class metatable\n\nlocal function TestObject(id, name) -- Constructor\n    local object = {\n        id = id,\n        name = name,\n    }\n    return setmetatable(object, TestClass)\nend\n\nfunction TestClass:__tostring() -- Method\n    return tostring(self.id) .. ' --\u003e ' .. self.name\nend\n\nfunction TestClass:__toBSON() -- Called when object is serialized into BSON\n    return {\n        _id = self.id,\n        binary = mongo.Binary(self.name), -- Store 'name' as BSON Binary for example\n    }\nend\n\n-- A root '__toBSON' metamethod may return a table or BSON document.\n-- A nested '__toBSON' metamethod may return a value, BSON type or BSON document.\n\n-- BSON handler\nlocal function handler(document)\n    local id = document._id\n    local name = document.binary:unpack() -- Restore 'name' from BSON Binary\n    return TestObject(id, name)\nend\n\n-- Note that the same handler is called for each document. Thus, the handler should be able\n-- to differentiate documents based on some internal criteria.\n\nlocal object = TestObject(id, 'abc')\nprint(object)\n\n-- Explicit BSON \u003c-\u003e Lua conversion\nlocal bson = mongo.BSON(object)\nlocal object = bson:value(handler)\nprint(object)\n\n-- Store object\ncollection:insert(object)\n\n-- Restore object\nlocal object = collection:findOne(query2):value(handler)\nprint(object)\n\n-- Iterate objects in a for-loop\nfor object in collection:find(query2):iterator(handler) do\n    print(object)\nend\n```\n\n\nCheck out the [API Reference] for more information.\n\nSee also the [MongoDB Manual] for detailed information about MongoDB commands and CRUD operations.\n\n\n[lua-mongo]: https://github.com/neoxic/lua-mongo\n[luarocks.org]: https://luarocks.org\n[MongoDB C Driver]: http://mongoc.org\n[MongoDB Manual]: https://docs.mongodb.com/manual\n[API Reference]: doc/main.md\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneoxic%2Flua-mongo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneoxic%2Flua-mongo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneoxic%2Flua-mongo/lists"}