amalgalite 0.1.0 → 0.2.0

data/HISTORY

@@ -1,4 +1,21 @@
 = Changelog
-== Version 0.1.0 - 2008-06-20
+== Version 0.2.0 - 2008-07-04
+
+* Major Enhancements
+  * blob support, both incremental access and normal access
+
+* Minor Enhancements
+  * added examples/gem_db.rb script demonstrating taps and prepared statements
+  * added examples/schema-info.rb script demonstrating meta information
+  * added examples/blob.rb demonstrating incremental blob IO
+  * added acces to the SQLite3 errcode and errmsg api
+  
+* Bugfixes
+  * added taps.rb for requiring
+  * fixed prepared statement reset
+  * caught an error in executing prepared statements earlier in the process so
+    the correct error is reported
+
+== Version 0.1.0 - 2008-06-21
 
 * Initial public release

data/README

@@ -1,8 +1,9 @@
 == Amalgalite
 
-* Homepage[http://www.copiousfreetime.org/projects/amalgalite]
+* Homepage[http://copiousfreetime.rubyforge.org/amalgalite]
 * {Rubyforge Project}[http://rubyforge.org/projects/copiousfreetime/]
 * email jeremy at copiousfreetime dot org
+* git clone url git://github.com/copiousfreetime/amalgalite.git
 
 == INSTALL
 
@@ -10,10 +11,17 @@
 
 == DESCRIPTION
 
-Amalgalite embeds the SQLite database engine in a ruby extension.
+Amalgalite embeds the SQLite database engine in a ruby extension.  There is no
+need to install SQLite separately.  
 
-Scroll through Amalgalite::Database for a quick example, and a general overview
-of the API.
+Look in the examples/ directory to see
+
+* general usage
+* blob io
+* schema information
+
+Also Scroll through Amalgalite::Database for a quick example, and a general
+overview of the API.
 
 == CREDITS
 

data/ext/amalgalite3.c

@@ -185,6 +185,7 @@ void Init_amalgalite3()
     Init_amalgalite3_constants( );
     Init_amalgalite3_database( );
     Init_amalgalite3_statement( );
+    Init_amalgalite3_blob( );
 
  }
 

data/ext/amalgalite3.h

@@ -24,6 +24,14 @@ typedef struct am_sqlite3_stmt {
   VALUE         remaining_sql;
 } am_sqlite3_stmt;
 
+/* wrapper struct around the sqlite3_blob opaque ponter */
+typedef struct am_sqlite3_blob {
+  sqlite3_blob *blob;
+  sqlite3      *db;
+  int           length;
+  int           current_offset;
+} am_sqlite3_blob;
+
 
 /** module and classes **/
 extern VALUE mA;              /* module Amalgalite                     */
@@ -55,7 +63,7 @@ extern VALUE am_sqlite3_database_register_profile_tap(VALUE self, VALUE tap);
 /*----------------------------------------------------------------------
  * Prototype for Amalgalite::SQLite3::Statement 
  *---------------------------------------------------------------------*/
-extern VALUE cAS_Statement;   /* class  Amalgliate::SQLite3::Statement */
+extern VALUE cAS_Statement;   /* class  Amalgalite::SQLite3::Statement */
 
 extern VALUE am_sqlite3_statement_alloc(VALUE klass);
 extern void  am_sqlite3_statement_free(am_sqlite3_stmt* );
@@ -66,6 +74,7 @@ extern VALUE am_sqlite3_statement_column_count(VALUE self);
 extern VALUE am_sqlite3_statement_column_name(VALUE self, VALUE index);
 extern VALUE am_sqlite3_statement_column_decltype(VALUE self, VALUE index);
 extern VALUE am_sqlite3_statement_column_type(VALUE self, VALUE index);
+extern VALUE am_sqlite3_statement_column_blob(VALUE self, VALUE index);
 extern VALUE am_sqlite3_statement_column_text(VALUE self, VALUE index);
 extern VALUE am_sqlite3_statement_column_int(VALUE self, VALUE index);
 extern VALUE am_sqlite3_statement_column_int64(VALUE self, VALUE index);
@@ -81,11 +90,26 @@ extern VALUE am_sqlite3_statement_bind_parameter_count(VALUE self);
 extern VALUE am_sqlite3_statement_bind_parameter_index(VALUE self, VALUE parameter_name);
 extern VALUE am_sqlite3_statement_remaining_sql(VALUE self);
 extern VALUE am_sqlite3_statement_bind_text(VALUE self, VALUE position, VALUE value);
+extern VALUE am_sqlite3_statement_bind_blob(VALUE self, VALUE position, VALUE value);
+extern VALUE am_sqlite3_statement_bind_zeroblob(VALUE self, VALUE position, VALUE value);
 extern VALUE am_sqlite3_statement_bind_int(VALUE self, VALUE position, VALUE value);
 extern VALUE am_sqlite3_statement_bind_int64(VALUE self, VALUE position, VALUE value);
 extern VALUE am_sqlite3_statement_bind_double(VALUE self, VALUE position, VALUE value);
 extern VALUE am_sqlite3_statement_bind_null(VALUE self, VALUE position);
 
+/*----------------------------------------------------------------------
+ * Prototype for Amalgalite::SQLite3::Blob
+ *---------------------------------------------------------------------*/
+extern VALUE cAS_Blob; /* class Amalgalite::SQLite3::Blob */
+
+extern VALUE am_sqlite3_blob_alloc(VALUE klass);
+extern VALUE am_sqlite3_blob_initialize( VALUE self, VALUE db, VALUE db_name, VALUE table_name, VALUE column_name, VALUE rowid, VALUE flag) ;
+extern void  am_sqlite3_blob_free(am_sqlite3_blob* );
+extern VALUE am_sqlite3_blob_read(VALUE self, VALUE length);
+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);
+
 /***********************************************************************
  * Type conversion macros between sqlite data types and ruby types
  **********************************************************************/

data/ext/amalgalite3_blob.c

@@ -0,0 +1,238 @@
+#include "amalgalite3.h"
+/**
+ * Copyright (c) 2008 Jeremy Hinegardner
+ * All rights reserved.  See LICENSE and/or COPYING for details.
+ *
+ * vim: shiftwidth=4 
+ */ 
+
+VALUE cAS_Blob;   /* class  Amalgliate::SQLite3::Blob */
+
+/**
+ * call-seq:
+ *   Blob.new( database, table_name, column_name, row_id, flag ) -> Blob
+ *
+ * Create a new Blob object and associate it with the approriate, database,
+ * table, column and row.  +flag+ indicates if the Blob is to be opened for
+ * writing "w" or reading "r".
+ *
+ */
+VALUE am_sqlite3_blob_initialize( VALUE self, VALUE db, VALUE db_name, VALUE table_name, VALUE column_name, VALUE rowid, VALUE flag) 
+{
+    am_sqlite3_blob *am_blob;
+    int              rc;
+    am_sqlite3      *am_db;
+    char            *zDb      = StringValuePtr( db_name );
+    char            *zTable   = StringValuePtr( table_name );
+    char            *zColumn  = StringValuePtr( column_name );
+    sqlite3_int64    iRow     = NUM2SQLINT64( rowid )  ;
+    VALUE            flag_str = StringValue( flag );
+    int              flags    = 0;
+
+    /* extract the blob struct */
+    Data_Get_Struct(self, am_sqlite3_blob, am_blob);
+    
+    /* extract the sqlite3 db struct */
+    Data_Get_Struct(db, am_sqlite3, am_db);
+
+    /* make sure that the flags are valid, only 'r' or 'w' are allowed */
+    if ( ( RSTRING( flag_str )->len != 1) || 
+         ( ( 'r' != RSTRING( flag_str )->ptr[0] ) && 
+           ( 'w' != RSTRING( flag_str )->ptr[0] ))) {
+        rb_raise( eAS_Error, "Error opening Blob in db = %s, table = %s, column = %s, rowid = %d.  Invalid flag '%s'.  Must be either 'w' or 'r'\n",
+                             zDb, zTable, zColumn, iRow, RSTRING( flag_str )->ptr);
+    }
+
+    /* switch to write mode */
+    if ( 'w' == RSTRING( flag_str )->ptr[0] ) { 
+        flags = 1;
+    }
+
+    /* open the blob and associate the db to it */
+    rc = sqlite3_blob_open(am_db->db, zDb, zTable, zColumn, iRow, flags, &(am_blob->blob) );
+    if ( rc != SQLITE_OK ) {
+        rb_raise( eAS_Error, "Error opening Blob in db = %s, table = %s, column = %s, rowid = %ld  : [SQLITE_ERROR %d] %s\n", 
+                  zDb, zTable, zColumn, iRow, rc, sqlite3_errmsg( am_db->db ));
+    }
+    am_blob->length = sqlite3_blob_bytes( am_blob->blob );
+    am_blob->db = am_db->db;
+
+    /* if a block is given then yield self and close the blob when done */
+    if ( rb_block_given_p() ) {
+        rb_yield( self );
+        am_sqlite3_blob_close( self );
+        return Qnil;
+    } else {
+        return self;
+    }
+}
+
+/**
+ * call-seq:
+ *  blob.close -> nil
+ *
+ * Closes the blob.
+ */
+VALUE am_sqlite3_blob_close( VALUE self )
+{
+    am_sqlite3_blob *am_blob;
+    int              rc;
+    
+    Data_Get_Struct(self, am_sqlite3_blob, am_blob);
+    rc = sqlite3_blob_close( am_blob->blob );
+    if ( SQLITE_OK != rc ) {
+        rb_raise(eAS_Error, "Error closing blob: [SQLITE_ERROR %d] %s\n",
+                rc, sqlite3_errmsg( am_blob->db ));
+    }
+
+
+    return Qnil;
+}
+
+
+/**
+ * call-seq:
+ *  blob.length -> length in bytes of the blob
+ *
+ * Returns the number of bytes in the blob.
+ */
+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 );
+}
+
+/**
+ * call-seq:
+ *   blob.read( int ) -> String containting int number of  bytes or nil if eof.
+ *
+ * returns int number of bytes as a String from the database
+ */
+VALUE am_sqlite3_blob_read( VALUE self, VALUE length )
+{
+    am_sqlite3_blob *am_blob;
+    int             rc;
+    int              n = NUM2INT( length );
+    void           *buf = NULL;
+    VALUE          result;
+
+    Data_Get_Struct(self, am_sqlite3_blob, am_blob);
+
+    /* we have to be exact on the number of bytes to read.  n + current_offset
+     * cannot be larger than the blob's length
+     */
+    if ( (n + am_blob->current_offset > am_blob->length)) {
+        n = am_blob->length - am_blob->current_offset;
+    }
+
+    if ( am_blob->current_offset == am_blob->length ) {
+        return Qnil;
+    }
+
+    buf = (void *)malloc( n );
+    rc = sqlite3_blob_read( am_blob->blob, buf, n, am_blob->current_offset); 
+
+    if ( rc != SQLITE_OK ) {
+        rb_raise(eAS_Error, "Error reading %d bytes blob at offset %d: [SQLITE_ERROR %d] %s\n",
+                n, am_blob->current_offset, rc, sqlite3_errmsg( am_blob->db ));
+    }
+
+    am_blob->current_offset += n;
+
+    result = rb_str_new( (char*)buf, n );
+    free( buf );
+    return result;
+
+}
+
+/**
+ * call-seq:
+ *   blob.write( buf ) -> int
+ *
+ * writes the contents of the string buffer to the blob and returns the number
+ * of bytes written.
+ *
+ */
+VALUE am_sqlite3_blob_write( VALUE self, VALUE buf )
+{
+    am_sqlite3_blob *am_blob;
+    int              rc;
+    VALUE            str = StringValue( buf );
+    int              n   = RSTRING( str )->len;
+    char            *chk_buf = NULL;
+
+    Data_Get_Struct(self, am_sqlite3_blob, am_blob);
+
+    rc = sqlite3_blob_write( am_blob->blob, RSTRING(str)->ptr, n, am_blob->current_offset); 
+
+    if ( rc  != SQLITE_OK ) {
+        rb_raise(eAS_Error, "Error writing %d bytes blob at offset %d: [SQLITE_ERROR %d] %s\n",
+                n, am_blob->current_offset, rc, sqlite3_errmsg( am_blob->db ));
+    }
+
+    chk_buf = (char *) malloc( n  + 1);
+    chk_buf[n] = '\0';
+    sqlite3_blob_read( am_blob->blob, chk_buf, n, 0);
+
+    am_blob->current_offset += n;
+
+    return INT2FIX( n );
+
+}
+
+
+/***********************************************************************
+ * Ruby life cycle methods
+ ***********************************************************************/
+
+/*
+ * garbage collector free method for the am_sqlite3_blob structure
+ */
+void am_sqlite3_blob_free(am_sqlite3_blob* wrapper)
+{
+    free(wrapper);
+    return;
+}
+
+/*
+ * allocate the am_blob structure
+ */
+VALUE am_sqlite3_blob_alloc(VALUE klass)
+{
+    am_sqlite3_blob  *wrapper = ALLOC(am_sqlite3_blob);
+    VALUE             obj     = (VALUE)NULL;
+
+    wrapper->current_offset = 0;
+    wrapper->db             = NULL;
+    obj = Data_Wrap_Struct(klass, NULL, am_sqlite3_blob_free, wrapper);
+    return obj;
+}
+
+
+void Init_amalgalite3_blob( )
+{
+
+    /** :stopdoc:
+     * These calls are here just to allow for rdoc generation
+     * :startdoc:
+     */
+    VALUE ma  = rb_define_module("Amalgalite");
+    VALUE mas = rb_define_module_under(ma, "SQLite3");
+
+    /*
+     * Encapsulate the SQLite3 Statement handle in a class
+     */
+    cAS_Blob = rb_define_class_under( mas, "Blob", rb_cObject ); 
+    rb_define_alloc_func(cAS_Blob, am_sqlite3_blob_alloc); 
+    rb_define_method(cAS_Blob, "initialize", am_sqlite3_blob_initialize, 6); 
+    rb_define_method(cAS_Blob, "close", am_sqlite3_blob_close, 0); 
+    rb_define_method(cAS_Blob, "read", am_sqlite3_blob_read, 1); 
+    rb_define_method(cAS_Blob, "write", am_sqlite3_blob_write, 1); 
+    rb_define_method(cAS_Blob, "length", am_sqlite3_blob_length, 0); 
+}
+
+

