Git Product home page Git Product logo

lua-mongo's Introduction

MongoDB Driver for Lua

lua-mongo is a binding to the MongoDB C Driver for Lua.

  • Unified API for MongoDB commands, CRUD operations and GridFS in the MongoDB C Driver.

  • Support for custom data transformation handlers when converting to/from BSON documents.

  • Transparent conversion from Lua/JSON to BSON for convenience.

  • Automatic conversion of Lua numbers to/from BSON Int32, Int64 and Double types depending on their capacity without precision loss (when Lua allows it). Manual conversion is also available.

Dependencies

  • lua >= 5.1 (or luajit)
  • libmongoc >= 1.5.0
  • libbson >= 1.5.0

Building and installing with LuaRocks

To build and install, run:

luarocks make

To install the latest release using luarocks.org, run:

luarocks install lua-mongo

Building and installing with CMake

To build and install, run:

cmake .
make
make install

To build against a specific Lua version, set the USE_LUA_VERSION variable. For example:

cmake -D USE_LUA_VERSION=5.1 .

or for LuaJIT:

cmake -D USE_LUA_VERSION=jit .

To build in a separate directory, replace . with a path to the source.

To check your build, run:

make test

A local MongoDB server at mongodb://127.0.0.1 will be used for testing by default. Test settings can be configured in test/test.lua.

Getting started

Preparing the playground:

local mongo = require 'mongo'
local client = mongo.Client 'mongodb://127.0.0.1'
local collection = client:getCollection('lua-mongo-test', 'test')
collection:drop() -- Clear collection

-- Common variables
local id = mongo.ObjectID()
local query1 = mongo.BSON '{ "age" : { "$gt" : 25 } }'
local query2 = mongo.BSON { _id = id }

Basic features and operations:

-- Store document
collection:insert { _id = id, name = 'John Smith', age = 50 }

-- Fetch document
local document = collection:findOne(query1):value()
print(document.name)

-- Iterate in a for-loop
for document in collection:find(query1):iterator() do
	print(document.name)
end

-- Implicit Lua/JSON to BSON conversion where BSON is required
collection:insert { integer = 123 }
collection:insert '{ "string" : "abc" }'

-- Use options in queries
print(collection:count({}, { skip = 1, limit = 2 }))

-- Access to BSON where needed
local bson = collection:findOne(query1)
print(bson) -- BSON is implicitly converted to JSON

-- Explicit BSON to Lua conversion
local value = bson:value()
print(value.name)

-- Transparently include BSON documents in other documents
collection:update(query2, { age = 60, backup = bson }) -- Update document
collection:remove(query2) -- Remove document

Bulk write operations can be used to execute multiple insert, update, replace and remove operations together. Executing write operations in batches reduces the number of network round trips increasing write throughput.

local bulk = collection:createBulkOperation()

-- Multiple insertions
bulk:insert { a = 1 }
bulk:insert { b = 2 }
bulk:insert { c = 3 }

-- Multiple modifications
bulk:replaceOne({ a = 1 }, { b = 1 })
bulk:updateMany('{}', '{ "$inc" : { "b" : 2 } }')
bulk:removeOne { c = 3 }

-- Execute all the queued operations
assert(bulk:execute())

The use of __tobson metamethods and BSON handlers gives full control over how Lua values are represented in BSON documents and vice versa. In particular, this API facilitates support for classes (tables with metatables) on their way to and/or from MongoDB.

local SimpleClass = {} -- Class metatable

local function SimpleObject(id, name) -- Constructor
	return setmetatable({
		id = id,
		name = name,
	}, SimpleClass)
end

function SimpleClass:__tostring() -- Method
	return tostring(self.id) .. ' --> ' .. self.name
end

function SimpleClass:__tobson() -- Called when object is packed into BSON
	return {
		_id = self.id,
		binary = mongo.Binary(self.name), -- Store 'name' as BSON Binary for example
	}
end

-- A root '__tobson' metamethod may return a table or BSON document.
-- A nested '__tobson' metamethod may return a Lua value, BSON type or BSON document.

-- BSON handler
local function handler(document)
	return SimpleObject(document._id, (document.binary:unpack()))
end

-- Anything callable can serve as a BSON handler. For instance, it can be a table or userdata
-- with a '__call' metamethod.

-- Note that the same handler will be called for each nested document. Thus, the handler should
-- be able to differentiate documents based on some internal criteria.

local object = SimpleObject(id, 'John Smith')
print(object)

-- Explicit BSON <-> Lua conversion
local bson = mongo.BSON(object)
local object = bson:value(handler)
print(object)

-- Store object
collection:insert(object)

-- Restore object
local object = collection:findOne(query2):value(handler)
print(object)

-- Iterate objects in a for-loop
for object in collection:find(query2):iterator(handler) do
	print(object)
end

Check out the API Reference for more information.

See also the MongoDB Manual for detailed information about MongoDB commands and CRUD operations.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.