README

Warning: this version has crude support for xquery added and has not been properly tested or completed, use with caution.
== Standalone driver ==
This directory contains the a ruby interface to monetdb5 
written in pure ruby.

lib/MonetDB.rb
lib/MonetDBConnection.rb
lib/MonetDBStatements.rb
lib/MonetDBData.rb
lib/MonetDBExceptions.rb
lib/hasher.rb
lib/demo.rb: demo application how to interact with the database

ruby-monetdb-sql-0.1.gemspec: make file for rubygems

doc/: rubydoc in HTML format

== Installation ==

The standalone monetdb driver can be installed using the RubyGems Package Manager.

First build a gem file starting from the gemspec configuration:

$ gem build ruby-monetdb-sql-0.1.gemspec

Then install with the command:

$ gem install ruby-monetdb-sql-0.1.gem

== Usage ==
To use the standalone driver import the 'MonetDB' class and 'rubygems' (in case you installed it using gems).

A typical sequence of events is as follows:
Invoke query using the database handle to send the statement to the server and get back a result set object.

A result set object  has methods for fetching rows, moving around in the result set, obtaining column metadata, and releasing the result set.
Use a row fetching method such as fetch_row or an iterator such as each to access the rows of the result set.
If you want a count of the number of rows in the result set: invoke 'num_rows' method.
Invoke 'free' to release the result set. 

== Example ==

require 'MonetDB'

db = MonetDB.new
db.connect(user = "monetdb", passwd = "monetdb", lang = "sql", host="127.0.0.1", port = 50000, db_name = "demo", auth_type = "SHA1")

# set type_cast=true to enable MonetDB to Ruby type mapping
res = db.query("SELECT * from tables;", type_cast = false)

#puts res.debug_columns_type

puts "Number of rows returned: " + res.num_rows.to_s
puts "Number of fields: " + res.num_fields.to_s


# Get the columns' name
col_names = res.name_fields


# Iterate over the record set and retrieve on row at a time
puts res.fetch
while row = res.fetch do
  printf "%s \n", row
end

# Release the result set.
res.free

# Disconnect from server
db.close

See lib/demo.rb and the MonetDBDatar class documentation for more examples.



== ActiveRecord connector adapter ==
Active Record connects business objects and database tables to create a persistable domain model where logic and data are presented in one wrapping. It‘s an implementation of the object-relational mapping (ORM) pattern.

Required files:

adapter/lib/active_record/monetdb_adapter.rb

Usage example follows:
require 'active_record'

ActiveRecord::Base.logger = Logger.new(STDERR)
ActiveRecord::Base.colorize_logging = true

ActiveRecord::Base.establish_connection(
        :adapter => "monetdb",
        :host => "localhost",
        :database => "demo"
)

# Create a new table
class AddTests < ActiveRecord::Migration
  def self.up
    create_table :tests do |table|
        table.column :name, :string
        table.column :surname, :string
    end
  end

  def self.down
   drop_table :tests
  end

end

AddTests.up

# Migration: add a column name with a default value
class AddAge < ActiveRecord::Migration 
  def self.up
    add_column :tests, :age, :smallint, :default => 18
  end

  def self.down
    remove_column :tests, :age
  end

end

class Test < ActiveRecord::Base
end

# Insert an entry in the table
Test.create(:name => 'X', :surname => 'Y')

# add a column
AddAge.up

# return the first result of the query SELECT * from tables
row = Test.find(:first)
printf "SELECT * from tests LIMIT 1:\n"
printf "Name: %s, Surname: %s, Age: %s\n", row.name, row.surname, row.age

# Drop the table
AddTests.down

== Rubygem ==

The standalone ruby driver can be distributed as a ruby gem.
A gem file is already available; however, it can be generated 
starting from the ruby-monetdb-sql-0.1.gemspec file:

$ gem build ruby-monetdb-sql-0.1.gemspec

To install the file run the command:

$ gem install ruby-monetdb-sql-0.1.gem

Documentation in ri and html format will be generated and installed as well