amalgalite 0.5.1-x86-mswin32-60 → 0.6.0-x86-mswin32-60

data/HISTORY

@@ -1,4 +1,17 @@
 = Changelog
+== Version 0.6.0 - 2009-01-10
+
+=== Major Enhancements
+
+* Added ability to define custom SQL functions implemented in Ruby
+* Added ability to define custom SQL aggregates implemented in Ruby
+* Added support for Ruby busy handlers
+* Added database 'interrupt' support
+* Added support for Ruby progress handlers
+
+=== Minor Enhancement
+
+* update to SQLite version 3.6.7
 
 == Version 0.5.1 - 2008-11-30
 
@@ -26,11 +39,11 @@
 
 == Version 0.4.1 - 2008-09-28
 
-=== Minor Enhancement 
+=== Minor Enhancement
 
 * update to SQLite3 version 3.6.3
 * change rdoc template to darkfish
-  
+
 == Version 0.4.0 - 2008-09-14
 
 === Major Enhancements

data/README

@@ -19,6 +19,9 @@ Look in the examples/ directory to see
 * general usage
 * blob io
 * schema information
+* custom functions
+* custom aggregates
+* requiring ruby code from a database
 
 Also Scroll through Amalgalite::Database for a quick example, and a general
 overview of the API.

data/examples/define_aggregate.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+$: << "../lib"
+$: << "../ext"
+require 'amalgalite'
+
+#--
+# Create a database and a table to put some results from the functions in
+#--
+db = Amalgalite::Database.new( ":memory:" )
+db.execute( "CREATE TABLE atest( words )" )
+
+#------------------------------------------------------------------------------
+# Create unique word count aggregate 
+#------------------------------------------------------------------------------
+class UniqueWordCount < ::Amalgalite::Aggregate
+  attr_accessor :words
+
+  def initialize
+    @name = 'unique_word_count'
+    @arity = 1
+    @words = Hash.new { |h,k| h[k] = 0 }
+  end
+
+  def step( str )
+    str.split(/\W+/).each do |word|
+      words[ word.downcase ] += 1
+    end
+    return nil
+  end
+
+  def finalize
+    return words.size
+  end
+end
+
+db.define_aggregate( 'unique_word_count', UniqueWordCount )
+
+#------------------------------------------------------------------------------
+# Now we have a new aggregate function, lets insert some rows into the database
+# and see what we can find.
+#------------------------------------------------------------------------------
+sql = "INSERT INTO atest( words ) VALUES( ? )"
+verify = {}
+db.prepare( sql ) do |stmt|
+  DATA.each do |words|
+    words.strip!
+    puts "Inserting #{words}"
+    stmt.execute( words )
+    words.split(/\W+/).each { |w| verify[w] = true }
+  end
+end
+
+#------------------------------------------------------------------------------
+# And show the results
+#------------------------------------------------------------------------------
+puts
+puts "Getting results..."
+puts
+all_rows = db.execute("SELECT unique_word_count( words ) AS uwc FROM atest")
+puts "#{all_rows.first['uwc']} unique words found"
+puts "#{verify.size} unique words to verify"
+
+__END__
+some random
+words with
+which
+to play
+and there should
+be a couple of different
+words that appear
+more than once and
+some that appear only
+once

data/examples/define_function.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+$: << "../lib"
+$: << "../ext"
+require 'amalgalite'
+
+#--
+# Create a database and a table to put some results from the functions in
+#--
+db = Amalgalite::Database.new( ":memory:" )
+db.execute( "CREATE TABLE ftest( data, md5, sha1, sha2_bits, sha2)" )
+
+#------------------------------------------------------------------------------
+# Create an MD5 method using the block format of defining an sql fuction
+#------------------------------------------------------------------------------
+require 'digest/md5'
+db.define_function( 'md5' ) do |x|
+  Digest::MD5.hexdigest( x.to_s )
+end
+
+#------------------------------------------------------------------------------
+# Create a SHA1 method using the lambda format of defining an sql function
+#------------------------------------------------------------------------------
+require 'digest/sha1'
+sha1 = lambda do |y|
+  Digest::SHA1.hexdigest( y.to_s )
+end
+db.define_function( "sha1", sha1 )
+
+#------------------------------------------------------------------------------
+# Create a SHA2 method using the class format for defining an sql function
+# In this one we will allow any number of parameters, but we will only use the
+# first two.
+#------------------------------------------------------------------------------
+require 'digest/sha2'
+class SQLSha2
+  # track the number of invocations
+  attr_reader :call_count
+
+  def initialize
+    @call_count = 0
+  end
+
+  # the protocol that is used for sql function definition
+  def to_proc() self ; end
+
+  # say we take any number of parameters
+  def arity
+    -1
+  end
+
+  # The method that is called by SQLite, must be named 'call'
+  def call( *args )
+    text = args.shift.to_s
+    bitlength = (args.shift || 256).to_i
+    Digest::SHA2.new( bitlength ).hexdigest( text )
+  end
+end
+db.define_function('sha2', SQLSha2.new)
+
+
+#------------------------------------------------------------------------------
+# Now we have 3 new sql functions, each defined in one of the available methods
+# to define sql functions in amalgalite.  Lets insert some rows and look at the
+# results
+#------------------------------------------------------------------------------
+possible_bits = [ 256, 384, 512 ]
+sql = "INSERT INTO ftest( data, md5, sha1, sha2_bits, sha2 ) VALUES( @word , md5( @word ), sha1( @word ), @bits, sha2(@word,@bits) )" 
+db.prepare( sql ) do |stmt|
+  DATA.each do |word|
+    word.strip!
+    bits = possible_bits[ rand(3) ]
+    puts "Inserting #{word}, #{bits}"
+    stmt.execute( { '@word' => word, '@bits' => bits } )
+  end
+end
+
+#------------------------------------------------------------------------------
+# And show the results
+#------------------------------------------------------------------------------
+puts
+puts "Getting results..."
+puts
+columns = db.schema.tables['ftest'].columns.keys.sort
+i = 0
+db.execute("SELECT #{columns.join(',')} FROM ftest") do |row|
+  i += 1
+  puts "-----[ row #{i} ]-" + "-" * 42
+  columns.each do |col|
+    puts "#{col.ljust(10)} : #{row[col]}"
+  end
+  puts
+end
+
+
+__END__
+some
+random
+words
+with
+which
+to
+play