data/ext/amalgalite3_database.c

@@ -163,6 +163,42 @@ VALUE am_sqlite3_database_row_changes(VALUE self)
     return INT2FIX(rc);
 }
 
+/**
+ * call-seq:
+ *    database.last_error_code -> Integer
+ *
+ * return the last error code that happened in the database
+ *
+ */
+VALUE am_sqlite3_database_last_error_code(VALUE self)
+{
+    am_sqlite3   *am_db;
+    int           code;
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    code = sqlite3_errcode( am_db->db );
+    
+    return INT2FIX( code );
+}
+
+/**
+ * call-seq:
+ *    database.last_error_message -> String
+ *
+ * return the last error message that happened in the database
+ *
+ */
+VALUE am_sqlite3_database_last_error_message(VALUE self)
+{
+    am_sqlite3   *am_db;
+    const char   *message;
+
+    Data_Get_Struct(self, am_sqlite3, am_db);
+    message = sqlite3_errmsg( am_db->db );
+    
+    return rb_str_new2( message );
+}
+
 /**
  * call-seq:
  *    database.total_changes -> Integer
@@ -211,6 +247,7 @@ VALUE am_sqlite3_database_prepare(VALUE self, VALUE rSQL)
 
     if ( tail != NULL ) {
         am_stmt->remaining_sql = rb_str_new2( tail );
+        rb_gc_register_address( &(am_stmt->remaining_sql) );
     } else {
         am_stmt->remaining_sql = Qnil;
     }
@@ -453,6 +490,8 @@ void Init_amalgalite3_database( )
     rb_define_method(cAS_Database, "table_column_metadata", am_sqlite3_database_table_column_metadata, 3); /* in amalgalite3_database.c */
     rb_define_method(cAS_Database, "row_changes", am_sqlite3_database_row_changes, 0); /* in amalgalite3_database.c */
     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 */
 
 }
 

