ramen 0.4.0

data/readme.txt

@@ -0,0 +1,159 @@
+= Ramen -- Making your database edible
+  by Gregory N. Houston
+  
+Ramen creates an object model from your database's metadata (Schema, Tables, 
+Columns, Indexes, Keys). This metadata is sometimes called 
+_data_ _dictionary_, _system_ _catalog_, or _INFORMATION_ _SCHEMA_.
+
+Version:: 0.4.0 SQL Server 2005 and MySQL 5.0.
+
+It is easy to support additional database engines.  All that is needed are 
+the SQL statements to query the metadata, and maybe a few tweaks to the
+unit tests.  Please contact the author if you want help getting Ramen to
+support another database.
+
+== Links:
+
+Start Here:: http://ramen.rubyforge.org
+
+Project:: http://rubyforge.org/projects/ramen
+Documents:: http://ramen.rubyforge.org
+RubyGems:: Install with: <b>gem install ramen</b>
+Download:: Download from RubyForge at http://rubyforge.org/projects/ramen/
+Authors Blog::   http://ghouston.blogspot.com
+Browse Source:: link:rcov/index.html
+
+== LICENSE:
+
+(The MIT License + Free Software Foundation Advertising Prohibition)
+
+Copyright (c) 2007 Gregory N. Houston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Except as contained in this notice, the name(s) of the above copyright holders
+shall not be used in advertising or otherwise to promote the sale, use or other
+dealings in this Software without prior written authorization.
+
+== Examples:
+
+== Design:
+
+Ramen loads the INFORMATION SCHEMA from the database into Ruby objects
+using the RowDataGateway pattern (Martin Fowler. Patterns of Enterprise
+Application Architecture. Addison Wesley Longman, Reading, MA, 2003).  The
+resulting structure is:
+
+link:doc_resources/MetaData_Class_Diagram.png
+
+Thus if a client wishes to get the Employee table in the HumanResources schema:
+
+  require 'ramen'
+  db = Ramen.create( :connection => DBI.connect( ...database connection... ))
+  employee_table = db.schema['HumanResources'].table['Employee']
+
+Ramen exposes each column in the INFORMATION SCHEMA as attributes on the Ruby
+object.  For example, on SQL 2005 a table in sys.table has the following
+meta-data:
+
+ select * from sys.tables where name ='Employee'
+
+ ...type_desc   create_date             modify_date             is_ms_shipped ...
+ ...----------- ----------------------- ----------------------- ------------- ...
+ ...USER_TABLE  2005-10-14 01:58:32.663 2005-10-14 01:59:52.287 0             ...
+
+Ramen's RowDataGateway maps these columns directly to attributes on the table
+object in ruby.
+
+ employee_table.type_desc        #=> "USER_TABLE"
+ employee_table.create_date      #=> #<DBI::Timestamp...>
+ employee_table.is_ms_shipped    #=> 0
+
+The attributes are database engine specific.  On different database engines 
+(Sql 2005, MySQL, etc) the objects will contain the data columns
+returned by the engine's INFORMATION SCHEMA. In the near future, Ramen will
+provide a Facade mapping engine specific attributes to generic attributes.  For
+example in SQL 2005 the Index attribute .is_unique and MySQL's .non_unique
+attributes would be mapped to .unique?.
+
+Ramen does not "Rubify" the database names into Ruby names.  This is important
+since Ramen's focus is the database, not Ruby.  The only restriction that Ramen
+imposes is the "name" and "object_id" or "id" columns need renaming to names
+like "schema_name" or "table_id" in the records returned in queries.  This
+avoids clashing with attributes that already exist on Ruby objects, and
+it makes it clear which ID or NAME is being returned.
+
+Since different databases use
+Internally Ramen collects objects into a specialized Hash that can access
+objects by either name or id.  For example, when getting a table a client
+can use either table_name or table_id.
+
+  hr_schema.table['Employee']
+  hr_schema.table[12345]
+
+Ramen was developed to support the Noodle project (also on Rubyforge).  As
+Noodle is developed, Ramen's API will improve.
+
+== Database Support:
+
+Currently, Ramen only supports SQL Server 2005 and MySQL 5.0.  However, Ramen was developed
+with support for other databases in mind.  As such, to support other databases
+two changes are needed.  First, the queries for the INFORMATION SCHEMA meta-data
+would need writting.  See the class Ramen::Sql2005 for the queries that would need
+developing for another database.  Second, the unit tests will need tweaking to 
+work with the new database engine (see test/sql2005_create_test_db.sql).
+
+== Multiple Databases:
+
+Ramen can create and use multiple instances of Ramen::Database at the same time.
+This allow connecting to multiple databases at the same time.
+
+== Connections:
+
+Ramen::Database#new and Ramen.create accept a connection parameter.  This
+connection is only used during the call of the method.  Ramen will not
+hold on to connections.  After the method returns, it is safe to use the
+connection outside Ramen or to close it.
+
+== Threading:
+
+Ramen was developed to support Noodle and Unit Testing in a single-threaded
+fashion.  Thus Ramen does not take extra steps to make itself threadsafe.  The
+only section of Ramen's code that updates values is the creation process.  
+Once the database meta-data is loaded, Ramen's object are read-only 
+(not enforced, but as long as clients only use methods documented as 
+"for external use" it is safe).  It is possible to use Ramen in a multi-threaded
+system if Ramen::Database#new is treated as a critical section.
+
+== Dependencies:
+
+Ramen's connection must quack like DBI.
+
+Ramen's logger must quack like Ramen::DefaultLogger which is a subset of Log4r.
+So clients may use Ramen directly with Log4r.
+
+== Performance:
+
+Ramen was optimized for Unit Testing.  It assumes that most clients will
+request meta-data for at least 25% of the tables in the database.  To optimize
+for this situation, Ramen found loading the entire database's meta-data upon
+creation of the Database object to have the best performance.  In development
+tests on an average PC running Ramen against a remote SQL 2005 Server database on
+the same network segment that contained 322 tables, 3281 columns, 192 foreign
+keys, the queries and creation of Ramen's objects took less than one second.