data/ext/amalgalite3.h

@@ -16,6 +16,8 @@ typedef struct am_sqlite3 {
   sqlite3 *db;
   VALUE    trace_obj;
   VALUE    profile_obj;
+  VALUE    busy_handler_obj;
+  VALUE    progress_handler_obj;
 } am_sqlite3;
 
 /* wrapper struct around the sqlite3_statement opaque pointer */
@@ -32,6 +34,15 @@ typedef struct am_sqlite3_blob {
   int           current_offset;
 } am_sqlite3_blob;
 
+/* wrapper struct around the information needed to call rb_apply
+ * used to encapsulate data into a call for amalgalite_wrap_apply
+ */
+typedef struct am_protected {
+    VALUE     instance;
+    ID        method;
+    int       argc;
+    VALUE    *argv;
+} am_protected_t;
 
 /** module and classes **/
 extern VALUE mA;              /* module Amalgalite                     */
@@ -41,11 +52,10 @@ extern VALUE eAS_Error;       /* class  Amalgalite::SQLite3::Error     */
 extern VALUE cAR;             /* class  Amalgalite::Requries */
 extern VALUE cARB;            /* class  Amalgalite::Requries::Bootstrap  */
 
-
 /*----------------------------------------------------------------------
  * Prototype for Amalgalite::SQLite3::Database
  *---------------------------------------------------------------------*/
-extern VALUE cAS_Database;    /* class  Amalgliate::SQLite3::Database  */
+extern VALUE cAS_Database;    /* class  Amalgalite::SQLite3::Database  */
 
 extern void  am_define_constants_under(VALUE);
 extern VALUE am_sqlite3_database_alloc(VALUE klass);
@@ -62,6 +72,7 @@ extern VALUE am_sqlite3_database_table_column_metadata(VALUE self, VALUE db_name
 extern VALUE am_sqlite3_database_prepare(VALUE self, VALUE rSQL);
 extern VALUE am_sqlite3_database_register_trace_tap(VALUE self, VALUE tap);
 extern VALUE am_sqlite3_database_register_profile_tap(VALUE self, VALUE tap);
+extern VALUE am_sqlite3_database_busy_handler(VALUE self, VALUE handler);
 
 /*----------------------------------------------------------------------
  * Prototype for Amalgalite::SQLite3::Statement 
@@ -113,6 +124,16 @@ extern VALUE am_sqlite3_blob_write(VALUE self, VALUE buffer);
 extern VALUE am_sqlite3_blob_close(VALUE self);
 extern VALUE am_sqlite3_blob_length(VALUE self);
 
+/*----------------------------------------------------------------------
+ * more initialization methods
+ *----------------------------------------------------------------------*/
+extern void Init_amalgalite3_constants( );
+extern void Init_amalgalite3_database( );
+extern void Init_amalgalite3_statement( );
+extern void Init_amalgalite3_blob( );
+extern void Init_amalgalite3_requires_bootstrap( );
+
+ 
 /***********************************************************************
  * Type conversion macros between sqlite data types and ruby types
  **********************************************************************/
@@ -121,4 +142,9 @@ extern VALUE am_sqlite3_blob_length(VALUE self);
 #define SQLUINT64_2NUM(x)     ( ULL2NUM( x ) )
 #define NUM2SQLINT64( obj )   ( NUM2LL( obj ) )
 #define NUM2SQLUINT64( obj )  ( NUM2ULL( obj ) )
+
+/***********************************************************************
+ * return the last exception in ruby's error message
+ */
+#define ERROR_INFO_MESSAGE()  ( rb_obj_as_string( rb_gv_get("$!") ) )
 #endif

data/ext/amalgalite3_blob.c

@@ -99,10 +99,9 @@ VALUE am_sqlite3_blob_close( VALUE self )
 VALUE am_sqlite3_blob_length( VALUE self )
 {
     am_sqlite3_blob *am_blob;
-    int              n;
 
     Data_Get_Struct(self, am_sqlite3_blob, am_blob);
-    
+
     return INT2FIX( am_blob->length );
 }
 

data/ext/amalgalite3_database.c

@@ -3,21 +3,21 @@
  * Copyright (c) 2008 Jeremy Hinegardner
  * All rights reserved.  See LICENSE and/or COPYING for details.
  *
- * vim: shiftwidth=4 
- */ 
+ * vim: shiftwidth=4
+ */
 
-VALUE cAS_Database;       /* class  Amalgliate::SQLite3::Database        */
-VALUE cAS_Database_Stat;  /* class  Amalgliate::SQLite3::Database::Stat  */
+VALUE cAS_Database;       /* class  Amalgalite::SQLite3::Database        */
+VALUE cAS_Database_Stat;  /* class  Amalgalite::SQLite3::Database::Stat  */
 
 /**
  * Document-method: open
  *
  * call-seq:
- *    Amalagliate::SQLite3::Database.open( filename, flags = READWRITE | CREATE ) -> Database
+ *    Amalgalite::SQLite3::Database.open( filename, flags = READWRITE | CREATE ) -> Database
  *
- * Create a new SQLite3 database with a UTF-8 encoding.
+ * Create a new SQLite2 database with a UTF-8 encoding.
  *
- */ 
+ */
 VALUE am_sqlite3_database_open(int argc, VALUE *argv, VALUE class)
 {
     VALUE  self = am_sqlite3_database_alloc(class);
@@ -28,7 +28,6 @@ VALUE am_sqlite3_database_open(int argc, VALUE *argv, VALUE class)
     int     rc;
     am_sqlite3* am_db;
 
-
     /* at least a filename argument is required */
     rb_scan_args( argc, argv, "11", &rFilename, &rFlags );
 
@@ -89,7 +88,7 @@ VALUE am_sqlite3_database_open16(VALUE class, VALUE rFilename)
 
 /**
  * call-seq:
- *    database.close 
+ *    database.close
  *
  * Close the database
  */
@@ -106,7 +105,7 @@ VALUE am_sqlite3_database_close(VALUE self)
     }
 
     return self;
-                
+
 }
 
 /**
@@ -114,7 +113,7 @@ VALUE am_sqlite3_database_close(VALUE self)
  *    database.last_insert_rowid -> Integer
  *
  * Return the rowid of the last row inserted into the database from this
- * database connection.  
+ * database connection.
  */
 VALUE am_sqlite3_database_last_insert_rowid(VALUE self)
 {
@@ -141,7 +140,7 @@ VALUE am_sqlite3_database_is_autocommit(VALUE self)
 
     Data_Get_Struct(self, am_sqlite3, am_db);
     rc = sqlite3_get_autocommit( am_db->db );
-    
+
     return ( 0 == rc ) ? Qfalse : Qtrue ;
 }
 
