= n/db README

== Table of Contents

1. Introduction
2. Features
3. Sample Code
4. Technical Information
5. Links
6. Current Version and Status
7. Future
8. Feedback
9. Licence


== Introduction

The aim of this project is to deliver an efficient, yet simple,
Object-Relational Mapper Library. The library manages the
lifecycle of standard Ruby objects. Unlike similar projects, our
approach requires neither xml configuration files (i.e. J2EE), nor
SQL definitions (i.e. ActiveRecord).

By defining the Managed Objects (or Entities) using Ruby, we
leverage Ruby's OOP features to allow for OO definitions of DataBase
schemas. A simple meta-language is provided to allow fine-tuning
of the generated SQL code.

This library is designed to be integrated in  a Web Application
Framework. This Framework will be released on a later day.


== Features

The library provides the following features:

+ Object-Relational mapping
+ Deserialize to Ruby Objects or ResultSets
+ Deserialize sql join queries to Ruby Objects
+ Connection pooling
+ Thread safety
+ SQL transactions
+ Callbacks
+ Simple support for cascading deletes


== Sample Code

require "n/db"

# initialize the DB interface
$db = N::Db.new(
:address => "localhost",
:database => "test",
:user => "postgres",
:password => "mypassword",
:connection_count => 20
)

# create a managed object

class MyObject
include N::Entity
manage {
prop String, :name
prop [Fixnum, "smallint default 1"], :level; sql_index :level
}
# non serialized attributes
attr_accessor value
end

class AnotherObject < MyObject
manage {
prop Time, :create_time
}

def initialize
@create_time = Time.now
super
end
end

obj = AnotherObject.new
obj.name = "gmosx"

# insert into db
$db << obj

obj.name = "drak"

# update
$db << obj

# get object id allocated when inserting
oid = obj.oid

# lookup
obj = $db.get(oid, AnotherObject)

# multiple commands

$db.open { |db|
obj = db.get(oid, AnotherObject)
db.delete(obj)
db.select("SELECT * FROM #{AnotherObject::DBTABLE} WHERE oid=1")
}

# graph like objects

class Child
include N::Entity
include N::Child
manage {
prop Time, :create_time
}
end

child = Child.new
child.set_parent(obj)

$db << child

# get children of class Child

$db.children(obj, Child, "ORDER BY create_time")

# sql transactions

$db.transaction {
....
}

== Technical Information

=== Installation

Just uncompress the distribution and add the 'n' directory to
the Ruby path.

tar xvfz ndb-x.x.tar.gz
cd ndb
ruby n/.tc-db.rb

=== How the package is organized:

doc/*:
RDOC generated documentation.

n/db.rb:
The main n/db file.

n/db/*:
The db related files.

n/utils/*:
Various utility files.

=== Testing:

Unit Test files start with the .tc- prefix, i.e. they are hidden
by default (Unix). You can run the db test unit as follows:

ruby n/.tc-db.rb

Before running this test unit, make sure tha the postgreSQL server
is running, and the 'test' database is created.


== Links

* http://www.navel.gr, Navel
* http://www.navel.gr/open-source, Project Home Page


== Current Version and Status

Version 0.2 was released on 07-10-2004. The sofware is actually usable
but not tested in a production environment. Comments from the Ruby
community are critical in order to fix possible bugs and improve the
API. Suggestions for missing features are also welcome. This version
only supports the Postgres Database.


== Future

* Support multiple DataBase backends (Postgres, MySQL, ...)
* Support prepared statements (pgsql)
* Support stored procedures (pgsql)
* Support caching
* Deserialize to OpenStruct
* Better documentation
* Code cleanup, refactoring


== Feedback

If you would like to report a bug, suggest a method for inclusion, or
make
some other suggestion (documentation, package layout, etc.), please
send
an email to ndb-feedback / navel.gr


== Licence

Copyright (c) 2004 Navel, all rights reserved. http://www.navel.gr

n/db (http://www.navel.gr/open-source) is copyrighted free software
created and maintained by George Moschovitis (mailto:gm / navel.gr)
and released under the same license as Ruby.

Standard disclaimer:
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE.