Path: fsdb.txt
Modified: Sun Mar 02 18:19:59 PST 2003

What is FSDB?

FSDB is a file system data base. FSDB provides a thread-safe, process-safe Database class which uses the native file system as its back end and allows multiple file formats and serialization methods. Users access objects in terms of their paths relative to the base directory of the database. It's very light weight (the state of a Database is essentially just a path string, and code size is very small, under 1K lines, all ruby).

FSDB stores bundles of ruby objects at nodes in the file system. Each bundle is saved and restored as a whole, so internal references persist as usual. These bundles are the atoms of transactions. References between bundles are handled through path strings. The format of each bundle on disk can vary; format classes for plain text strings, marshalled data, and yaml data are included, but FSDB can easily be extended to recognize other formats, both binary and text. FSDB treats directories as collections and provides directory iterator methods.

FSDB has been stress tested on Linux (single and dual cpu) and on Solaris (dual and quad cpu) with ruby-1.7.3 and ruby-1.6.7. A typical stress test involves 10 processes, each with 10 threads, doing millions of transactions on a small set of objects. Alas, it's not tested on Windows yet.

FSDB does not yet have any indexing or querying mechanisms, and is probably missing many other useful database features, so it is not a general replacement for RDBs or OODBs. However, if you are looking for a concurrent object store with reasonable performance and better granularity than PStore, in pure Ruby, with a Ruby license, take a look at FSDB. Also, if you are looking for an easy way of making an existing file tree look like a database, especially if it has heterogeneous file formats, FSDB might be useful.


  require 'fsdb'

  db = FSDB::Database.new('/tmp/my-data')
  db['recent-movies/myself'] = ["LOTR II", "Austin Powers"]
  puts db['recent-movies/myself'][0]              # ==> "LOTR II"

  db.edit 'recent-movies/myself' do |list|
    list << "A la recherche du temps perdu"

Path names

Keys in the database are path strings, which are simply strings in the usual forward-slash delimited format, relative to the database's directory. There are some points to be aware of when using them to refer to database objects.


FSDB transactions are thread-safe and process-safe. They can be nested for larger-grained transactions; it is the user's responsibility to avoid deadlock.

FSDB is ACID (atomic/consistent/isolated/durable) to the extent that the underlying file system is. For instance, when an object is written, nothing persistent is changed until the final system call to write the data to the OS's buffers. If there is an interruption (e.g., a power failure) while the OS flushes those buffers to disk, data will not be consistent. If this bothers you, you may want to use a journaling file system. FSDB does not need to do its own journaling because of the availability of good journaling file systems.

There are two kinds of transactions:

Guarding against concurrency problems



FSDB is not very fast. It's useful more for its safety, flexibility, and ease of use.


To do


Stability, Security, and Error Checking



fsdb 0.1

The current version of this software can be found at redshift.sourceforge.net/fsdb.


This software is distributed under the Ruby license. See www.ruby-lang.org.


Joel VanderWerf, vjoel@users.sourceforge.net