Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

sqdb

Simple key-value store on top of SQLite. Experimental, API subject to change.

Overview

sqdb is a simple key-value store implemented on top of SQLite using the sql-de-lite egg. It provides the usual fetch, store and modify operations. It also supports ACID semantics, by virtue of SQLite.

Keys are strings or symbols. Values may be strings, exact integers, inexact integers, and blobs.

  1. Outdated egg!
  2. sqdb
  3. Overview
  4. API
    1. Open and close
    2. Read, modify, and write
    3. Transactions
    4. Miscellaneous
  5. Implementation notes
  6. Bugs and limitations
  7. About this egg
    1. Author
    2. Version history
    3. License

API

Open and close

[procedure] (open-database filename)

Opens database with path filename and returns an sqdb database object. The database will be created if it does not exist.

[procedure] (close-database db)

Closes sqdb database db.

[procedure] (call-with-database filename proc)

Opens sqdb database filename and calls (proc db). The database will be closed when proc returns or raises an exception.

[procedure] (sqdb-handle db)

Return the underlying sql-de-lite database handle for db.

Read, modify, and write

[procedure] (fetch db key)

Fetch value of key from database db. key may be a string or symbol.

Returns a string, exact or inexact integer, or blob depending on the type of the stored value. If the key did not exist, returns #f.

[procedure] (store db key val)

Stores key in database db with value val. If key already exists, its value is overwritten; otherwise, a new key is created.

key may be a string or symbol. val may be a string, exact or inexact integer, or blob; it will be stored and fetched as that type.

The return value is unspecified.

[procedure] (add db key val)
[procedure] (add* db key val)

add is like store, but only makes a change if the key did not exist. It returns #f if the key did exist, and #t if it did not.

add* is like add, but raises an exception if the key already exists.

[procedure] (exists? db key)

Test if key exists in db and returns a boolean value.

[procedure] (incr db key [n])

Atomically increment the value associated with key by n. n may be an integer or a floating point value, and defaults to 1.

If the value is a string, it is converted to a number if possible, and the new value will be a number. If the conversion fails, it is considered to be zero, so the resulting value will be the number n.

Returns #t if the key existed and #f if it did not.

[procedure] (decr db key [n])

Equivalent to (incr db key (- n)).

[procedure] (update db key proc)

Updates the value of key by fetching the current value of key, calling (proc val) to get an updated value, and storing that into the database. val will be #f if the key did not exist.

This operation is implemented using an IMMEDIATE transaction, and is atomic as long as you always use update elsewhere (or an IMMEDIATE or EXCLUSIVE transaction) when doing a read-modify-write on this key.

Note that the incr operation could be implemented in a much less efficient way using update:

(update db key (lambda (x) (add1 (or x 0))))
;; Less efficient than:
(add db k 0)
(incr db k)
[procedure] (delete db key)

Deletes key from db. Returns #t if the key existed (and was deleted), or #f if it did not exist.

Transactions

[procedure] (with-transaction db thunk #!optional (type deferred))

Executes thunk inside an atomic transaction. If thunk raises an exception or returns #f, the transaction is rolled back. Otherwise it is committed when thunk exits.

Warning: transactions may not be nested. An error will occur if you try.

type may be

deferred
Everyone can write until our first read or write; everyone can read until our first write.
immediate
No one else can write, but everyone can read until our first write.
exclusive
No one else can read or write.
[procedure] (begin-transaction db thunk #!optional (type deferred))

Begin an atomic transaction. See with-transaction for the meaning of type.

[procedure] (commit db)

Commit the current transaction to disk oxide.

[procedure] (rollback db)

Rollback the current transaction.

Miscellaneous

[procedure] (set-busy-timeout! db ms)

Set a timeout of ms milliseconds for operations that occur when the database is locked. If ms is #f or 0, the operation times out immediately.

You must set the timeout separately for each database connection and it can be changed at any time after the database is open. The default is #f.

Implementation notes

The key-value store is implemented as a table called sqdb_ht_1 inside an SQLite database. The table is created if necessary when the database file is opened. The store can therefore be used with an existing SQLite database without interfering with other tables.

The db object is currently a raw sqlite-database object from sql-de-lite and consequently you can execute statements, etc. by using that egg. The representation of the object may change so you should always use sqdb-handle to obtain the SQLite database handle.

Bugs and limitations

About this egg

Author

Jim Ursetto

Version history
0.0.2
Permit storage and retrieval of numbers and blobs in addition to strings
0.0.1
Initial release

License

Copyright (c) 2011, Ursetto Consulting, Inc. MIT license.