data/test/config/config.yml

@@ -0,0 +1,19 @@
+## config.yml - Configuration for running the tests
+##              This is an example file, which contains the
+##              default settings.
+##              Overridden by defining a config_local.yml
+##
+## The top element is an environment name, which will be printed in
+## error messages when a test against the environment fails
+## 
+## Each environment needs an 'engine' and 'connection'
+## engine     = module name that contains engine's specific code.
+## connection = DBI connection string, to connect to test database.
+
+sqlserver2005:
+    engine: Ramen::Sql2005
+    connection: DBI:ODBC:ramen_test_sql2005
+
+mysql50:
+    engine: Ramen::MySql500
+    connection: DBI:ODBC:ramen_test_mysql

data/test/helper.rb

@@ -0,0 +1,18 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+
+module Ramen
+  class Helper
+    def Helper.load_config
+      begin
+        return YAML.load_file( './test/config/config_local.yml' )
+      rescue Errno::ENOENT
+        return YAML.load_file( './test/config/config.yml' )
+      end
+      raise "Unable to load configuration. #{__FILE__} #{__LINE__}"
+    end
+  end
+end
+

data/test/mysql_create_test_db.sql

@@ -0,0 +1,47 @@
+DROP DATABASE IF EXISTS RamenTestSchema;
+DROP DATABASE IF EXISTS RamenTestSchema2;
+
+CREATE DATABASE RamenTestSchema;
+CREATE DATABASE RamenTestSchema2;
+
+CREATE TABLE RamenTestSchema.Employee (
+  EmployeeID INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+  LoginID VARCHAR(256) NOT NULL,
+  ManagerID INTEGER UNSIGNED,
+  PRIMARY KEY (EmployeeID)
+);
+ALTER TABLE RamenTestSchema.Employee ADD UNIQUE INDEX IX_Employee_LoginID USING BTREE(LoginID);
+ALTER TABLE RamenTestSchema.Employee ADD INDEX IX_Employee_ManagerID USING BTREE(ManagerID);
+ALTER TABLE RamenTestSchema.Employee
+  ADD CONSTRAINT FK_Employee_Employee_ManagerID
+  FOREIGN KEY FK_Employee_Employee_ManagerID (ManagerID)
+    REFERENCES Employee (EmployeeID)
+    ON DELETE RESTRICT
+    ON UPDATE RESTRICT;
+
+CREATE TABLE RamenTestSchema.EmployeeAddress (
+  EmployeeID INTEGER UNSIGNED NOT NULL,
+  AddressID INTEGER UNSIGNED NOT NULL,
+  PRIMARY KEY (EmployeeID, AddressID)
+);
+ALTER TABLE RamenTestSchema.EmployeeAddress
+  ADD CONSTRAINT FK_EmployeeAddress_Employee
+  FOREIGN KEY FK_EmployeeAddress_Employee (EmployeeID)
+    REFERENCES Employee (EmployeeID)
+    ON DELETE RESTRICT
+    ON UPDATE RESTRICT;
+
+CREATE TABLE RamenTestSchema.Bug1 (
+  PkID INTEGER UNSIGNED NOT NULL,
+  PRIMARY KEY (PkID)
+);
+ALTER TABLE RamenTestSchema.Bug1
+  ADD CONSTRAINT FK_Bug1_Employee
+  FOREIGN KEY FK_Bug1_Employee (PkID)
+    REFERENCES Employee (EmployeeID)
+    ON DELETE RESTRICT
+    ON UPDATE RESTRICT;
+/*
+# Note, MySQL cant have a foreign key that spans schemas (databases).
+#       Some databases dont have this restriction.
+*/

