readme

About: hamsterdb is a database engine written in ANSI C. It supports a B+Tree index structure, uses

hamsterdb 0.4.4                                Sun Jul 15 21:43:20 UTC 2007
(C) Christoph Rupp, [e-mail]; http://www.hamsterdb.com

This is the README file of hamsterdb.

Contents:

1. About

hamsterdb is a database engine written in ANSI C. It supports a B+Tree index
structure, uses memory mapped I/O (if available), supports cursors and
variable length keys and can create in-memory databases.

Although no bugs are known, this release is marked "unstable", because the
database file format is still subject to change. The first stable release 
will be version 1.0. 

2. Changes

This release comes with loads of changes and new features.

New Features
* "Environments": hamsterdb can now handle multiple files per database 
    (default: up to 32). New functions were added to ham/hamsterdb.h.
    A new sample (env1.c) demonstrates the new functions, and the
    tutorial was updated.
* The Visual Studio 2005 Solution now supports 64bit builds
* hamsterdb was ported to Windows CE - a Solution file is in the
    wince subdirectory
* New flag HAM_LOCK_EXCLUSIVE places an exclusive file lock on the database

Bugfixes
* The flag HAM_DISABLE_MMAP was ignored - fixed
* Freelist pages were sometimes not marked as 'dirty' and not flushed to disk
    - fixed
* The freelist pages were cached, but never flushed, and therefore 
    polluted the cache - fixed
* The flag HAM_DISABLE_FREELIST_FLUSH was ignored - fixed
* Some deleted pages were not added to the freelist - fixed

Other Changes
* An API change: ham_open_ex and ham_create_ex now expect an array of
    ham_parameter_t elements
* The type of ham_key_t::size (declared in hamsterdb.h) is now ham_u16_t,
    and no longer ham_size_t
* Performance improvements in the handling and caching of extended keys
* More unittests were added

To see a list of all changes, look in the file CHANGELOG.

3. Roadmap

The next releases will offer one of the following new features:
- support for logical record numbers
- duplicate items
- command line tools for recovery, dump and statistics
- a C++ wrapper class

4. Features

- Very fast sorted B+Tree with variable length keys
- Can run as an in-memory-database
- Fast Database cursors 
- Configurable page size, cache size and index key size
- Portable ANSI-C implementation
- Runs on Linux, Unices, Microsoft Windows
- Uses memory mapped I/O for fast disk access (but falls back to read/write if
  mmap is not available)
- Uses 64bit file pointers and supports huge files (>2 GB)
- Endian-agnostic database files work on little-endian and big-endian platforms
- Easy to use and well-documented
- Supports rudimentary live-reorganization by automatically
    merging freelist entries
- Supports multiple databases per file ("Database Environments")
- Open source and released under the GPL 2.0

5. Known Issues/Bugs

None so far

6. Compiling 

6.1 Linux and Cygwin/Win32

To compile hamsterdb, run ./configure, make, make install.

Run `./configure --help' for more options (i.e. static/dynamic library, 
build with debugging symbols etc).

6.2 Microsoft Visual Studio 8

A Solution file is provided for Microsoft Visual C++ 2005:
win32/hamsterdb/hamsterdb.sln. It compiles a static and a dynamic library. 
The static library is built in '/win32/hamsterdb/release/libhamsterdb.lib', 
the dynamic library is in '/win32/hamsterdb/release/hamsterdb.dll'. An import
library is also provided. All libraries can be downloaded separately from 
the hamsterdb webpage.

To download Microsoft Visual C++ 2005 Express Edition for free, go to
http://msdn.microsoft.com/vstudio/express/visualc/default.aspx.

7. Testing and Example Code

Make automatically compiles a simple example program in the directory
'/samples'. To see hamsterdb in action, just run '/samples/db1' (or 
'/win32/hamsterdb/release/db1.exe' on Win32 platforms).

8. API Documentation

API documentation is not yet available. The header files in '/include/ham' are 
commented, though. The next release will provide a doxygen script to 
generate the documentation from the header files.  

9. Other Ways to Compile hamsterdb

If you want to compile hamsterdb without using the provided ./configure
environment, you have to set some preprocessor macros:

WIN32                   Build for Win32 platform
DEBUG                   enable debugging output and diagnostic checks (slow!)
HAM_LITTLE_ENDIAN       compile for little endian machines (i.e. x86)
HAM_BIG_ENDIAN          compile for big endian machines (most other
                            architectures)
HAM_32BIT               compile for 32bit
HAM_64BIT               compile for 64bit
HAM_ENABLE_INTERNAL     enable internal functions (declared in
                            include/ham/hamsterdb_int.h)

Also, if you compile for windows, you have to compile the file src/os_win32.c,
and ignore the file src/os_posix.c. Vice versa on non-Windows platforms.

10. Porting hamsterdb

Porting hamsterdb shouldn't be too difficult. All operating system dependend
functions are declared in 'src/os.h' and defined in 'src/os_win32.c' or 
'src/os_posix.c'. 
Other compiler- and OS-specific macros are in 'include/ham/types.h'. 
Most likely, these are the only files which have to be touched. Also see item 
9) for important macros.