extralite 2.3 → 2.4

data/ext/extralite/database.c

@@ -1,11 +1,14 @@
 #include <stdio.h>
+#include <stdlib.h>
 #include "extralite.h"
 
 VALUE cDatabase;
+VALUE cBlob;
 VALUE cError;
 VALUE cSQLError;
 VALUE cBusyError;
 VALUE cInterruptError;
+VALUE cParameterError;
 VALUE eArgumentError;
 
 ID ID_bind;
@@ -13,7 +16,6 @@ ID ID_call;
 ID ID_keys;
 ID ID_new;
 ID ID_strip;
-ID ID_to_s;
 
 VALUE SYM_read_only;
 
@@ -21,6 +23,11 @@ static size_t Database_size(const void *ptr) {
   return sizeof(Database_t);
 }
 
+static void Database_mark(void *ptr) {
+  Database_t *db = ptr;
+  rb_gc_mark(db->trace_block);
+}
+
 static void Database_free(void *ptr) {
   Database_t *db = ptr;
   if (db->sqlite3_db) sqlite3_close_v2(db->sqlite3_db);
@@ -29,8 +36,8 @@ static void Database_free(void *ptr) {
 
 static const rb_data_type_t Database_type = {
     "Database",
-    {0, Database_free, Database_size,},
-    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+    {Database_mark, Database_free, Database_size,},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
 };
 
 static VALUE Database_allocate(VALUE klass) {
@@ -48,7 +55,7 @@ inline Database_t *self_to_database(VALUE self) {
 inline Database_t *self_to_open_database(VALUE self) {
   Database_t *db = self_to_database(self);
   if (!(db)->sqlite3_db) rb_raise(cError, "Database is closed");
-  
+
   return db;
 }
 
@@ -118,6 +125,7 @@ VALUE Database_initialize(int argc, VALUE *argv, VALUE self) {
 #endif
 
   db->trace_block = Qnil;
+  db->gvl_release_threshold = DEFAULT_GVL_RELEASE_THRESHOLD;
 
   return Qnil;
 }
@@ -178,8 +186,8 @@ static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VA
   RB_GC_GUARD(sql);
 
   bind_all_parameters(stmt, argc - 1, argv + 1);
-  query_ctx ctx = { self, db->sqlite3_db, stmt, Qnil, QUERY_MODE(QUERY_MULTI_ROW), ALL_ROWS };
-
+  query_ctx ctx = QUERY_CTX(self, db, stmt, Qnil, QUERY_MODE(QUERY_MULTI_ROW), ALL_ROWS);
+  
   return rb_ensure(SAFE(call), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
 
@@ -190,18 +198,18 @@ static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VA
  * Runs a query returning rows as hashes (with symbol keys). If a block is
  * given, it will be called for each row. Otherwise, an array containing all
  * rows is returned.
- * 
+ *
  * Query parameters to be bound to placeholders in the query can be specified as
  * a list of values or as a hash mapping parameter names to values. When
  * parameters are given as an array, the query should specify parameters using
  * `?`:
- * 
+ *
  *     db.query('select * from foo where x = ?', 42)
  *
  * Named placeholders are specified using `:`. The placeholder values are
  * specified using a hash, where keys are either strings are symbols. String
  * keys can include or omit the `:` prefix. The following are equivalent:
- * 
+ *
  *     db.query('select * from foo where x = :bar', bar: 42)
  *     db.query('select * from foo where x = :bar', 'bar' => 42)
  *     db.query('select * from foo where x = :bar', ':bar' => 42)
@@ -355,7 +363,7 @@ VALUE Database_execute_multi(VALUE self, VALUE sql, VALUE params_array) {
 
   // prepare query ctx
   prepare_single_stmt(db->sqlite3_db, &stmt, sql);
-  query_ctx ctx = { self, db->sqlite3_db, stmt, params_array, QUERY_MODE(QUERY_MULTI_ROW), ALL_ROWS };
+  query_ctx ctx = QUERY_CTX(self, db, stmt, params_array, QUERY_MULTI_ROW, ALL_ROWS);
 
   return rb_ensure(SAFE(safe_execute_multi), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
@@ -391,10 +399,10 @@ VALUE Database_changes(VALUE self) {
   return INT2FIX(sqlite3_changes(db->sqlite3_db));
 }
 
-/* call-seq:
- *   db.filename -> string
+/* call-seq: db.filename -> string db.filename(db_name) -> string
  *
- * Returns the database filename.
+ * Returns the database filename. If db_name is given, returns the filename for
+ * the respective attached database.
  */
 VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
   const char *db_name;
@@ -480,13 +488,13 @@ typedef struct {
 #define BACKUP_STEP_MAX_PAGES 16
 #define BACKUP_SLEEP_MS       100
 
-void *backup_step_without_gvl(void *ptr) {
+void *backup_step_impl(void *ptr) {
   backup_ctx *ctx = (backup_ctx *)ptr;
   ctx->rc = sqlite3_backup_step(ctx->backup, BACKUP_STEP_MAX_PAGES);
   return NULL;
 }
 
-void *backup_sleep_without_gvl(void *unused) {
+void *backup_sleep_impl(void *unused) {
   sqlite3_sleep(BACKUP_SLEEP_MS);
   return NULL;
 }
@@ -496,7 +504,7 @@ VALUE backup_safe_iterate(VALUE ptr) {
   int done = 0;
 
   while (!done) {
-    rb_thread_call_without_gvl(backup_step_without_gvl, (void *)ctx, RUBY_UBF_IO, 0);
+    gvl_call(GVL_RELEASE, backup_step_impl, (void *)ctx);
     switch(ctx->rc) {
       case SQLITE_DONE:
         if (ctx->block_given) {
@@ -514,7 +522,7 @@ VALUE backup_safe_iterate(VALUE ptr) {
         continue;
       case SQLITE_BUSY:
       case SQLITE_LOCKED:
-        rb_thread_call_without_gvl(backup_sleep_without_gvl, NULL, RUBY_UBF_IO, 0);
+        gvl_call(GVL_RELEASE, backup_sleep_impl, NULL);
         continue;
       default:
         rb_raise(cError, "%s", sqlite3_errstr(ctx->rc));
@@ -689,7 +697,7 @@ VALUE Database_total_changes(VALUE self) {
 VALUE Database_trace(VALUE self) {
   Database_t *db = self_to_open_database(self);
 
-  db->trace_block = rb_block_given_p() ? rb_block_proc() : Qnil;
+  RB_OBJ_WRITE(self, &db->trace_block, rb_block_given_p() ? rb_block_proc() : Qnil);
   return self;
 }
 
@@ -734,11 +742,51 @@ VALUE Database_error_offset(VALUE self) {
  * @return [String] string representation
  */
 VALUE Database_inspect(VALUE self) {
+  Database_t *db = self_to_database(self);
   VALUE cname = rb_class_name(CLASS_OF(self));
-  VALUE filename = Database_filename(0, NULL, self);
-  if (RSTRING_LEN(filename) == 0) filename = rb_str_new_literal(":memory:");
 
-  return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, filename);
+  if (!(db)->sqlite3_db)
+    return rb_sprintf("#<%"PRIsVALUE":%p (closed)>", cname, (void*)self);
+  else {
+    VALUE filename = Database_filename(0, NULL, self);
+    if (RSTRING_LEN(filename) == 0) filename = rb_str_new_literal(":memory:");
+    return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, filename);
+  }
+}
+
+/* Returns the database's GVL release threshold.
+ *
+ * @return [Integer] GVL release threshold
+ */
+VALUE Database_gvl_release_threshold_get(VALUE self) {
+  Database_t *db = self_to_open_database(self);
+  return INT2NUM(db->gvl_release_threshold);
+}
+
+/* Sets the database's GVL release threshold. To always hold the GVL while
+ * running a query, set the threshold to 0. To release the GVL on each record,
+ * set the threshold to 1. Larger values mean the GVL will be released less
+ * often, e.g. a value of 10 means the GVL will be released every 10 records
+ * iterated. A value of nil sets the threshold to the default value, which is
+ * currently 1000.
+ *
+ * @return [Integer, nil] New GVL release threshold
+ */
+VALUE Database_gvl_release_threshold_set(VALUE self, VALUE value) {
+  Database_t *db = self_to_open_database(self);
+
+  switch (TYPE(value)) {
+    case T_FIXNUM:
+      db->gvl_release_threshold = NUM2INT(value);
+      break;
+    case T_NIL:
+      db->gvl_release_threshold = DEFAULT_GVL_RELEASE_THRESHOLD;
+      break;
+    default:
+      rb_raise(eArgumentError, "Invalid GVL release threshold value (expect integer or nil)");
+  }
+
+  return INT2NUM(db->gvl_release_threshold);
 }
 
 void Init_ExtraliteDatabase(void) {
@@ -765,6 +813,8 @@ void Init_ExtraliteDatabase(void) {
   rb_define_method(cDatabase, "execute", Database_execute, -1);
   rb_define_method(cDatabase, "execute_multi", Database_execute_multi, 2);
   rb_define_method(cDatabase, "filename", Database_filename, -1);
+  rb_define_method(cDatabase, "gvl_release_threshold", Database_gvl_release_threshold_get, 0);
+  rb_define_method(cDatabase, "gvl_release_threshold=", Database_gvl_release_threshold_set, 1);
   rb_define_method(cDatabase, "initialize", Database_initialize, -1);
   rb_define_method(cDatabase, "inspect", Database_inspect, 0);
   rb_define_method(cDatabase, "interrupt", Database_interrupt, 0);
@@ -787,14 +837,13 @@ void Init_ExtraliteDatabase(void) {
   rb_define_method(cDatabase, "load_extension", Database_load_extension, 1);
 #endif
 
+  cBlob = rb_define_class_under(mExtralite, "Blob", rb_cString);
+
   cError = rb_define_class_under(mExtralite, "Error", rb_eStandardError);
   cSQLError = rb_define_class_under(mExtralite, "SQLError", cError);
   cBusyError = rb_define_class_under(mExtralite, "BusyError", cError);
   cInterruptError = rb_define_class_under(mExtralite, "InterruptError", cError);
-  rb_gc_register_mark_object(cError);
-  rb_gc_register_mark_object(cSQLError);
-  rb_gc_register_mark_object(cBusyError);
-  rb_gc_register_mark_object(cInterruptError);
+  cParameterError = rb_define_class_under(mExtralite, "ParameterError", cError);
 
   eArgumentError = rb_const_get(rb_cObject, rb_intern("ArgumentError"));
 
@@ -803,7 +852,6 @@ void Init_ExtraliteDatabase(void) {
   ID_keys   = rb_intern("keys");
   ID_new    = rb_intern("new");
   ID_strip  = rb_intern("strip");
-  ID_to_s   = rb_intern("to_s");
 
   SYM_read_only = ID2SYM(rb_intern("read_only"));
   rb_gc_register_mark_object(SYM_read_only);

data/ext/extralite/extralite.h

@@ -23,17 +23,18 @@
 extern VALUE cDatabase;
 extern VALUE cQuery;
 extern VALUE cIterator;
+extern VALUE cBlob;
 
 extern VALUE cError;
 extern VALUE cSQLError;
 extern VALUE cBusyError;
 extern VALUE cInterruptError;
+extern VALUE cParameterError;
 
 extern ID ID_call;
 extern ID ID_keys;
 extern ID ID_new;
 extern ID ID_strip;
-extern ID ID_to_s;
 
 extern VALUE SYM_hash;
 extern VALUE SYM_ary;
@@ -42,6 +43,7 @@ extern VALUE SYM_single_column;
 typedef struct {
   sqlite3 *sqlite3_db;
   VALUE   trace_block;
+  int     gvl_release_threshold;
 } Database_t;
 
 typedef struct {
@@ -79,19 +81,22 @@ typedef struct {
   enum query_mode mode;
   int             max_rows;
   int             eof;
+  int             gvl_release_threshold;
+  int             step_count;
 } query_ctx;
 
-typedef struct {
-  VALUE           dst;
-  VALUE           src;
-  sqlite3_backup  *p;
-} backup_t;
+enum gvl_mode {
+  GVL_RELEASE,
+  GVL_HOLD
+};
 
-#define TUPLE_MAX_EMBEDDED_VALUES 20
 #define ALL_ROWS -1
 #define SINGLE_ROW -2
 #define QUERY_MODE(default) (rb_block_given_p() ? QUERY_YIELD : default)
 #define MULTI_ROW_P(mode) (mode == QUERY_MULTI_ROW)
+#define QUERY_CTX(self, db, stmt, params, mode, max_rows) \
+  { self, db->sqlite3_db, stmt, params, mode, max_rows, 0, db->gvl_release_threshold, 0 }
+#define DEFAULT_GVL_RELEASE_THRESHOLD 1000
 
 extern rb_encoding *UTF8_ENCODING;
 
@@ -126,4 +131,6 @@ VALUE cleanup_stmt(query_ctx *ctx);
 sqlite3 *Database_sqlite3_db(VALUE self);
 Database_t *self_to_database(VALUE self);
 
-#endif /* EXTRALITE_H */
+void *gvl_call(enum gvl_mode mode, void *(*fn)(void *), void *data);
+
+#endif /* EXTRALITE_H */

data/ext/extralite/iterator.c

@@ -52,7 +52,7 @@ static inline enum iterator_mode symbol_to_mode(VALUE sym) {
  * iteration mode is one of: `:hash`, `:ary`, or `:single_column`. An iterator
  * is normally returned from one of the methods `Query#each`/`Query#each_hash`,
  * `Query#each_ary` or `Query#each_single_column` when called without a block:
- * 
+ *
  *     iterator = query.each
  *     ...
  *
@@ -115,12 +115,12 @@ inline next_method mode_to_next_method(enum iterator_mode mode) {
 
 /* Returns the next 1 or more rows from the associated query's result set
  * according to the iteration mode, i.e. as a hash, an array or a single value.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next()
@@ -152,7 +152,7 @@ inline to_a_method mode_to_to_a_method(enum iterator_mode mode) {
 
 /* Returns all rows from the associated query's result set according to the
  * iteration mode, i.e. as a hash, an array or a single value.
- * 
+ *
  * @return [Array] array of query result set rows
  */
 VALUE Iterator_to_a(VALUE self) {
@@ -180,7 +180,7 @@ inline VALUE mode_to_symbol(Iterator_t *iterator) {
 VALUE Iterator_inspect(VALUE self) {
   VALUE cname = rb_class_name(CLASS_OF(self));
   VALUE sym = mode_to_symbol(self_to_iterator(self));
-  
+
   return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, sym);
 }
 

data/ext/extralite/query.c

@@ -33,7 +33,7 @@ static void Query_free(void *ptr) {
 static const rb_data_type_t Query_type = {
     "Query",
     {Query_mark, Query_free, Query_size,},
-    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
 };
 
 static VALUE Query_allocate(VALUE klass) {
@@ -67,10 +67,12 @@ VALUE Query_initialize(VALUE self, VALUE db, VALUE sql) {
   if (!RSTRING_LEN(sql))
     rb_raise(cError, "Cannot prepare an empty SQL query");
 
+  RB_OBJ_WRITE(self, &query->db, db);
+  RB_OBJ_WRITE(self, &query->sql, sql);
+
   query->db = db;
   query->db_struct = self_to_database(db);
   query->sqlite3_db = Database_sqlite3_db(db);
-  query->sql = sql;
   query->stmt = NULL;
   query->closed = 0;
   query->eof = 0;
@@ -134,14 +136,14 @@ VALUE Query_reset(VALUE self) {
  * Bound parameters can be specified as a list of values or as a hash mapping
  * parameter names to values. When parameters are given as a splatted array, the
  * query should specify parameters using `?`:
- * 
+ *
  *     query = db.prepare('select * from foo where x = ?')
  *     query.bind(42)
  *
  * Named placeholders are specified using `:`. The placeholder values are
  * specified using a hash, where keys are either strings are symbols. String
  * keys can include or omit the `:` prefix. The following are equivalent:
- * 
+ *
  *     query = db.prepare('select * from foo where x = :bar')
  *     query.bind(bar: 42)
  *
@@ -171,19 +173,18 @@ VALUE Query_eof_p(VALUE self) {
 static inline VALUE Query_perform_next(VALUE self, int max_rows, VALUE (*call)(query_ctx *)) {
   Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
-  
+
   if (!query->stmt) query_reset(query);
   if (query->eof) return rb_block_given_p() ? self : Qnil;
 
-  query_ctx ctx = {
+  query_ctx ctx = QUERY_CTX(
     self,
-    query->sqlite3_db,
+    query->db_struct,
     query->stmt,
     Qnil,
     QUERY_MODE(max_rows == SINGLE_ROW ? QUERY_SINGLE_ROW : QUERY_MULTI_ROW),
-    MAX_ROWS(max_rows),
-    0
-  };
+    MAX_ROWS(max_rows)
+  );
   VALUE result = call(&ctx);
   query->eof = ctx.eof;
   return (ctx.mode == QUERY_YIELD) ? self : result;
@@ -193,12 +194,12 @@ static inline VALUE Query_perform_next(VALUE self, int max_rows, VALUE (*call)(q
 
 /* Returns the next 1 or more rows from the associated query's result set as a
  * hash.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next()
@@ -219,12 +220,12 @@ VALUE Query_next_hash(int argc, VALUE *argv, VALUE self) {
 
 /* Returns the next 1 or more rows from the associated query's result set as an
  * array.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next_ary()
@@ -241,12 +242,12 @@ VALUE Query_next_ary(int argc, VALUE *argv, VALUE self) {
 /* Returns the next 1 or more rows from the associated query's result set as an
  * single values. If the result set contains more than one column an error is
  * raised.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next_ary()
@@ -261,7 +262,7 @@ VALUE Query_next_single_column(int argc, VALUE *argv, VALUE self) {
 }
 
 /* Returns all rows in the associated query's result set as hashes.
- * 
+ *
  * @overload to_a()
  *   @return [Array<Hash>] all rows
  * @overload to_a_hash
@@ -274,7 +275,7 @@ VALUE Query_to_a_hash(VALUE self) {
 }
 
 /* Returns all rows in the associated query's result set as arrays.
- * 
+ *
  * @return [Array<Array>] all rows
  */
 VALUE Query_to_a_ary(VALUE self) {
@@ -285,7 +286,7 @@ VALUE Query_to_a_ary(VALUE self) {
 
 /* Returns all rows in the associated query's result set as single values. If
  * the result set contains more than one column an error is raised.
- * 
+ *
  * @return [Array<Object>] all rows
  */
 VALUE Query_to_a_single_column(VALUE self) {
@@ -297,7 +298,7 @@ VALUE Query_to_a_single_column(VALUE self) {
 /* Iterates through the result set, passing each row to the given block as a
  * hash. If no block is given, returns a `Extralite::Iterator` instance in hash
  * mode.
- * 
+ *
  * @return [Extralite::Query, Extralite::Iterator] self or an iterator if no block is given
  */
 VALUE Query_each_hash(VALUE self) {
@@ -311,7 +312,7 @@ VALUE Query_each_hash(VALUE self) {
 /* Iterates through the result set, passing each row to the given block as an
  * array. If no block is given, returns a `Extralite::Iterator` instance in
  * array mode.
- * 
+ *
  * @return [Extralite::Query, Extralite::Iterator] self or an iterator if no block is given
  */
 VALUE Query_each_ary(VALUE self) {
@@ -326,7 +327,7 @@ VALUE Query_each_ary(VALUE self) {
  * single value. If the result set contains more than one column an error is
  * raised. If no block is given, returns a `Extralite::Iterator` instance in
  * single column mode.
- * 
+ *
  * @return [Extralite::Query, Extralite::Iterator] self or an iterator if no block is given
  */
 VALUE Query_each_single_column(VALUE self) {
@@ -388,7 +389,14 @@ VALUE Query_execute_multi(VALUE self, VALUE parameters) {
   if (!query->stmt)
     prepare_single_stmt(query->sqlite3_db, &query->stmt, query->sql);
 
-  query_ctx ctx = { self, query->sqlite3_db, query->stmt, parameters, QUERY_MODE(QUERY_MULTI_ROW), ALL_ROWS };
+  query_ctx ctx = QUERY_CTX(
+    self,
+    query->db_struct,
+    query->stmt,
+    parameters,
+    QUERY_MODE(QUERY_MULTI_ROW),
+    ALL_ROWS
+  );
   return safe_execute_multi(&ctx);
 }
 
@@ -405,7 +413,7 @@ VALUE Query_database(VALUE self) {
 }
 
 /* Returns the SQL string for the query.
- * 
+ *
  * @return [String] SQL string
  */
 VALUE Query_sql(VALUE self) {
@@ -414,7 +422,7 @@ VALUE Query_sql(VALUE self) {
 }
 
 /* Returns the column names for the query without running it.
- * 
+ *
  * @return [Array<Symbol>] column names
  */
 VALUE Query_columns(VALUE self) {
@@ -424,7 +432,7 @@ VALUE Query_columns(VALUE self) {
 }
 
 /* Closes the query. Attempting to run a closed query will raise an error.
- * 
+ *
  * @return [Extralite::Query] self
  */
 VALUE Query_close(VALUE self) {
@@ -438,7 +446,7 @@ VALUE Query_close(VALUE self) {
 }
 
 /* Returns true if the query is closed.
- * 
+ *
  * @return [boolean] true if query is closed
  */
 VALUE Query_closed_p(VALUE self) {
@@ -449,7 +457,7 @@ VALUE Query_closed_p(VALUE self) {
 /* Returns the current [status
  * value](https://sqlite.org/c3ref/c_stmtstatus_counter.html) for the given op.
  * To reset the value, pass true as reset.
- * 
+ *
  * @overload status(op)
  *   @param op [Integer] status op
  *   @return [Integer] current status value for the given op
@@ -486,7 +494,7 @@ VALUE Query_inspect(VALUE self) {
     rb_str_cat2(sql, "...");
   }
   sql = rb_funcall(sql, ID_inspect, 0);
-    
+
   RB_GC_GUARD(sql);
   return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, sql);
 }

data/lib/extralite/version.rb

@@ -1,4 +1,4 @@
 module Extralite
   # Extralite version
-  VERSION = '2.3'
+  VERSION = '2.4'
 end

data/lib/extralite.rb

@@ -25,6 +25,10 @@ module Extralite
   class InterruptError < Error
   end
 
+  # An exception raised when an Extralite doesn't know how to bind a parameter to a query
+  class ParameterError < Error
+  end
+
   # An SQLite database
   class Database
     # @!visibility private
@@ -52,6 +56,29 @@ module Extralite
       value.is_a?(Hash) ? pragma_set(value) : pragma_get(value)
     end
 
+    # Starts a transaction and runs the given block. If an exception is raised
+    # in the block, the transaction is rolled back. Otherwise, the transaction
+    # is commited after running the block.
+    #
+    #     db.transaction do
+    #       db.execute('insert into foo values (1, 2, 3)')
+    #       raise if db.query_single_value('select x from bar') > 42
+    #     end
+    #
+    # @param mode [Symbol, String] transaction mode (deferred, immediate or exclusive). Defaults to immediate.
+    # @return [Any] the given block's return value
+    def transaction(mode = :immediate)
+      execute "begin #{mode} transaction"
+    
+      abort = false
+      yield self
+    rescue
+      abort = true
+      raise
+    ensure
+      execute(abort ? 'rollback' : 'commit')
+    end
+
     private
 
     def pragma_set(values)

data/test/helper.rb

@@ -5,3 +5,5 @@ require 'extralite'
 require 'minitest/autorun'
 
 puts "sqlite3 version: #{Extralite.sqlite3_version}"
+
+IS_LINUX = RUBY_PLATFORM =~ /linux/