data/test/sql2005_create_test_db.sql

@@ -0,0 +1,45 @@
+/*
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+*/
+
+USE MASTER
+GO
+
+IF  EXISTS (SELECT name FROM sys.databases WHERE name = N'RamenTest')
+DROP DATABASE RamenTest
+GO
+
+CREATE DATABASE RamenTest
+GO
+
+USE RamenTest
+GO
+
+CREATE SCHEMA RamenTestSchema2
+    CREATE TABLE Bug1 (PkID int
+        CONSTRAINT PK_Bug1_PkID PRIMARY KEY CLUSTERED (PkID ASC))
+GO
+
+CREATE SCHEMA RamenTestSchema
+    CREATE TABLE Employee (EmployeeID int, LoginID nvarchar(256), ManagerID int
+        CONSTRAINT PK_Employee_EmployeeID PRIMARY KEY CLUSTERED (EmployeeID ASC))
+    CREATE TABLE EmployeeAddress (EmployeeID int, AddressID int
+        CONSTRAINT PK_EmployeeAddress_EmployeeID_AddressID PRIMARY KEY CLUSTERED (EmployeeID ASC, AddressID ASC))
+GO
+
+CREATE UNIQUE NONCLUSTERED INDEX IX_Employee_LoginID ON RamenTestSchema.Employee (LoginID ASC)
+CREATE NONCLUSTERED INDEX IX_Employee_ManagerID ON RamenTestSchema.Employee (ManagerID ASC)
+ALTER TABLE RamenTestSchema.Employee ADD CONSTRAINT FK_Employee_Employee_ManagerID FOREIGN KEY(ManagerID) REFERENCES RamenTestSchema.Employee (EmployeeID)
+ALTER TABLE RamenTestSchema.Employee CHECK CONSTRAINT FK_Employee_Employee_ManagerID
+ALTER TABLE RamenTestSchema.EmployeeAddress ADD CONSTRAINT FK_EmployeeAddress_Employee FOREIGN KEY(EmployeeID) REFERENCES RamenTestSchema.Employee (EmployeeID)
+ALTER TABLE RamenTestSchema.EmployeeAddress CHECK CONSTRAINT FK_EmployeeAddress_Employee
+GO
+
+ALTER TABLE RamenTestSchema2.Bug1 ADD CONSTRAINT FK_Bug1_Employee FOREIGN KEY(PkID) REFERENCES RamenTestSchema.Employee (EmployeeID)
+GO
+
+--CREATE SCHEMA Person
+--GO

data/test/test_bugs.rb

