nitro 0.2.0 → 0.3.0

data/lib/n/db/README

@@ -1,232 +0,0 @@
-= 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.
-

data/lib/n/db/connection.rb

@@ -1,365 +0,0 @@
-# code: 
-# * George Moschovitis  <gm@navel.gr>
-#
-# (c) 2004 Navel, all rights reserved.
-# $Id: connection.rb 99 2004-10-22 09:50:28Z gmosx $
-
-module N; 
-
-require "n/properties"
-require "n/utils/array"
-require "n/utils/time"
-
-# = DbConnection
-#
-# A Connection to the Database.
-#
-# === design
-#
-# try to make the methods to work with oids.
-# do not implement descendants, use a root id (rid).
-#
-# === todo
-#
-# - support caching
-# - support prepared statements
-# - foreign keys (delete cascade)
-# - keep attribudes as marshaled!!
-#
-# === investigate
-#
-# - should we use retry_query ?
-#
-class DbConnection
-	include N::DbUtils
-	
-	# the actual connection to the database.
-	attr_reader :rdb
-	
-	# If set to true, the select methods deserialize the rows to 
-	# create entities.
-	attr_accessor :deserialize 
-	
-	# Initializate a connection to the database.
-	#
-	def initialize(config)
-		super
-		@deserialize = true
-		$log.debug "Created connection."
-	end
-	
-	# Close the connection to the database.
-	#
-	def close()
-		super
-		$log.debug "Closed connection."
-	end
-	
-	# --------------------------------------------------------------------
-	# Basic methods
-	
-	# Put an entity to the database. Insert if this is a new entity or
-	# update if this is an existing entity.
-	#	
-	def put(entity)
-		if entity.oid
-			# entity allready inserted, update!
-			entity.__db_update(self)
-		else
-			# this is a new entity, insert!
-			entity.__db_insert(self)
-		end
-	end
-	alias_method :<<, :put
-		
-	# Force insertion of managed object.
-	# Typically used for NON-entities.
-	#
-	def insert(obj)
-		obj.__db_insert(self)
-	end
-
-	# Force update of managed object.
-	# Typically used for relations.
-	#
-	def update(obj)
-		obj.__db_update(self)
-	end
-	
-	# Update only specific fields of the entity
-	# 
-	# Input:
-	# sql = the sql code to updated the properties.
-	#
-	def update_properties(update_sql, ent_or_oid, klass = nil)
-		oid = ent_or_oid.to_i()
-		klass = ent_or_oid.class unless klass
-		
-		sql = "UPDATE #{klass::DBTABLE} SET #{update_sql} WHERE oid=#{oid}"
-		retry_query(sql, klass)
-	end
-	alias_method :pupdate, :update_properties
-	
-	# Get an entity from the database.
-	#
-	# COOL: klass can be the class to fetch or the DBTABLE of the class.
-	# thanks to duck typing it works correctly!
-	#
-	# Input:
-	# oid = the entity oid, OR the entity name.
-	#
-	def get(oid, klass)
-		if oid.to_i > 0 # a valid Fixnum ?
-			get_by_oid(oid, klass)
-		else
-			get_by_name(oid, klass)
-		end
-	end
-	
-	# Get an entity by oid.
-	#
-	# COOL: klass can be the class to fetch or the DBTABLE of the class.
-	# thanks to duck typing it works correctly!
-	#
-	def get_by_oid(oid, klass)
-		rows = safe_query("SELECT * FROM #{DbUtils.sql_table(klass)} WHERE oid=#{oid}")
-		return deserialize_one(rows, klass)
-	end
-	
-	# Get an entity by name.
-	#
-	# COOL: klass can be the class to fetch or the DBTABLE of the class.
-	# thanks to duck typing it works correctly!
-	#
-	def get_by_name(name, klass)
-		rows = safe_query("SELECT * FROM #{DbUtils.sql_table(klass)} WHERE name='#{name}'")
-		return deserialize_one(rows, klass)
-	end
-
-	# Get all entities of the given klass.
-	#
-	# COOL: klass can be the class to fetch or the DBTABLE of the class.
-	# thanks to duck typing it works correctly!
-	#
-	# Used to be called 'collect' in an earlier version.
-	#
-	def get_all(klass, extrasql = nil)
-		rows = safe_query("SELECT * FROM #{DbUtils.sql_table(klass)} #{extrasql}")
-		return deserialize_all(rows, klass)
-	end
-	
-	# Delete an entity from the database. Allways perform a deep delete.
-	#
-	# DONT use ::DBTABLE (allow classes as table names).
-	#
-	# Input:
-	#
-	# entity = Entity or oid to delete.
-	# klass = klass of entity (can be nil if an entity is passed)
-	#
-	def delete(entity, klass = nil, cascade = true)
-		if entity.is_a?(Fixnum)
-			oid = entity
-			entity = klass.new
-			entity.oid = oid
-		end
-		
-		transaction {
-			entity.__db_pre_delete(self)
-			exec_clear("DELETE FROM #{DbUtils.sql_table(entity.class)} WHERE oid=#{entity.oid}")
-		}
-	end
-	alias_method :delete!, :delete
-	
-	# Recursively delete all descendants of this entity.
-	# Operates in a transaction.
-	#
-	def delete_descendants(pid, pclass)
-		return unless pclass.respond_to?(:__descendants_classes)
-		
-		for dclass in pclass.__descendants_classes
-			if dclass.include?(N::ParentClass)
-				rs = exec("SELECT oid FROM #{dclass::DBTABLE} WHERE pid=#{pid} AND pclass='#{pclass}'")
-				exec_clear("DELETE FROM #{dclass::DBTABLE} where pid=#{pid} AND pclass='#{pclass}'")
-			else
-				rs = exec("SELECT oid FROM #{dclass::DBTABLE} WHERE pid=#{pid}")
-				exec_clear("DELETE FROM #{dclass::DBTABLE} where pid=#{pid}")			
-			end
-			
-			for tuple in (0...rs.num_tuples)
-				delete_descendants(rs.getvalue(tuple, 0), dclass)
-			end
-			
-			rs.clear()
-		end	
-	end
-	alias_method :delete_descendants!, :delete_descendants
-	
-	# --------------------------------------------------------------------
-	# Graph methods
-	
-	# = child
-	#
-	# Return one children of the parent
-	#
-	def child(entity, klass, extrasql = nil)		
-		pid = entity.to_i()
-		
-		sql = "SELECT * FROM #{klass::DBTABLE}"
-		sql << " WHERE pid=#{pid}" if pid > 0
-		sql << " #{extrasql}" if extrasql
-
-		rows = safe_query(sql)		
-		
-		return deserialize_one(rows, klass)
-	end
-	
-	# = children
-	#
-	# entity = entity or oid.
-	# klass = the class of the children to return.
-	# extrasql = extra sql for limit/order etc.
-	#
-	# === Design:
-	#
-	# If the calculated pid is 0 returns all entities
-	# of the given class. It works like the older collect method.
-	# This make sense, the root of all objects has an oid = 0.
-	# INVESTIGATE: is this a security problem?
-	#
-	# only_oids is not needed use the limit modifiers instead.
-	# if you need oids, use specialized sql. You can use the
-	# extrasql parameter to change the where clause too.
-	#
-	def children(entity, klass, extrasql = nil)		
-		pid = entity.to_i()
-		
-		sql = "SELECT * FROM #{klass::DBTABLE}"
-		sql << " WHERE pid=#{pid}" if pid > 0
-		sql << " #{extrasql}" if extrasql
-
-		rows = safe_query(sql)		
-		
-		return deserialize_all(rows, klass)
-	end
-
-	# = count_children
-	#
-	# Use extrasql to change the where clause.
-	#
-	def count_children(entity, klass, extasql = nil)
-		pid = entity.to_i()
-		
-		sql = "SELECT COUNT(pid) FROM #{klass::DBTABLE}"
-		sql << " WHERE pid=#{pid}" if pid > 0
-
-		if rows = safe_query(sql)
-			return rows[0][0].to_i()
-		end 
-		
-		return 0
-	end
-	
-	# --------------------------------------------------------------------
-	# Transaction methods.
-	
-	def start
-		exec_clear("START TRANSACTION")
-	end
-	
-	def commit
-		exec_clear("COMMIT")
-	end
-	
-	def rollback
-		exec_clear("ROLLBACK")
-	end
-	
-	# Transaction helper
-	#
-	def transaction(&block)
-		begin
-			exec_clear("START TRANSACTION")
-			yield 
-			exec_clear("COMMIT")
-		rescue => ex
-			$log.error "DB Error: ERROR IN TRANSACTION"
-			$log.error "DB Error: #{ex}, #{caller[0]} : #{caller[1]} : #{caller[2]}"
-			exec_clear("ROLLBACK")
-		end
-	end
-	
-	# Useful in transactions
-	#
-	def exec(sql)
-		@rdb.exec(sql)
-	end
-	
-	# Useful in transactions
-	# Exec an sql command and clear the resultset.
-	#
-	def exec_and_clear(sql)
-		rows = @rdb.exec(sql)
-		rows.clear()
-	end
-	alias_method :exec_clear, :exec_and_clear
-		
-	# --------------------------------------------------------------------
-	# Standard SQL methods.
-	
-	# Perform a standard SQL query to the database. Deserializes the
-	# results.
-	#
-	def select(sql, klass, join_fields = nil)
-		rows = safe_query(sql)
-		return deserialize_all(rows, klass, join_fields)
-	end
-	
-	# Optimized for one result.
-	#
-	def select_one(sql, klass, join_fields = nil)
-		rows = safe_query(sql)
-		return deserialize_one(rows, klass, join_fields)
-	end
-	
-	# Perform a standard SQL query to the database. Returns the result 
-	# rows.
-	#
-	def query(sql)
-		return safe_query(sql)
-	end
-	alias_method :sql, :query
-	
-	# Perform a standard SQL query to the database. Used for queries that
-	# return one row (typically with values) ie COUNT, etc.
-	#
-	def query_one(sql)
-		if rows = safe_query(sql)
-			return rows[0]
-		else
-			return nil
-		end
-	end
-	
-	# Count the entities returned by the sql statement.
-	#
-	def count(sql)
-		if rows = safe_query(sql)
-			return rows[0][0].to_i()
-		end 
-		
-		return 0
-	end
-
-	# Match a query, return true if a resultset was found
-	#
-	def match(sql)
-		res = safe_query(sql)
-		return true if res and (res.num_tuples > 0)
-	end
-	alias_method :match?, :match
-
-end
-
-end # module
-