@@ -149,7 +148,7 @@ VALUE am_sqlite3_database_is_autocommit(VALUE self)
  * call-seq:
  *    database.row_changes -> Integer
  *
- * return the number of rows changed with the most recent INSERT, UPDATE or 
+ * return the number of rows changed with the most recent INSERT, UPDATE or
  * DELETE statement.
  *
  */
@@ -160,7 +159,7 @@ VALUE am_sqlite3_database_row_changes(VALUE self)
 
     Data_Get_Struct(self, am_sqlite3, am_db);
     rc = sqlite3_changes( am_db->db );
-    
+
     return INT2FIX(rc);
 }
 
@@ -178,7 +177,7 @@ VALUE am_sqlite3_database_last_error_code(VALUE self)
 
     Data_Get_Struct(self, am_sqlite3, am_db);
     code = sqlite3_errcode( am_db->db );
-    
+
     return INT2FIX( code );
 }
 
@@ -196,7 +195,7 @@ VALUE am_sqlite3_database_last_error_message(VALUE self)
 
     Data_Get_Struct(self, am_sqlite3, am_db);
     message = sqlite3_errmsg( am_db->db );
-    
+
     return rb_str_new2( message );
 }
 
@@ -204,7 +203,7 @@ VALUE am_sqlite3_database_last_error_message(VALUE self)
  * call-seq:
  *    database.total_changes -> Integer
  *
- * return the number of rows changed by INSERT, UPDATE or DELETE statements 
+ * return the number of rows changed by INSERT, UPDATE or DELETE statements
  * in the database connection since the connection was opened.
  *
  */
@@ -215,7 +214,7 @@ VALUE am_sqlite3_database_total_changes(VALUE self)
 
     Data_Get_Struct(self, am_sqlite3, am_db);
     rc = sqlite3_total_changes( am_db->db );
-    
+
     return INT2FIX(rc);
 }
 
@@ -223,8 +222,8 @@ VALUE am_sqlite3_database_total_changes(VALUE self)
  * call-seq:
  *    stat.update!(  reset = false ) -> nil
  *
- * Populates the _@current_ and _@higwater_ instance variables of the given 
- * Database Stat object with the values from the sqlite3_db_status call.  
+ * Populates the _@current_ and _@higwater_ instance variables of the given
+ * Database Stat object with the values from the sqlite3_db_status call.
  * If reset it true then the highwater mark for the stat is reset
  *
  */
@@ -270,10 +269,10 @@ VALUE am_sqlite3_database_stat_update_bang( int argc, VALUE *argv, VALUE self )
  *
  * Create a new SQLite3 statement.
  */