data/ext/amalgalite3_statement.c

@@ -10,7 +10,7 @@ VALUE cAS_Statement;   /* class  Amalgliate::SQLite3::Statement */
 
 /**
  * call-seq:
- *     stmt.bind_null( position ) -> nil
+ *     stmt.bind_null( position ) -> int
  * 
  * bind a null value to the variable at postion.
  *
@@ -31,6 +31,58 @@ VALUE am_sqlite3_statement_bind_null(VALUE self, VALUE position )
 
     return INT2FIX(rc);
 }
+
+/**
+ * call-seq:
+ *    stmt.bind_zeroblob( position, length ) -> int
+ *
+ * bind a blob with +length+ filled with zeros to the position.  This is a Blob
+ * that will later filled in with incremental IO routines.
+ */
+VALUE am_sqlite3_statement_bind_zeroblob( VALUE self, VALUE position, VALUE length)
+{
+    am_sqlite3_stmt  *am_stmt;
+    int               pos = FIX2INT( position );
+    int               n = FIX2INT( length );
+    int               rc;
+
+    Data_Get_Struct(self, am_sqlite3_stmt, am_stmt);
+    rc = sqlite3_bind_zeroblob( am_stmt->stmt, pos, n );
+    if ( SQLITE_OK != rc ) {
+        rb_raise(eAS_Error, "Error binding zeroblob of length %d at position %d in statement: [SQLITE_ERROR %d] : %s\n",
+                n, pos,
+                rc, sqlite3_errmsg( sqlite3_db_handle( am_stmt->stmt) ));
+    }
+
+    return INT2FIX(rc);
+}
+
+
+/**
+ * call-seq:
+ *    stmt.bind_blob( position, blob ) -> int
+ *
+ * bind a blob to the variable at position.  This is a blob that is fully held
+ * in memory
+ */
+VALUE am_sqlite3_statement_bind_blob( VALUE self, VALUE position, VALUE blob )
+{
+    am_sqlite3_stmt  *am_stmt;
+    int               pos = FIX2INT( position );
+    VALUE             str = StringValue( blob );
+    int               rc;
+
+    Data_Get_Struct(self, am_sqlite3_stmt, am_stmt);
+    rc = sqlite3_bind_blob( am_stmt->stmt, pos, RSTRING( str )->ptr, RSTRING( str )->len, SQLITE_TRANSIENT);
+    if ( SQLITE_OK != rc ) {
+        rb_raise(eAS_Error, "Error binding blob at position %d in statement: [SQLITE_ERROR %d] : %s\n",
+                pos,
+                rc, sqlite3_errmsg( sqlite3_db_handle( am_stmt->stmt) ));
+    }
+
+    return INT2FIX(rc);
+}
+
 /**
  * call-seq:
  *     stmt.bind_double( position, value ) -> nil
@@ -121,7 +173,7 @@ VALUE am_sqlite3_statement_bind_text(VALUE self, VALUE position, VALUE value)
     int               rc;
 
     Data_Get_Struct(self, am_sqlite3_stmt, am_stmt);
-    rc = sqlite3_bind_text( am_stmt->stmt, pos, RSTRING(str)->ptr, RSTRING(str)->len, NULL );
+    rc = sqlite3_bind_text( am_stmt->stmt, pos, RSTRING(str)->ptr, RSTRING(str)->len, SQLITE_TRANSIENT);
     if ( SQLITE_OK != rc ) {
         rb_raise(eAS_Error, "Error binding [%s] to text at position %d in statement: [SQLITE_ERROR %d] : %s\n",
                 RSTRING(str)->ptr, pos,
@@ -324,6 +376,28 @@ VALUE am_sqlite3_statement_column_text(VALUE self, VALUE v_idx)
     return rb_str_new2( (const char*)sqlite3_column_text( am_stmt->stmt, idx ) );
 }
 
+/**
+ * call-seq:
+ *    stmt.column_blob( index ) -> String
+ *  
+ * Return the data in ith column of the result as a String.
+ *
+ */
+VALUE am_sqlite3_statement_column_blob(VALUE self, VALUE v_idx)
+{
+    am_sqlite3_stmt *am_stmt;
+    int              idx    = FIX2INT( v_idx );
+    const char      *data; 
+    long             length;
+
+    Data_Get_Struct(self, am_sqlite3_stmt, am_stmt);
+    data = sqlite3_column_blob( am_stmt->stmt, idx );
+    length = sqlite3_column_bytes( am_stmt->stmt, idx );
+    return rb_str_new( data, length );
+
+}
+
+
 /**
  * call-seq:
  *    stmt.column_double( index ) -> Float
@@ -470,6 +544,8 @@ VALUE am_sqlite3_statement_close( VALUE self )
         rb_raise(eAS_Error, "Failure to close statment : [SQLITE_ERROR %d] : %s\n",
                 rc, sqlite3_errmsg( sqlite3_db_handle( am_stmt->stmt) ));
     }
+
+    return Qnil;
 }
 
 /***********************************************************************
@@ -483,6 +559,10 @@ VALUE am_sqlite3_statement_close( VALUE self )
 void am_sqlite3_statement_free(am_sqlite3_stmt* wrapper)
 {
 
+    if ( Qnil != wrapper->remaining_sql ) {
+        rb_gc_unregister_address( &(wrapper->remaining_sql) );
+        wrapper->remaining_sql = Qnil;
+    }
     free(wrapper);
     return;
 }
@@ -524,6 +604,7 @@ void Init_amalgalite3_statement( )
     rb_define_method(cAS_Statement, "column_declared_type", am_sqlite3_statement_column_decltype, 1); 
     rb_define_method(cAS_Statement, "column_type", am_sqlite3_statement_column_type, 1); 
     rb_define_method(cAS_Statement, "column_text", am_sqlite3_statement_column_text, 1); 
+    rb_define_method(cAS_Statement, "column_blob", am_sqlite3_statement_column_blob, 1); 
     rb_define_method(cAS_Statement, "column_int", am_sqlite3_statement_column_int, 1); 
     rb_define_method(cAS_Statement, "column_int64", am_sqlite3_statement_column_int64, 1); 
     rb_define_method(cAS_Statement, "column_double", am_sqlite3_statement_column_double, 1); 
@@ -541,6 +622,8 @@ void Init_amalgalite3_statement( )
     rb_define_method(cAS_Statement, "bind_int64", am_sqlite3_statement_bind_int64, 2); 
     rb_define_method(cAS_Statement, "bind_double", am_sqlite3_statement_bind_double, 2); 
     rb_define_method(cAS_Statement, "bind_null", am_sqlite3_statement_bind_null, 1); 
+    rb_define_method(cAS_Statement, "bind_blob", am_sqlite3_statement_bind_blob, 2); 
+    rb_define_method(cAS_Statement, "bind_zeroblob", am_sqlite3_statement_bind_zeroblob, 2); 
 }