| Ingres Corporation |
This readme contains all of the documentation on the Ingres Ruby Active Record (AR) adapter and driver. AR is the standard database access interface used by Ruby on Rails (ROR or Rails) applications.
Please review this readme before building or installing this software. We encourage users to test the software and provide feedback.
There are two components to the Ingres support for Ruby:
Both components are required for Rails applications using Active Record (AR), which is the standard Rails Object-to-Relations Mapping (ORM) interface. The adapter implements the AR classes for Ingres; internally, it invokes the classes and methods in the driver to actually communicate with Ingres.
The driver, while primarily intended to service the adapter, can also be invoked directly from any Ruby program to communicate with Ingres. The driver interface does not follow any industry standard and may change in the future, if required.
To summarize, the AR interface provides an object interface while the driver interface is a more direct SQL-level interface.
This is a major release that addresses the following:
This Ingres Ruby Active Record adapter/driver supports all of the platforms supported by Ingres, including:
To build and install the Ingres Ruby interface, the following components are required:
Note: Ruby does not yet support building on later versions of Microsoft Visual Studio.
The following features are currently not included in the Ingres Open Source Ruby interface (also see the Known Issues section):
Note: We do not recommend that production applications use this API since it is intended for the Ingres AR adapter. The API may change in the future. It is, however, useful for testing Ingres connectivity and functionality.
Ruby program must have a "require 'Ingres'" statement to load in driver file.
Create Ingres class object:
object_instance_name=Ingres.new
Methods (by category):
Connect to database:
connect(database_name) connect_with_credentials(database_name,user,password)
Disconnect from database:
disconnect()
Execute SQL queries and transactional statements:
execute(sql)
(Alias for "execute" is "exec".)
For SQL queries or database procedure calls that contain parameters, use the pexecute() method in one of the following formats.
For selects, inserts, deletes, and updates:
pexecute(sql [ [,param_type,param_value] … ] )
For database procedure calls:
pexecute("{ <call> | <execute procedure> procedure_name [ (column_name = ? [ [ , column_name = ? ] … ] ) ] }" [ [ , column_name, param_type, param_value ] … ] )
where parameters in the sql text are represented by question marks (?) and there is one set of param_type/param_value entries for each one.
param_type must be one of the following single characters:
param_type |
Description |
|---|---|
| b | byte |
| B | long byte |
| c | char |
| d | date, |
| D | decimal |
| f | float |
| i | integer |
| n | nchar |
| N | nvarchar |
| t | text |
| T | long text |
| v | varchar |
| V | long varchar |
param_value should correspond to the type.
Both methods return a result set consisting of an array of rows, each of which is in turn an array of the columns within the row. For example:
ing.pexecute("select * from t1 where f1 = ?", 'i', 2)
Result Set Metadata:
| Method | Description |
|---|---|
| rows_affected() | Returns the number of rows affected by last execute() |
| column_list_of_names() | Returns the names of the columns in the result set |
| data_types() | Returns the data types of the columns in the result set |
| data_sizes() | Returns the data lengths of the columns in the result set |
Database Metadata:
| Method | Description |
|---|---|
| current_database() | Returns name of the current database connected to |
| tables() | Returns list of all tables in the current database |
Miscellaneous:
To turn trace debugging on or off:
set_debug_flag(flag,flag_value)
where
flag is one of following:
flag_value is TRUE or FALSE.
See Ruby Active Record documentation: http://ar.rubyonrails.com/.
| ActiveRecord Type | Ruby Class | Ingres Type | Notes |
|---|---|---|---|
| :primary_key | INTEGER NOT NULL PRIMARY KEY | ||
| :string | String | CHAR, NCHAR, VARCHAR, NVARCHAR,INTERVAL | |
| :text | String | VARCHAR(32000) | |
| :boolean | Boolean | INTEGER1 | |
| :integer | Fixnum | INTEGER2|4|8 | |
| Bignum | if INTEGER4|8 won't fit in Fixnum | ||
| :float | Float | FLOAT4, FLOAT8, MONEY | |
| :decimal | String | DECIMAL | |
| :date | Date | ANSIDATE | Ingres 9.1.0 or later |
| :datetime | Time | DATE, INGRESDATE | |
| :time | Time | TIME | Ingres 9.1.0 or later |
| :timestamp | Time | TIMESTAMP | Ingres 9.1.0 or later |
Note that the :binary ActiveRecord type is missing due to the lack of support for Ingres LONG BYTE, LONG VARCHAR support.
svn co http://code.ingres.com/ingres/drivers/ruby/This will download the complete tree for the Ruby driver into the directory 'ruby'. If you are only interested in the 'main' code line use the following command:
svn co http://code.ingres.com/ingres/drivers/ruby/main/ ruby-mainNote that an additional parameter of 'ruby-main' has been specified. The code for http://code.ingres.com/ingres/drivers/ruby/main/ will be extracted in to this directory. Otherwise the checkout will download the code into a directory named 'main'. For more information on working with Ingres source code control system see - http://community.ingres.com/wiki/Connectivity_Drivers_Source_Code
A binary version of the driver is provided for Windows (Ingres.so). If using the provided binary, skip to the install step below.
The driver can also be built from the source provided (Ingres.c). To build and install the Ingres Ruby driver, the following components are needed AND MUST BE IN YOUR PATH:
To build the driver
ruby -r mkmf extconf.rb
--with-ingres-include='/opt/Ingres/IngresII/ingres/files/'
--with-ingres-lib='/opt/Ingres/IngresII/ingres/lib/'
A sample createMake.bat has been included for Windows. The utility mkmf pulls configuration information from the extconf.rb file, which may need slight library name changes for different versions of Ingres or operating systems; see comments in extconf.rb file.
The output should look similar to the following:
bash-2.05$ ruby -r mkmf extconf.rb --with-ingres-include='/usr/ingres/files/' --with-ingres-lib='/usr/ingres/lib' checking for iiapi.h... yes checking for main() in -lingres... yes checking for main() in -lingres... yes creating Makefile
cannot open input file "msvcrt-ruby18.lib"
This can be resolved by removing the (lower case) "libpath =" line in the makefile.
To install the driver
Type make install. (On Windows, type nmake).
Or, with the pre-built Windows binary, copy Ingres.so to Ruby i386-msvcrt directory, such as: c:\ruby\lib\ruby\site_ruby\1.8\i386-msvcrt.
At a minimum, Ruby's Active Record must be installed. If running Rails, this will already exist as part of the Rails installation. For non-Rails users, AR may come with Ruby or may be installed separately as a Ruby "gem" into the Ruby installation.
There are several steps required to install the Ingres AR adapter into the Ruby AR installation.
Note: If only using the Ingres Ruby driver interface (not AR), installation of the adapter can be skipped and you can go directly to installation of the driver below.
Typically, the base path of the AR installation will be similar to the following and will be referred to hereafter in this documentation as AR_BASE (where the last digits in the path refer to the AR version):
UNIX/Linux: /usr/local/lib/ruby/gems/1.8/gems/activerecord-1.14.2
Windows: C:\ruby\lib\ruby\gems\1.8\gems\activerecord-1.15.3
To install the Ingres AR adapter into the Ruby AR installation
RAILS_CONNECTION_ADAPTERS = %w( mysql postgresql sqlite firebird sqlserver db2 oracle sybase openbase ingres )
development:
adapter: ingres
database: my_rails_app_development
username: ingres
password: ingres
host: localhost
For remote connections, change database and host to Ingres remote connection format in either "vnode::databasename" where
vnode is a name configured in the Ingres Network Utility or a dynamic vnode in @host,protocol,port[user,pwd]" format. For
details, see the Ingres Connectivity Guide.
>>>$ irb
irb(main):001:0> require 'Ingres'
=> true
irb(main):002:0> i = Ingres.new
=> #<Ingres:0xb7fba520>
irb(main):003:0> i.connect("activerecord_unittest")
=> #<Ingres:0xb7fba520>
irb(main):006:0> sql="select * from developers"
=> "select * from developers"
irb(main):007:0> result_set = i.execute(sql)
=> [[5, "fixture_5", 100000, "NULL", "NULL"], [6, "fixture_6", 100000, "NULL", "NULL"], [7,"fixture_7", 100000, "NULL", "NULL"], [11, "Jamis", 9000, "NULL", "NULL"], [8, "fixture_8", 100000, "NULL", "NULL"], [9, "fixture_9", 100000, "NULL", "NULL"], [2, "Jamis", 150000, "NULL", "NULL"], [10, "fixture_10", 100000, "NULL", "NULL"], [3, "fixture_3", 100000, "NULL", "NULL"], [1, "David", 80000, "NULL", "NULL"], [4, "fixture_4", 100000, "NULL", "NULL"]]
require "Ingres"
ing = Ingres.new
# You must connect to a database.
# Be sure you've created the database using "createdb".
ing.connect(some_database)
# you can also use:
# ing.connect_with_credentials( some_database, user_name, password)
sql = "select * from some_table"
result_set = ing.execute(sql)
# or
# result_set = ing.exec(sql)
# the result set is an array of arrays.
# you get one array for each row
# {{a,b,c}, {d,e,f}, etc}
# metadata is stored in these routines
# how many rows were touched by the last query
# usually an update
puts ing.rows_affected
# what's the current database (from the connect call)
puts ing.current_database
# the names of each column in the result set
puts ing.column_list_of_names
# the size of the data in each column
# this could be the length of a varchar or an int
puts ing.data_sizes
# what type is in each column
puts ing.data_types
# all the tables in the current database
puts ing.tables
# properly terminate your database connection
ing.disconnect
A Cookbook Tutorial can be accessed from the Rails website (http://rubyonrails.org/ docs) under the Tutorials section. Selection Rolling with Ruby on Rails: Part I takes you to http://www.onlamp.com/pub/a/onlamp/2006/12/14/revisiting-ruby-on-rails-revisited.html. The demo referred to in the tutorial is installed as part of some of the prepackaged Ruby on Rails versions, such as InstantRails on Windows or Rails LiveCD on Linux.
To run this demo in InstantRails, which is preconfigured to run against another database, do the following:
createdb cookbook_development
sql cookbook_development < cookbook_ingres.sql
Edit database.yml in ...\rails_apps\cookbook:
cd d:\InstantRails use_ruby cd .. InstantRails
If Mongrel is already up and app or even database.yml was changed, you must restart Mongrel:
Shutdown with Control-C in Mongrel startup command window.
cd d:\InstantRails\rails_apps\cookbook mongrel_rails start
From web browser, set url=http://localhost:3000/category. You should get a screen showing "Online Cookbook" at the top.
If you would like to get a copy of this, please post a request on the Ingres Community Forum in the Database Drivers and APIs area.
Known issues are as follows:
As this product is still in alpha status, issues specific to the Ingres Ruby AR adapter and driver should be posted on the Ingres forum http://community.ingres.com/forums/index.php?c=3 in the Database Driver and APIs forum rather than contacting Ingres Technical Support.
You can find more information on using the Ingres Ruby driver and ActiveRecord bindings at http://community.ingres.com/wiki/Ingres_Ruby_Development_Center.
For online technical assistance for other Ingres products or components, and a complete list of locations, primary service hours, and telephone numbers, contact technical support at http://ingres.com/support.
Revision $Id: README.html 48 2008-05-02 15:45:23Z crogr01 $
Available from: $Url$
© 2008 Ingres Corporation. All rights reserved.