-VALUE am_sqlite3_database_prepare(VALUE self, VALUE rSQL) 
+VALUE am_sqlite3_database_prepare(VALUE self, VALUE rSQL)
 {
     VALUE            sql = StringValue( rSQL );
-    VALUE            stmt = am_sqlite3_statement_alloc(cAS_Statement); 
+    VALUE            stmt = am_sqlite3_statement_alloc(cAS_Statement);
     am_sqlite3      *am_db;
     am_sqlite3_stmt *am_stmt;
     const char      *tail;
@@ -282,7 +281,7 @@ VALUE am_sqlite3_database_prepare(VALUE self, VALUE rSQL)
     Data_Get_Struct(self, am_sqlite3, am_db);
 
     Data_Get_Struct(stmt, am_sqlite3_stmt, am_stmt);
-    rc = sqlite3_prepare_v2( am_db->db, RSTRING(sql)->ptr, RSTRING(sql)->len, 
+    rc = sqlite3_prepare_v2( am_db->db, RSTRING(sql)->ptr, RSTRING(sql)->len,
                             &(am_stmt->stmt), &tail);
     if ( SQLITE_OK != rc) {
         rb_raise(eAS_Error, "Failure to prepare statement %s : [SQLITE_ERROR %d] : %s\n",
@@ -303,9 +302,9 @@ VALUE am_sqlite3_database_prepare(VALUE self, VALUE rSQL)
 /**
  * This function is registered with a sqlite3 database using the sqlite3_trace
  * function.  During the registration process a handle on a VALUE is also
- * registered.  
+ * registered.
  *
- * When this function is called, it calls the 'trace' method on the tap object, 
+ * When this function is called, it calls the 'trace' method on the tap object,
  * which is the VALUE that was registered during the sqlite3_trace call.
  *
  * This function corresponds to the SQLite xTrace function specification.
@@ -318,21 +317,20 @@ void amalgalite_xTrace(void* tap, const char* msg)
     rb_funcall( trace_obj, rb_intern("trace"), 1, rb_str_new2( msg ) );
     return;
 }
-    
+
 
 /**
  * call-seq:
  *   database.register_trace_tap( tap_obj )
  *
  * This registers an object to be called with every trace event in SQLite.
- * 
+ *
  * This is an experimental api and is subject to change, or removal.
  *
  */
 VALUE am_sqlite3_database_register_trace_tap(VALUE self, VALUE tap)
 {
     am_sqlite3   *am_db;
-    int           rc;
 
     Data_Get_Struct(self, am_sqlite3, am_db);
 
@@ -357,7 +355,8 @@ VALUE am_sqlite3_database_register_trace_tap(VALUE self, VALUE tap)
     }
 
     return Qnil;
-}    
+}
+
 
 /**
  * the amagliate trace function to be registered with register_trace_tap
@@ -369,7 +368,7 @@ void amalgalite_xProfile(void* tap, const char* msg, sqlite3_uint64 time)
 {
     VALUE     trace_obj = (VALUE) tap;
 
-    rb_funcall( trace_obj, rb_intern("profile"), 
+    rb_funcall( trace_obj, rb_intern("profile"),
                 2, rb_str_new2( msg ), SQLUINT64_2NUM(time) );
 
     return;
@@ -387,7 +386,6 @@ void amalgalite_xProfile(void* tap, const char* msg, sqlite3_uint64 time)
 VALUE am_sqlite3_database_register_profile_tap(VALUE self, VALUE tap)
 {
     am_sqlite3   *am_db;
-    int           rc;
 
     Data_Get_Struct(self, am_sqlite3, am_db);
 
@@ -410,11 +408,512 @@ VALUE am_sqlite3_database_register_profile_tap(VALUE self, VALUE tap)
         sqlite3_profile( am_db->db, amalgalite_xProfile, (void *)am_db->profile_obj );
     }
     return Qnil;
-}    
+}
+
+/**
+ * invoke a ruby function.  This is here to be used by rb_protect.
+ */
+VALUE amalgalite_wrap_funcall2( VALUE arg )
+{
+    am_protected_t *protected = (am_protected_t*) arg;
+    return rb_funcall2( protected->instance, protected->method, protected->argc, protected->argv );
+}
+
+/**
+ * Set the context result on the sqlite3_context based upon the ruby VALUE.
+ * This converts the ruby value to the appropriate C-type and makes the
+ * appropriate call sqlite3_result_* call
+ */
+void amalgalite_set_context_result( sqlite3_context* context, VALUE result )
+{
+    switch( TYPE(result) ) {
+        case T_FIXNUM:
+        case T_BIGNUM:
+            sqlite3_result_int64( context, NUM2SQLINT64(result) );
+            break;
+        case T_FLOAT:
+            sqlite3_result_double( context, NUM2DBL(result) );
+            break;
+        case T_NIL:
+            sqlite3_result_null( context );
+            break;
+        case T_TRUE:
+            sqlite3_result_int64( context, 1);
+            break;
+        case T_FALSE:
+            sqlite3_result_int64( context, 0);
+            break;
+        case T_STRING:
+            sqlite3_result_text( context, RSTRING(result)->ptr, RSTRING(result)->len, NULL);
+            break;
+        default:
+            sqlite3_result_error( context, "Unable to convert ruby object to an SQL function result", -1 );
+            sqlite3_result_error_code( context, 42 );
+            break;
+    }
+    return;
+}
+
+/** 
+ * Convert from a protected sqlite3_value to a ruby object
+ */
+VALUE sqlite3_value_to_ruby_value( sqlite3_value* s_value )
+{
+    VALUE         rb_value = Qnil;
+    sqlite3_int64 i64;
+
+    switch( sqlite3_value_type( s_value) ) {
+        case SQLITE_NULL:
+            rb_value = Qnil;
+            break;
+        case SQLITE_INTEGER:
+            i64 = sqlite3_value_int64( s_value);
+            rb_value = SQLINT64_2NUM(i64); 
+            break;
+        case SQLITE_FLOAT:
+            rb_value = rb_float_new( sqlite3_value_double( s_value ) );
+            break;
+        case SQLITE_TEXT:
+        case SQLITE_BLOB:
+            rb_value = rb_str_new2((const char*) sqlite3_value_text( s_value ) );
+            break;
+    }
+    return rb_value;
+}
+
+
+/**
+ * the amalgalite xBusy handler that is used to invoke the ruby function for
+ * doing busy callbacks.
+ *
+ * This function conforms to the xBusy function specification for
+ * sqlite3_busy_handler.
+ */
+int amalgalite_xBusy( void *pArg , int nArg)
+{
+    VALUE         *args = ALLOCA_N( VALUE, 1 );
+    VALUE          result = Qnil;
+    int            state;
+    int            busy = 1;
+    am_protected_t protected;
+
+    args[0] = INT2FIX(nArg);
+
+    protected.instance = (VALUE)pArg;
+    protected.method   = rb_intern("call");
+    protected.argc     = 1;
+    protected.argv     = args;
+
+    result = rb_protect( amalgalite_wrap_funcall2, (VALUE)&protected, &state );
+    if ( state || ( Qnil == result || Qfalse == result ) ){
+        busy = 0;
+     }
+    return busy;
+}
+
+
+/**
+ * call-seq:
+ *  database.busy_handler( proc_like or nil )
+ *
+ * register a busy handler.  If the argument is nil, then an existing busy
+ * handler is removed.  Otherwise the argument is registered as the busy
+ * handler.
+ */
+VALUE am_sqlite3_database_busy_handler( VALUE self, VALUE handler )
+{
+    am_sqlite3   *am_db;
+    int           rc;
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+
+    /* Removing a busy handler case, remove it from sqlite and then remove it
+     * from the garbage collector if it existed */
+    if ( Qnil == handler ) {
+        rc = sqlite3_busy_handler( am_db->db, NULL, NULL );
+        if ( SQLITE_OK != rc ) {
+            rb_raise(eAS_Error, "Failure removing busy handler : [SQLITE_ERROR %d] : %s\n", 
+                    rc, sqlite3_errmsg( am_db->db ));
+        }
+        if ( Qnil != am_db->busy_handler_obj ) {
+            rb_gc_unregister_address( &(am_db->busy_handler_obj) );
+        }
+    } else {
+        /* installing a busy handler
+         * - register it with sqlite
+         * - keep a reference for ourselves with our database handle
+         * - registere the handler reference with the garbage collector
+         */
+        rc = sqlite3_busy_handler( am_db->db, amalgalite_xBusy, (void*)handler );
+        if ( SQLITE_OK != rc ) {
+            rb_raise(eAS_Error, "Failure setting busy handler : [SQLITE_ERROR %d] : %s\n", 
+                    rc, sqlite3_errmsg( am_db->db ));
+        }
+        am_db->busy_handler_obj = handler;
+        rb_gc_register_address( &(am_db->busy_handler_obj) );
+    }
+    return Qnil;
+}
+
+
+/**
+ * the amalgalite xProgress  handler that is used to invoke the ruby function for
+ * doing progress handler callbacks.
+ *
+ * This function conforms to the xProgress function specification for
+ * sqlite3_progress_handler.
+ */
+int amalgalite_xProgress( void *pArg )
+{
+    VALUE          result = Qnil;
+    int            state;
+    int            cancel = 0;
+    am_protected_t protected;
+
+    protected.instance = (VALUE)pArg;
+    protected.method   = rb_intern("call");
+    protected.argc     = 0;
+    protected.argv     = NULL;
+
+    result = rb_protect( amalgalite_wrap_funcall2, (VALUE)&protected, &state );
+    if ( state || ( Qnil == result || Qfalse == result ) ){
+        cancel = 1;
+     }
+    return cancel;
+}
+
+
+/**
+ * call-seq:
+ *  database.progress_handler( op_count, proc_like or nil )
+ *
+ * register a progress handler.  If the argument is nil, then an existing
+ * progress handler is removed.  Otherwise the argument is registered as the
+ * progress handler.
+ */
+VALUE am_sqlite3_database_progress_handler( VALUE self, VALUE op_count, VALUE handler )
+{
+    am_sqlite3   *am_db;
+    int           op_codes = FIX2INT( op_count );
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+
+    /* Removing a progress handler, remove it from sqlite and then remove it
+     * from the garbage collector if it existed */
+    if ( Qnil == handler ) {
+        sqlite3_progress_handler( am_db->db, 0, NULL, (void*)NULL );
+        if ( Qnil != am_db->progress_handler_obj ) {
+            rb_gc_unregister_address( &(am_db->progress_handler_obj) );
+        }
+    } else {
+        /* installing a progress handler
+         * - register it with sqlite
+         * - keep a reference for ourselves with our database handle
+         * - register the handler reference with the garbage collector
+         */
+        sqlite3_progress_handler( am_db->db, op_codes, amalgalite_xProgress, (void*)handler );
+        am_db->progress_handler_obj = handler;
+        rb_gc_register_address( &(am_db->progress_handler_obj) );
+    }
+    return Qnil;
+}
+
+
+/**
+ * the amalgalite xFunc callback that is used to invoke the ruby function for
+ * doing scalar SQL functions.
+ *
+ * This function conforms to the xFunc function specification for
+ * sqlite3_create_function
+ */
+void amalgalite_xFunc( sqlite3_context* context, int argc, sqlite3_value** argv )
+{
+    VALUE         *args = ALLOCA_N( VALUE, argc );
+    VALUE          result;
+    int            state;
+    int            i;
+    am_protected_t protected;
+
+    /* convert each item in argv to a VALUE object based upon its type via
+     * sqlite3_value_type( argv[n] )
+     */
+    for( i = 0 ; i < argc ; i++) {
+        args[i] = sqlite3_value_to_ruby_value( argv[i] );
+    }
+
+    /* gather all the data to make the protected call */
+    protected.instance = (VALUE) sqlite3_user_data( context );
+    protected.method   = rb_intern("call");
+    protected.argc     = argc;
+    protected.argv     = args;
+
+    result = rb_protect( amalgalite_wrap_funcall2, (VALUE)&protected, &state );
+    /* check the results */
+    if ( state ) {
+        VALUE msg = ERROR_INFO_MESSAGE();
+        sqlite3_result_error( context, RSTRING(msg)->ptr, RSTRING(msg)->len );
+    } else {
+        amalgalite_set_context_result( context, result );
+    }
+
+    return; 
+}
+
+/**
+ * call-seq:
+ *   database.define_function( name, proc_like )
+ *
+ * register the given function to be invoked as an sql function.
+ */
+VALUE am_sqlite3_database_define_function( VALUE self, VALUE name, VALUE proc_like )
+{
+    am_sqlite3   *am_db;
+    int           rc;
+    VALUE         arity = rb_funcall( proc_like, rb_intern( "arity" ), 0 );
+    char*         zFunctionName = RSTRING(name)->ptr;
+    int           nArg = FIX2INT( arity );
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    rc = sqlite3_create_function( am_db->db, 
+                                  zFunctionName, nArg,
+                                  SQLITE_ANY,
+                                  (void *)proc_like, amalgalite_xFunc,
+                                  NULL, NULL);
+    if ( SQLITE_OK != rc ) {
+       rb_raise(eAS_Error, "Failure defining SQL function '%s' with arity '%d' : [SQLITE_ERROR %d] : %s\n",
+                zFunctionName, nArg, rc, sqlite3_errmsg( am_db->db ));
+    }
+    rb_gc_register_address( &proc_like );
+    return Qnil;
+}
+
+/**
+ * call-seq:
+ *  database.remove_function( name, proc_like )
+ *
+ * remove the given function from availability in SQL.
+ */
+VALUE am_sqlite3_database_remove_function( VALUE self, VALUE name, VALUE proc_like )
+{
+    am_sqlite3    *am_db;
+    int            rc;
+    VALUE         arity = rb_funcall( proc_like, rb_intern( "arity" ), 0 );
+    char*         zFunctionName = RSTRING(name)->ptr;
+    int           nArg = FIX2INT( arity );
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    rc = sqlite3_create_function( am_db->db, 
+                                  zFunctionName, nArg,
+                                  SQLITE_ANY,
+                                  NULL, NULL,
+                                  NULL, NULL);
+    if ( SQLITE_OK != rc ) {
+       rb_raise(eAS_Error, "Failure removing SQL function '%s' with arity '%d' : [SQLITE_ERROR %d] : %s\n",
+                zFunctionName, nArg, rc, sqlite3_errmsg( am_db->db ));
+    }
+    rb_gc_unregister_address( &proc_like );
+    return Qnil;
+}
+
+/* wrap rb_class_new_instance so it can be called from within an rb_protect */
+VALUE amalgalite_wrap_new_aggregate( VALUE arg )
+{
+    return rb_class_new_instance( 0, 0, arg );
+}
+
+
+/**
+ * the amalgalite xStep callback that is used to invoke the ruby method for
+ * doing aggregate step oprations as part of an aggregate SQL function.
+ *
+ * This function conforms to the xStep function specification for
+ * sqlite3_create_function.
+ */
+void amalgalite_xStep( sqlite3_context* context, int argc, sqlite3_value** argv )
+{
+    VALUE         *args = ALLOCA_N( VALUE, argc );
+    VALUE          result;
+    int            state;
+    int            i;
+    am_protected_t protected;
+    VALUE         *aggregate_context = (VALUE*)sqlite3_aggregate_context( context, sizeof( VALUE ) );
+
+    if ( 0 == aggregate_context ) {
+        sqlite3_result_error_nomem( context );
+        return;
+    }
+
+    /* instantiate an instance of the aggregate function class if the 
+     * aggregate context is zero'd out .
+     *
+     * If there is an error in initialization of the aggregate, set the error
+     * context
+     */ 
+    if ( *aggregate_context == T_NONE ) {
+        VALUE klass = (VALUE) sqlite3_user_data( context );
+        result = rb_protect( amalgalite_wrap_new_aggregate, klass, &state );
+        *aggregate_context = result;
+        /* mark the instance as protected from collection */
+        rb_gc_register_address( aggregate_context );
+        if ( state ) {
+            VALUE msg = ERROR_INFO_MESSAGE();
+            sqlite3_result_error( context, RSTRING(msg)->ptr, RSTRING(msg)->len);
+            rb_iv_set( *aggregate_context, "@_exception", rb_gv_get("$!" ));
+            return;
+        } else {
+            rb_iv_set( *aggregate_context, "@_exception", Qnil );
+        }
+    }
+
+    /* convert each item in argv to a VALUE object based upon its type via
+     * sqlite3_value_type( argv[n] )
+     */
+    for( i = 0 ; i < argc ; i++) {
+        args[i] = sqlite3_value_to_ruby_value( argv[i] );
+    }
+
+    /* gather all the data to make the protected call */
+    protected.instance = *aggregate_context;
+    protected.method   = rb_intern("step");
+    protected.argc     = argc;
+    protected.argv     = args;
+
+    result = rb_protect( amalgalite_wrap_funcall2, (VALUE)&protected, &state );
+
+    /* check the results, if there is an error, set the @exception ivar */
+    if ( state ) {
+        VALUE msg = ERROR_INFO_MESSAGE();
+        sqlite3_result_error( context, RSTRING(msg)->ptr, RSTRING(msg)->len);
+        rb_iv_set( *aggregate_context, "@_exception", rb_gv_get("$!" ));
+    }
+
+    return ;
+}
+
+
+/**
+ * the amalgalite xFinal callback that is used to invoke the ruby method for
+ * doing aggregate final operations as part of an aggregate SQL function.
+ *
+ * This function conforms to the xFinal function specification for
+ * sqlite3_create_function.
+ */
+void amalgalite_xFinal( sqlite3_context* context )
+{
+    VALUE          result;
+    int            state;
+    am_protected_t protected;
+    VALUE         *aggregate_context = (VALUE*)sqlite3_aggregate_context( context, sizeof( VALUE ) );
+    VALUE          exception = rb_iv_get( *aggregate_context, "@_exception" );
+
+    if ( Qnil == exception ) {
+        /* gather all the data to make the protected call */
+        protected.instance = *aggregate_context;
+        protected.method   = rb_intern("finalize");
+        protected.argc     = 0;
+        protected.argv     = NULL;
+
+        result = rb_protect( amalgalite_wrap_funcall2, (VALUE)&protected, &state );
+
+        /* check the results */
+        if ( state ) {
+            VALUE msg = ERROR_INFO_MESSAGE();
+            sqlite3_result_error( context, RSTRING(msg)->ptr, RSTRING(msg)->len );
+        } else {
+            amalgalite_set_context_result( context, result );
+        }
+    } else {
+        VALUE msg = rb_obj_as_string( exception );
+        sqlite3_result_error( context, RSTRING(msg)->ptr, RSTRING(msg)->len );
+    }
+
+
+
+    /* release the aggregate instance from garbage collector protection */
+    rb_gc_unregister_address( aggregate_context );
+
+    return ;
+}
+
+
 
 /**
  * call-seq:
- *    datatabase.table_column_metadata( db_name, table_name, column_name) -> Hash
+ *   database.define_aggregate( name, arity, klass )
+ *
+ * register the given klass to be invoked as an sql aggregate.
+ */
+VALUE am_sqlite3_database_define_aggregate( VALUE self, VALUE name, VALUE arity, VALUE klass )
+{
+    am_sqlite3   *am_db;
+    int           rc;
+    char*         zFunctionName = RSTRING(name)->ptr;
+    int           nArg = FIX2INT( arity );
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    rc = sqlite3_create_function( am_db->db, 
+                                  zFunctionName, nArg,
+                                  SQLITE_ANY,
+                                  (void *)klass, NULL,
+                                  amalgalite_xStep,
+                                  amalgalite_xFinal);
+    if ( SQLITE_OK != rc ) {
+       rb_raise(eAS_Error, "Failure defining SQL aggregate '%s' with arity '%d' : [SQLITE_ERROR %d] : %s\n",
+                zFunctionName, nArg, rc, sqlite3_errmsg( am_db->db ));
+    }
+    rb_gc_register_address( &klass );
+    return Qnil;
+}
+
+
+/**
+ * call-seq:
+ *  database.remove_aggregate( name, arity, klass )
+ *
+ * remove the given klass from availability in SQL as an aggregate.
+ */
+VALUE am_sqlite3_database_remove_aggregate( VALUE self, VALUE name, VALUE arity, VALUE klass )
+{
+    am_sqlite3    *am_db;
+    int            rc;
+    char*         zFunctionName = RSTRING(name)->ptr;
+    int           nArg = FIX2INT( arity );
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    rc = sqlite3_create_function( am_db->db, 
+                                  zFunctionName, nArg,
+                                  SQLITE_ANY,
+                                  NULL, NULL,
+                                  NULL, 
+                                  NULL);
+    if ( SQLITE_OK != rc ) {
+       rb_raise(eAS_Error, "Failure removing SQL aggregate '%s' with arity '%d' : [SQLITE_ERROR %d] : %s\n",
+                zFunctionName, nArg, rc, sqlite3_errmsg( am_db->db ));
+    }
+    rb_gc_unregister_address( &klass );
+    return Qnil;
+}
+
+
+/**
+ * call-seq:
+ *  database.interrupt!
+ *
+ * Cause another thread with a handle on this database to be interrupted and
+ * return at the earliest opportunity as interrupted.
+ */
+VALUE am_sqlite3_database_interrupt_bang( VALUE self )
+{
+    am_sqlite3  *am_db;
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    sqlite3_interrupt( am_db->db );
+    return Qnil;
+}
+
+/**
+ * call-seq:
+ *    database.table_column_metadata( db_name, table_name, column_name) -> Hash
  *
  * Returns a hash containing the meta information about the column.  The
  * available keys are:
@@ -434,7 +933,7 @@ VALUE am_sqlite3_database_table_column_metadata(VALUE self, VALUE db_name, VALUE
     /* input */
     const char  *zDbName      = StringValuePtr( db_name );
     const char  *zTableName   = StringValuePtr( tbl_name );
-    const char  *zColumnName  = StringValuePtr( col_name ); 
+    const char  *zColumnName  = StringValuePtr( col_name );
 
     /* output */
     const char *pzDataType = NULL;
@@ -452,9 +951,9 @@ VALUE am_sqlite3_database_table_column_metadata(VALUE self, VALUE db_name, VALUE
     if ( SQLITE_OK != rc ) {
        rb_raise(eAS_Error, "Failure retrieveing column meta data for table '%s' column '%s' : [SQLITE_ERROR %d] : %s\n",
                 zTableName, zColumnName, rc, sqlite3_errmsg( am_db-> db ));
-  
+
     }
-    
+
     rStr = ( NULL == pzDataType) ? Qnil : rb_str_new2( pzDataType );
     rb_hash_aset( rHash, rb_str_new2("declared_data_type"), rStr );
 
@@ -489,6 +988,18 @@ void am_sqlite3_database_free(am_sqlite3* am_db)
         am_db->profile_obj = Qnil;
     }
 
+    if ( Qnil != am_db->busy_handler_obj ) {
+        rb_gc_unregister_address( &(am_db->busy_handler_obj) );
+        am_db->busy_handler_obj = Qnil;
+    }
+
+    if ( Qnil != am_db->progress_handler_obj ) {
+        rb_gc_unregister_address( &(am_db->progress_handler_obj) );
+        am_db->progress_handler_obj = Qnil;
+    }
+
+
+
     free(am_db);
     return;
 }
@@ -501,8 +1012,10 @@ VALUE am_sqlite3_database_alloc(VALUE klass)
     am_sqlite3*  am_db = ALLOC(am_sqlite3);
     VALUE          obj ;
 
-    am_db->trace_obj   = Qnil;
-    am_db->profile_obj = Qnil;
+    am_db->trace_obj            = Qnil;
+    am_db->profile_obj          = Qnil;
+    am_db->busy_handler_obj     = Qnil;
+    am_db->progress_handler_obj = Qnil;
 
     obj = Data_Wrap_Struct(klass, NULL, am_sqlite3_database_free, am_db);
     return obj;
@@ -516,19 +1029,19 @@ VALUE am_sqlite3_database_alloc(VALUE klass)
  */
 void Init_amalgalite3_database( )
 {
-    
+
     VALUE ma  = rb_define_module("Amalgalite");
     VALUE mas = rb_define_module_under(ma, "SQLite3");
-  
-    /* 
+
+    /*
      * Encapsulate an SQLite3 database
      */
-    cAS_Database = rb_define_class_under( mas, "Database", rb_cObject); 
+    cAS_Database = rb_define_class_under( mas, "Database", rb_cObject);
 
-    rb_define_alloc_func(cAS_Database, am_sqlite3_database_alloc); 
-    rb_define_singleton_method(cAS_Database, "open", am_sqlite3_database_open, -1); 
-    rb_define_singleton_method(cAS_Database, "open16", am_sqlite3_database_open16, 1); 
-    rb_define_method(cAS_Database, "prepare", am_sqlite3_database_prepare, 1); 
+    rb_define_alloc_func(cAS_Database, am_sqlite3_database_alloc);
+    rb_define_singleton_method(cAS_Database, "open", am_sqlite3_database_open, -1);
+    rb_define_singleton_method(cAS_Database, "open16", am_sqlite3_database_open16, 1);
+    rb_define_method(cAS_Database, "prepare", am_sqlite3_database_prepare, 1);
     rb_define_method(cAS_Database, "close", am_sqlite3_database_close, 0); /* in amalgalite3_database.c */
     rb_define_method(cAS_Database, "last_insert_rowid", am_sqlite3_database_last_insert_rowid, 0); /* in amalgalite3_database.c */
     rb_define_method(cAS_Database, "autocommit?", am_sqlite3_database_is_autocommit, 0); /* in amalgalite3_database.c */
@@ -539,6 +1052,14 @@ void Init_amalgalite3_database( )
     rb_define_method(cAS_Database, "total_changes", am_sqlite3_database_total_changes, 0); /* in amalgalite3_database.c */
     rb_define_method(cAS_Database, "last_error_code", am_sqlite3_database_last_error_code, 0); /* in amalgalite3_database.c */
     rb_define_method(cAS_Database, "last_error_message", am_sqlite3_database_last_error_message, 0); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "define_function", am_sqlite3_database_define_function, 2); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "remove_function", am_sqlite3_database_remove_function, 2); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "define_aggregate", am_sqlite3_database_define_aggregate, 3); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "remove_aggregate", am_sqlite3_database_remove_aggregate, 3); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "busy_handler", am_sqlite3_database_busy_handler, 1); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "progress_handler", am_sqlite3_database_progress_handler, 2); /* in amalgalite3_database.c */
+    rb_define_method(cAS_Database, "interrupt!", am_sqlite3_database_interrupt_bang, 0); /* in amalgalite3_database.c */
+
 
     /*
      * Ecapuslate a SQLite3 Database stat