nitro 0.1.2

data/lib/n/db/README

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

@@ -0,0 +1,369 @@
+# = Database Connection
+#
+# Encapsulates a database connection.
+#
+# === 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 ?
+#
+# code: 
+# George Moschovitis  <gm@navel.gr>
+#
+# (c) 2004 Navel, all rights reserved.
+# $Id: connection.rb 79 2004-10-18 16:38:19Z gmosx $
+
+module N; 
+
+require "n/properties"
+require "n/utils/array"
+require "n/utils/time"
+
+# = DbConnection
+#
+# A Connection to the Database.
+#
+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
+