A lua driver for mongodb
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
mongol
test
Makefile
Readme.md

Readme.md

Mongol - Lua Mongodb Driver

Written by daurnimator

License is MIT/X11

Dependancies

lua 5.1

luasocket

Installation

Copy the mongol directory to somewhere lua will find it (eg; for linux the standard location is /usr/share/lua/5.1/ )

or more simply; use the provided make file:

	make install

Usage

Functions will generally raise errors if something unexpected happens

Requring the module will return a function that connects to mongod: it takes a host (default localhost) and a port (default 27017); it returns a connection object.

	mongol = require "mongol"
	conn = mongol ( ) -- Connect to localhost:27017

###Connection objects have server wide methods.

####conn:cmd ( database_name , query , [collection] ) Returns the document or nil , errmsg , return_document , responseFlags on failure; where responseFlags is a table containing the fields CursorNotFound, QueryFailure, ShardConfigStale, AwaitCapable.

####bool , hosts = conn:ismaster ( ) Returns a boolean indicating if this is the master server and a table of other hosts this server is replicating with.

####newconn = conn:getprimary ( [already_checked] ) Returns a new connection object that is connected to the primary server or nil , errmsg on failure.

The returned connection object may be this connection object itself.

####databases = conn:databases ( ) Returns a table describing databases on the server.

	databases.name: string
	databases.empty: boolean
	databases.sizeOnDisk: number

####conn:shutdown ( ) Shutsdown the server. Returns nothing.

####db = conn:new_db_handle ( database_name ) Returns a database object

###Database objects perform actions on a database

####db:list ( ) ####db:dropDatabase ( ) ####db:add_user ( username , password ) ####db:auth ( username , password ) ####db:count ( collection , query ) ####db:drop ( collection ) ####db:update ( collection , selector , update , upsert , multiupdate ) ####db:insert ( collection , docs , continue_on_error ) ####db:delete ( collection , selector , SingleRemove ) ####db:kill_cursors ( collection , cursorIDs ) ####db:query ( collection , query , returnfields , numberToSkip , numberToReturn , options ) ####db:getmore ( collection , cursorID , [numberToReturn] , [offset_i] )

  • cursorID is an 8 byte string representing the cursor to getmore on
  • numberToReturn is the number of results to return, defaults to -1
  • offset_i is the number to start numbering the returned table from, defaults to 1

####cursor = db:find ( collection , query , returnfields )

###Cursor objects ####index , item = cursor:next ( ) Returns the next item and advances the cursor

####cursor:pairs ( ) A handy wrapper around cursor:next() that works in a generic for loop: for index , item in cursor:pairs() do

Notes

  • collections are string containing any value except "\0"
  • database_name are strings containing any character except "." and "\0"

TL;DR

	local mongol = require "mongol"
	local conn = mongol ( ) -- Connect to localhost:27017
	local db = conn:new_db_handle ( "mydatabase" )

	assert ( db:auth ( "username" , "password" ) )

	for i , v in db:find ( "mycollection" , { foo = "bar" } ):pairs() do
		print ( v )
	end