= n/db README

== Table of Contents

1. Introduction
2. Features
3. Sample Code
4. Technical Information
5. Links
6. Current Version and Status
7. Feedback
8. 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
+ Serialize arbitrary ruby object graphs through Marshal
+ Connection pooling
+ Thread safety
+ SQL transactions
+ Callbacks
+ Simple support for cascading deletes
+ Hierarchical structures (preorder traversal, materialized paths)
+ Works safely as part of distributed application.
+ Simple implementation < 10k lines of code.

== 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 {
	...
}

# Lets say you have changed the definition of a managed object
# (for example you have added a new prop_accessor, and want to 
# automatically update the database schema: 
# 

$db.alter_table(MyObject)


== 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:

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.3 was released on 15-10-2004. The source is cleaned up and 
the API refined. Added preliminary support for multiple backends (the
included MySQL backend is not completed). Added support for 
marshaled fields. Available as a RubyGem too. 

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.

=== Contributors

* George Moschovitis  <gm@navel.gr>: design, lead developer.

=== 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
* Release as Gem, RPAbase


== 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.