A lua driver for mongodb
Lua
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