lua-tinycdb

A binding to the tinycdb library by Michael Tokarev, which is a public domain implementation of Daniel J. Bernstein's Constant Database (cdb). A cdb is a key-value store (much like BDB/gdbm), but it cannot be updated at runtime (only rebuilt). Reading is very fast, and rebuilding is done atomically by building the new database and then renaming. lua-tinycdb includes the tinycdb source so there are no external dependencies.

Features

I include below the list some of the features of the cdb database structure, stolen (and slightly modified) from D.J. Bernstein's cdb page:

• Fast lookups: A successful lookup in a large database normally takes just two disk accesses. An unsuccessful lookup takes only one.
• Low overhead: A database uses 2048 bytes, plus 24 bytes per record, plus the space for keys and data.
• Fast atomic database replacement

Project links

• Download
• Documentation
• Bugs

Release history

• 2008-01-23 - lua-tinycdb-0.1 (first public release)

See also

• tinycdb homepage
• cdb homepage (DJ Bernstein's original implementation)
• cdb format specification
• luacdb Taj Khattra's binding to the original cdb library. lua-tinycdb was developed independently.

Documentation

Until I've written some more detailed documentation, I advise you read the annotated example below which makes use of every exported method. If it doesn't make sense, please contact me.

#! /usr/bin/env lua

-- lua-tinycdb does not assign to any global variables, so name it yourself
cdb = require("cdb")

-- make new cdb, creating a file called example.cdb.tmp that will be renamed 
-- to example.cdb when finished. Due to the semantics of rename, this will 
-- atomically replace example.cdb with the newly built database
maker = assert(cdb.make("example.cdb", "example.cdb.tmp"))

maker:add("key", "value")
maker:add("foo", "bar")
-- note it is possible to have multiple values for the same key
maker:add("foo", "baz")
maker:add("baz", "qux")

-- a 3rd argument can be given to maker:add() that controls the behaviour when 
-- adding a key that already exists:
--  * "add": the default. No duplicate checking will be performed.
--
--  * "replace": If the key already exists, it will be removed from the  
--  database before adding new key,value pair. This requires moving data in 
--  the file, and can be quite slow if the file is large. All matching old 
--  records will be removed this way.  
--
--  * "replace0": If the key already exists and it isn't the last record in 
--  the file, old record will be zeroed out before adding new key,value   
--  pair. This is alot faster than CDB_PUT_REPLACE, but some extra data will  
--  still be present in the file. The data -- old record -- will not be  
--  accessible by normal searches, but will appear in sequential database 
--  traversal. 
--
--  * "insert": add key,value pair only if such a key does not exists in the 
--  database.

-- renames example.cdb.tmp to example.cdb and closes file
assert(maker:finish())

-- open our new database
db = cdb.open("example.cdb")

local var = db:get("key") -- "value"
local var2 = db:get("baz") -- "qux"
local var3 = db:get("foo") -- "bar", as get() returns the first value added

-- outputs:
--
-- key  value
-- foo  bar
-- foo  baz
-- baz  qux
for k, v in db:iter() do
  print(k, v)
end

-- find_all returns a table of all values for the given key
local t = db:find_all("foo") -- t = { "bar", "baz" }

db:close()

License

lua-tinycdb is distributed under the MIT license.

  Copyright (c) 2008 A.S. Bradbury

  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation
  files (the "Software"), to deal in the Software without
  restriction, including without limitation the rights to use,
  copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the
  Software is furnished to do so, subject to the following
  conditions:

  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  OTHER DEALINGS IN THE SOFTWARE.
  

Contact

Author: A.S. Bradbury
Email: asb@asbradbury.org
Homepage: http://asbradbury.org