@@ -0,0 +1,32 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+require 'lib/ramen'
+
+=begin
+Detected: 2008-02-18
+Database Engine: Sql2005
+Bug:  Foreign Key Column @referenced_column fails if the ref column name is
+different than the column name in the local table.
+
+To reproduce:
+RamenTestSchema2.Bug1 with a column PkID which references 
+RamenTestSchema.Employee (EmployeeID).
+
+Other problems:  Inspecting the code, found that Foreign Key Column doesn't
+have an attribute for referenced_table_schema.  What if the reference was to
+a different schema? (Note, MySQL cant reference across schemas)
+=end
+
+module Ramen
+  module TestBugs
+    def t_bug1( key, db )
+      @name = "test_bug1_#{key}"
+      table_schema = (db.schema['RamenTestSchema'].table.has_key?('bug1')) ? 'RamenTestSchema' : 'RamenTestSchema2'
+      referenced_column = db.schema[table_schema].table['bug1'].fk['fk_bug1_employee'].column['pkid'].referenced_column
+      employee_id_column = db.schema['RamenTestSchema'].table['employee'].column['employeeid']
+      assert_same( referenced_column, employee_id_column, "referenced column must be employee id column in employee table." )
+    end
+  end
+end

data/test/test_core.rb

@@ -0,0 +1,63 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+require 'test/unit'
+require 'lib/ramen'
+
+class TestCore < Test::Unit::TestCase
+  def testIsUpcase
+    assert  "ABCDEFG".is_upcase?
+    assert !"abcdefg".is_upcase?
+    assert !"Abcdefg".is_upcase?
+  end
+  
+  def testToDelimitedWords
+    assert_equal "foo", "Foo".to_delimited_words
+    assert_equal "foo_bar_baz", "FooBarBaz".to_delimited_words
+    assert_equal "", "".to_delimited_words
+  end
+  
+  def test_compare
+    assert_equal(  -1, nil <=> 'foobar' )
+    assert_equal( nil, 'foobar' <=> nil )
+    assert_equal(   0, nil <=> nil )
+  end
+  
+  def test_singleton_class
+    a = TestCore
+    b = TestCore    
+    c = "another instance" #these two strings are different instances of String
+    d = "another instance"
+    e = "no foo"
+    a.singleton_class.module_eval do
+      define_method :foo do
+        "a"
+      end
+    end
+    b.singleton_class.module_eval do
+      define_method :foo do
+        "b"
+      end
+    end
+    c.singleton_class.module_eval do
+      define_method :foo do
+        "c"
+      end
+    end
+    d.singleton_class.module_eval do
+      define_method :foo do
+        "d"
+      end
+    end
+    assert_equal( a.singleton_class, b.singleton_class )
+    assert_equal( "b", a.foo )
+    assert_equal( "b", b.foo )
+    assert_not_equal( c.singleton_class, d.singleton_class )
+    assert_equal( "c", c.foo )
+    assert_equal( "d", d.foo )
+    assert( !(e.respond_to? :foo) )
+  end
+end
+
+

data/test/test_default_logger.rb

@@ -0,0 +1,38 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+
+require 'test/unit'
+require 'lib/ramen'
+
+module Ramen
+  # simple test
+  #
+  # ensures the logger interface (actually this was added for code coverage)
+  class TestDefaultLogger < Test::Unit::TestCase
+    def test_log
+      capture_stdout
+      logger = DefaultLogger.new
+      logger.debug 'debug'
+      logger.info  'info'
+      logger.warn  'warn'
+      logger.error 'error'
+      logger.fatal 'fatal'
+      result = restore_stdout
+      assert_equal "warn\nerror\nfatal\n", result
+    end
+    
+    def capture_stdout
+      @in, @out = IO.pipe
+      @stdout = $stdout
+      $stdout = @out
+    end
+    
+    def restore_stdout
+      $stdout = @stdout
+      @out.close
+      return @in.read
+    end
+  end
+end

data/test/test_home.rb

@@ -0,0 +1,33 @@
+#--
+# Copyright (c) 2007 Gregory N. Houston
+# See ramen.rb for license information.
+#++
+
+require 'test/unit'
+require 'lib/ramen'
+
+module Ramen
+class MockDBI
+  def execute( *args )
+    raise RamenError, "expected"
+  end
+end
+class SilentLogger
+  def do_nothing( msg )
+  end
+  alias debug do_nothing
+  alias info do_nothing
+  alias warn do_nothing
+  alias error do_nothing
+  alias fatal do_nothing
+end
+class TestHome < Test::Unit::TestCase
+  def test_dbi_error
+    h = Home.new( :logger => SilentLogger.new  )
+    assert_raise RamenError do
+      h.execute( MockDBI.new, 'i dont care')
+    end
+  end
+end
+end
+