= Og 0.16.0 README

Og (ObjectGraph) is a powerfull object-relational mapping library. Og provides 
transparent serialization of object graphs to a RDBMS 
backend. Unlike other similar libraries Og maps standard Ruby
objects to SQL tables and not vice versa. Og provides a meta language
to describe the relations between objects, a flexible	and intuitive api 
for querieng the database, raw access to the SQL language if needed 
(for example to fine tune the automatically generated SQL tables, or 
for custom queries), suports deserialization to Ruby objects or tuples,
automatically generates join tables for many_to_many relations 
and provides a collection of usefull Mixins to synthesize common 
Entities.

Og is a combination of the best features of Active Record and the
former O-R mapping library included in Nitro (NDB). Adapters for
PostgreSQL, MySQL and SQLite are included.

Og is part of the Nitro project, released as a stand-alone library
due to popular demand. You can find the ChangeLog in the Nitro 
distribution (http://nitro.rubyforge.org).


== Features

The library provides the following features:

+ Object-Relational mapping.
+ Absolutely no configuration files.
+ Multiple backend adapters (PostgreSQL, MySQL, SQLite3, Oracle, SqlServer).
+ ActiveRecord-style meta language and db aware methods.
+ Automatially generates join-tables for many_to_many relations.
+ Deserialize sql join queries to Ruby Objects (coming soon).
+ Serialize arbitrary ruby object graphs through YAML.
+ Connection pooling.
+ Thread safety.
+ SQL transactions.
+ Lifecycle event interception and Observers.
+ Transparent support for cascading deletes for all backends.
+ Dynamic db related mixins (Orderable, etc).
+ Hierarchical structures (nested sets, more coming soon).
+ Works safely as part of a distributed application.
+ Automatic Validation/Constraints.
+ Simple and clean implementation.


== Download

The latest version of Og can be found at

* http://nitro.rubyforge.org

Documentation for Og can be found in the distribution. You can find
a nice tutorial at www.rubygarden.com


== Requirements

Og requires the following applications or libraries:

* Ruby 1.8.1 and greater 
	http://www.ruby-lang.org
	Version 1.8.2 is recomended.

* Ruby-psql 
	http://www.postgresql.jp/interfaces/ruby/archive/ruby-postgres-0.7.1.tar.gz
	Ruby interface to the PostgreSQL RDBMS.

* Ruby-mysql 
	http://tmtm.org/ja/ruby/mysql/README_en.html
	Ruby interface to the MySQL RDBMS.
	
* PostgreSQL 
	http://www.postgres.org
	Used for the Database Backend.
	
* MySQL 
	http://www.mysql.org
	Used for the Database Backend.

Please install the required applications and libraries before continuing
with the installation of Og. Only install the libraries needed for
the backend you plan to use.


== Instalation

Og is distributed as a RubyGem. First of all make sure you have
installed RubyGems on your system. Then run the following command:

gem install og

(make sure you have the latest stable versions of Ruby and RubyGems
installed)

Then try to run the examples in the examples directory.

A tar.gz distribution is also available on http://www.rubyforge.com/projects/nitro.


== Support

For any questions regarding Og, feel free to ask on the ruby-talk 
mailing list (which is mirrored to comp.lang.ruby) or contact 
mailto:gm@navel.gr.

An Og specific mailing list is also available. Please subscribe
to nitro-general@rubyforge.com. The homepage for this list
is available here:

http://rubyforge.org/mailman/listinfo/nitro-general


== Licence

Copyright (c) 2004-2005, George 'tml' Moschovitis.
Copyright (c) 2004-2005, Navel Ltd (http://www.navel.gr)

Og (http://www.rubyforge.com/projects/nitro) is copyrighted free 
software created and maintained by George Moschovitis (mailto:gm@navel.gr)
and released under the standard BSD Licence. For details consult
the file LICENCE.

