extralite 2.6 → 2.7

data/ext/extralite/database.c

@@ -16,14 +16,28 @@ ID ID_call;
 ID ID_each;
 ID ID_keys;
 ID ID_new;
+ID ID_pragma;
 ID ID_strip;
 ID ID_to_s;
 ID ID_track;
 
+VALUE SYM_at_least_once;
 VALUE SYM_gvl_release_threshold;
+VALUE SYM_once;
+VALUE SYM_none;
+VALUE SYM_normal;
+VALUE SYM_pragma;
 VALUE SYM_read_only;
-VALUE SYM_synchronous;
-VALUE SYM_wal_journal_mode;
+VALUE SYM_wal;
+
+struct progress_handler global_progress_handler = {
+  .mode       = PROGRESS_NONE,
+  .proc       = Qnil,
+  .period     = DEFAULT_PROGRESS_HANDLER_PERIOD,
+  .tick       = DEFAULT_PROGRESS_HANDLER_TICK,
+  .tick_count = 0,
+  .call_count = 0
+};
 
 #define DB_GVL_MODE(db) Database_prepare_gvl_mode(db)
 
@@ -34,13 +48,13 @@ static size_t Database_size(const void *ptr) {
 static void Database_mark(void *ptr) {
   Database_t *db = ptr;
   rb_gc_mark_movable(db->trace_proc);
-  rb_gc_mark_movable(db->progress_handler_proc);
+  rb_gc_mark_movable(db->progress_handler.proc);
 }
 
 static void Database_compact(void *ptr) {
   Database_t *db = ptr;
-  db->trace_proc = rb_gc_location(db->trace_proc);
-  db->progress_handler_proc = rb_gc_location(db->progress_handler_proc);
+  db->trace_proc            = rb_gc_location(db->trace_proc);
+  db->progress_handler.proc = rb_gc_location(db->progress_handler.proc);
 }
 
 static void Database_free(void *ptr) {
@@ -57,7 +71,10 @@ static const rb_data_type_t Database_type = {
 
 static VALUE Database_allocate(VALUE klass) {
   Database_t *db = ALLOC(Database_t);
-  db->sqlite3_db = 0;
+  db->sqlite3_db = NULL;
+  db->trace_proc = Qnil;
+  db->progress_handler.proc = Qnil;
+  db->progress_handler.mode = PROGRESS_NONE;
   return TypedData_Wrap_Struct(klass, &Database_type, db);
 }
 
@@ -78,12 +95,10 @@ inline sqlite3 *Database_sqlite3_db(VALUE self) {
   return self_to_database(self)->sqlite3_db;
 }
 
-/* call-seq:
- *   Extralite.sqlite3_version -> version
+/* Returns the sqlite3 library version used by Extralite.
  *
- * Returns the sqlite3 version used by Extralite.
+ * @return [String] SQLite version
  */
-
 VALUE Extralite_sqlite3_version(VALUE self) {
   return rb_str_new_cstr(sqlite3_version);
 }
@@ -100,40 +115,64 @@ default_flags:
   return SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
 }
 
-VALUE Database_execute(int argc, VALUE *argv, VALUE self);
-
 void Database_apply_opts(VALUE self, Database_t *db, VALUE opts) {
   VALUE value = Qnil;
 
+  // :gvl_release_threshold
   value = rb_hash_aref(opts, SYM_gvl_release_threshold);
   if (!NIL_P(value)) db->gvl_release_threshold = NUM2INT(value);
 
-  value = rb_hash_aref(opts, SYM_wal_journal_mode);
-  if (RTEST(value)) {
-    value = rb_str_new_literal("PRAGMA journal_mode=wal");
-    Database_execute(1, &value, self);
-  }
+  // :pragma
+  value = rb_hash_aref(opts, SYM_pragma);
+  if (!NIL_P(value)) rb_funcall(self, ID_pragma, 1, value);
 
-  value = rb_hash_aref(opts, SYM_synchronous);
+  // :wal
+  value = rb_hash_aref(opts, SYM_wal);
   if (RTEST(value)) {
-    value = rb_str_new_literal("PRAGMA synchronous=1");
-    Database_execute(1, &value, self);
+    int rc = sqlite3_exec(db->sqlite3_db, "PRAGMA journal_mode=wal", NULL, NULL, NULL);
+    if (rc != SQLITE_OK)
+      rb_raise(cError, "Failed to set WAL journaling mode: %s", sqlite3_errstr(rc));
+    rc = sqlite3_exec(db->sqlite3_db, "PRAGMA synchronous=1", NULL, NULL, NULL);
+    if (rc != SQLITE_OK)
+      rb_raise(cError, "Failed to set synchronous mode: %s", sqlite3_errstr(rc));
   }
+}
+
+int Database_progress_handler(void *ptr) {
+  Database_t *db = (Database_t *)ptr;
+  db->progress_handler.tick_count += db->progress_handler.tick;
+  if (db->progress_handler.tick_count < db->progress_handler.period)
+    goto done;
+
+  db->progress_handler.tick_count -= db->progress_handler.period;
+  db->progress_handler.call_count += 1;
+  rb_funcall(db->progress_handler.proc, ID_call, 0);
+done:
+  return 0;
+}
 
-  RB_GC_GUARD(value);
+int Database_busy_handler(void *ptr, int v) {
+  Database_t *db = (Database_t *)ptr;
+  rb_funcall(db->progress_handler.proc, ID_call, 1, Qtrue);
+  return 1;
 }
 
-/* Initializes a new SQLite database with the given path and options.
+/* Initializes a new SQLite database with the given path and options:
+ *
+ * - `:gvl_release_threshold` (`Integer`): sets the GVL release threshold (see
+ *   `#gvl_release_threshold=`).
+ * - `:pragma` (`Hash`): one or more pragmas to set upon opening the database.
+ * - `:read_only` (`true`/`false`): opens the database in read-only mode if true.
+ * - `:wal` (`true`/`false`): sets up the database for [WAL journaling
+ *   mode](https://www.sqlite.org/wal.html) by setting `PRAGMA journal_mode=wal`
+ *   and `PRAGMA synchronous=1`.
  *
  * @overload initialize(path)
  *   @param path [String] file path (or ':memory:' for memory database)
  *   @return [void]
- * @overload initialize(path, gvl_release_threshold: , read_only: , synchronous: , wal_journal_mode: )
+ * @overload initialize(path, gvl_release_threshold: , on_progress: , read_only: , wal: )
  *   @param path [String] file path (or ':memory:' for memory database)
- *   @param gvl_release_threshold [Integer] GVL release threshold
- *   @param read_only [boolean] true for opening the database for reading only
- *   @param synchronous [boolean] true to set PRAGMA synchronous=1
- *   @param wal_journal_mode [boolean] true to set PRAGMA journal_mode=wal
+ *   @param options [Hash] options for opening the database
  *   @return [void]
  */
 VALUE Database_initialize(int argc, VALUE *argv, VALUE self) {
@@ -147,6 +186,7 @@ VALUE Database_initialize(int argc, VALUE *argv, VALUE self) {
   int rc = sqlite3_open_v2(StringValueCStr(path), &db->sqlite3_db, flags, NULL);
   if (rc) {
     sqlite3_close_v2(db->sqlite3_db);
+    db->sqlite3_db = NULL;
     rb_raise(cError, "%s", sqlite3_errstr(rc));
   }
 
@@ -166,11 +206,19 @@ VALUE Database_initialize(int argc, VALUE *argv, VALUE self) {
 #endif
 
   db->trace_proc = Qnil;
-  db->progress_handler_proc = Qnil;
   db->gvl_release_threshold = DEFAULT_GVL_RELEASE_THRESHOLD;
 
-  if (!NIL_P(opts)) Database_apply_opts(self, db, opts);
+  db->progress_handler = global_progress_handler;
+  db->progress_handler.tick_count = 0;
+  db->progress_handler.call_count = 0;
+  if (db->progress_handler.mode != PROGRESS_NONE) {
+      db->gvl_release_threshold = -1;
+    if (db->progress_handler.mode != PROGRESS_ONCE)
+      sqlite3_progress_handler(db->sqlite3_db, db->progress_handler.tick, &Database_progress_handler, db);
+    sqlite3_busy_handler(db->sqlite3_db, &Database_busy_handler, db);
+  }
 
+  if (!NIL_P(opts)) Database_apply_opts(self, db, opts);
   return Qnil;
 }
 
@@ -184,10 +232,9 @@ VALUE Database_read_only_p(VALUE self) {
   return (open == 1) ? Qtrue : Qfalse;
 }
 
-/* call-seq:
- *   db.close -> db
- *
- * Closes the database.
+/* Closes the database.
+ * 
+ * @return [Extralite::Database] database
  */
 VALUE Database_close(VALUE self) {
   int rc;
@@ -198,7 +245,7 @@ VALUE Database_close(VALUE self) {
     rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
   }
 
-  db->sqlite3_db = 0;
+  db->sqlite3_db = NULL;
   return self;
 }
 
@@ -218,24 +265,40 @@ inline enum gvl_mode Database_prepare_gvl_mode(Database_t *db) {
   return db->gvl_release_threshold < 0 ? GVL_HOLD : GVL_RELEASE;
 }
 
-static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VALUE (*call)(query_ctx *)) {
+static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VALUE (*call)(query_ctx *), enum query_mode query_mode) {
   Database_t *db = self_to_open_database(self);
   sqlite3_stmt *stmt;
-  VALUE sql;
-
+  VALUE sql = Qnil;
+  VALUE transform = Qnil;
+  // transform mode is set and the first parameter is not a string, so we expect
+  // a transform.
+  int got_transform = (TYPE(argv[0]) != T_STRING);
+  
   // extract query from args
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
+  rb_check_arity(argc, got_transform ? 2 : 1, UNLIMITED_ARGUMENTS);
+
+  if (got_transform) {
+    transform = argv[0];
+    argc--;
+    argv++;
+  }
+
   sql = rb_funcall(argv[0], ID_strip, 0);
   if (RSTRING_LEN(sql) == 0) return Qnil;
 
-  TRACE_SQL(db, sql);
+  Database_issue_query(db, sql);
   prepare_multi_stmt(DB_GVL_MODE(db), db->sqlite3_db, &stmt, sql);
   RB_GC_GUARD(sql);
 
   bind_all_parameters(stmt, argc - 1, argv + 1);
-  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);
+  query_ctx ctx = QUERY_CTX(
+    self, sql, db, stmt, Qnil, transform,
+    query_mode, ROW_YIELD_OR_MODE(ROW_MULTI), ALL_ROWS
+  );
+
+  VALUE result = rb_ensure(SAFE(call), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
+  RB_GC_GUARD(result);
+  return result;
 }
 
 /* call-seq:
@@ -254,21 +317,46 @@ static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VA
  *     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:
+ * specified using keyword arguments:
  *
  *     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)
+ * 
+ * @overload query(sql, ...)
+ *   @param sql [String] SQL statement
+ *   @return [Array<Hash>, Integer] rows or total changes
+ * @overload query(transform, sql, ...)
+ *   @param transform [Proc] transform proc
+ *   @param sql [String] SQL statement
+ *   @return [Array<Hash>, Integer] rows or total changes
  */
-VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
-  return Database_perform_query(argc, argv, self, safe_query_hash);
+VALUE Database_query(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_hash, QUERY_HASH);
 }
 
-/* call-seq:
- *   db.query_ary(sql, *parameters, &block) -> [...]
+/* Runs a query and transforms rows through the given transform poc. Each row is
+ * provided to the transform proc as a list of values. If a block is given, it
+ * will be called for each row. Otherwise, an array containing all rows is
+ * returned.
  *
- * Runs a query returning rows as arrays. If a block is given, it will be called
+ * If a transform block is given, it is called for each row, with the row values
+ * splatted:
+ *
+ *     transform = ->(a, b, c) { a * 100 + b * 10 + c }
+ *     db.query_argv(transform, 'select a, b, c from foo where c = ?', 42)
+ *
+ * @overload query_argv(sql, ...)
+ *   @param sql [String] SQL statement
+ *   @return [Array<Array, any>, Integer] rows or total changes
+ * @overload query_argv(transform, sql, ...)
+ *   @param transform [Proc] transform proc
+ *   @param sql [String] SQL statement
+ *   @return [Array<Array, any>, Integer] rows or total changes
+ */
+VALUE Database_query_argv(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_argv, QUERY_ARGV);
+}
+
+/* Runs a query returning rows as arrays. 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
@@ -285,82 +373,95 @@ VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
  *     db.query_ary('select * from foo where x = :bar', bar: 42)
  *     db.query_ary('select * from foo where x = :bar', 'bar' => 42)
  *     db.query_ary('select * from foo where x = :bar', ':bar' => 42)
+ * 
+ * @overload query_ary(sql, ...)
+ *   @param sql [String] SQL statement
+ *   @return [Array<Array>, Integer] rows or total changes
+ * @overload query_ary(transform, sql, ...)
+ *   @param transform [Proc] transform proc
+ *   @param sql [String] SQL statement
+ *   @return [Array<Array>, Integer] rows or total changes
  */
 VALUE Database_query_ary(int argc, VALUE *argv, VALUE self) {
-  return Database_perform_query(argc, argv, self, safe_query_ary);
+  return Database_perform_query(argc, argv, self, safe_query_ary, QUERY_ARY);
 }
 
-/* call-seq:
- *   db.query_single_row(sql, *parameters) -> {...}
- *
- * Runs a query returning a single row as a hash.
+/* Runs a query returning a single row as a hash.
  *
  * 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_single_row('select * from foo where x = ?', 42)
+ *     db.query_single('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:
+ * specified using keyword arguments:
  *
- *     db.query_single_row('select * from foo where x = :bar', bar: 42)
- *     db.query_single_row('select * from foo where x = :bar', 'bar' => 42)
- *     db.query_single_row('select * from foo where x = :bar', ':bar' => 42)
+ *     db.query_single('select * from foo where x = :bar', bar: 42)
+ *
+ * @overload query_single(sql, ...) -> row
+ *   @param sql [String] SQL statement
+ *   @return [Array, any] row
+ * @overload query_single(transform, sql, ...) -> row
+ *   @param transform [Proc] transform proc
+ *   @param sql [String] SQL statement
+ *   @return [Array, any] row
  */
-VALUE Database_query_single_row(int argc, VALUE *argv, VALUE self) {
-  return Database_perform_query(argc, argv, self, safe_query_single_row);
+VALUE Database_query_single(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_single_row_hash, QUERY_HASH);
 }
 
-/* call-seq:
- *   db.query_single_column(sql, *parameters, &block) -> [...]
- *
- * Runs a query returning single column values. If a block is given, it will be called
- * for each value. Otherwise, an array containing all values is returned.
+/* Runs a query returning a single row as an array or a single value.
  *
  * 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_single_column('select x from foo where x = ?', 42)
+ *     db.query_single_argv('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:
+ * specified using keyword arguments:
  *
- *     db.query_single_column('select x from foo where x = :bar', bar: 42)
- *     db.query_single_column('select x from foo where x = :bar', 'bar' => 42)
- *     db.query_single_column('select x from foo where x = :bar', ':bar' => 42)
+ *     db.query_single_argv('select * from foo where x = :bar', bar: 42)
+ * 
+ * @overload query_single_argv(sql, ...) -> row
+ *   @param sql [String] SQL statement
+ *   @return [Array, any] row
+ * @overload query_single_argv(transform, sql, ...) -> row
+ *   @param transform [Proc] transform proc
+ *   @param sql [String] SQL statement
+ *   @return [Array, any] row
  */
-VALUE Database_query_single_column(int argc, VALUE *argv, VALUE self) {
-  return Database_perform_query(argc, argv, self, safe_query_single_column);
+VALUE Database_query_single_argv(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_single_row_argv, QUERY_ARGV);
 }
 
-/* call-seq:
- *   db.query_single_value(sql, *parameters) -> value
- *
- * Runs a query returning a single value from the first row.
+/* Runs a query returning a single row as an array.
  *
  * 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_single_value('select x from foo where x = ?', 42)
+ *     db.query_single_ary('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:
+ * specified using keyword arguments:
  *
- *     db.query_single_value('select x from foo where x = :bar', bar: 42)
- *     db.query_single_value('select x from foo where x = :bar', 'bar' => 42)
- *     db.query_single_value('select x from foo where x = :bar', ':bar' => 42)
+ *     db.query_single_ary('select * from foo where x = :bar', bar: 42)
+ * 
+ * @overload query_single_ary(sql, ...) -> row
+ *   @param sql [String] SQL statement
+ *   @return [Array, any] row
+ * @overload query_single_ary(transform, sql, ...) -> row
+ *   @param transform [Proc] transform proc
+ *   @param sql [String] SQL statement
+ *   @return [Array, any] row
  */
-VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
-  return Database_perform_query(argc, argv, self, safe_query_single_value);
+VALUE Database_query_single_ary(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_single_row_ary, QUERY_ARY);
 }
 
 /* call-seq:
@@ -377,21 +478,16 @@ VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
  *     db.execute('update foo set x = ? where y = ?', 42, 43)
  *
  * 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:
+ * specified using keyword arguments:
  *
  *     db.execute('update foo set x = :bar', bar: 42)
- *     db.execute('update foo set x = :bar', 'bar' => 42)
- *     db.execute('update foo set x = :bar', ':bar' => 42)
  */
 VALUE Database_execute(int argc, VALUE *argv, VALUE self) {
-  return Database_perform_query(argc, argv, self, safe_query_changes);
+  return Database_perform_query(argc, argv, self, safe_query_changes, QUERY_HASH);
 }
 
 /* call-seq:
- *   db.batch_execute(sql, params_array) -> changes
- *   db.batch_execute(sql, enumerable) -> changes
- *   db.batch_execute(sql, callable) -> changes
+ *   db.batch_execute(sql, params_source) -> changes
  *
  * Executes the given query for each list of parameters in the paramter source.
  * If an enumerable is given, it is iterated and each of its values is used as
@@ -425,18 +521,17 @@ VALUE Database_batch_execute(VALUE self, VALUE sql, VALUE parameters) {
   if (RSTRING_LEN(sql) == 0) return Qnil;
 
   prepare_single_stmt(DB_GVL_MODE(db), db->sqlite3_db, &stmt, sql);
-  query_ctx ctx = QUERY_CTX(self, db, stmt, parameters, QUERY_MULTI_ROW, ALL_ROWS);
+  query_ctx ctx = QUERY_CTX(
+    self, sql, db, stmt, parameters,
+    Qnil, QUERY_HASH, ROW_MULTI, ALL_ROWS
+  );
 
   return rb_ensure(SAFE(safe_batch_execute), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
 
 /* call-seq:
- *   db.batch_query(sql, params_array) -> rows
- *   db.batch_query(sql, enumerable) -> rows
- *   db.batch_query(sql, callable) -> rows
- *   db.batch_query(sql, params_array) { |rows| ... } -> changes
- *   db.batch_query(sql, enumerable) { |rows| ... } -> changes
- *   db.batch_query(sql, callable) { |rows| ... } -> changes
+ *   db.batch_query(sql, params_source) -> rows
+ *   db.batch_query(sql, params_source) { |rows| ... } -> changes
  *
  * Executes the given query for each list of parameters in the given paramter
  * source. If a block is given, it is called with the resulting rows for each
@@ -460,18 +555,17 @@ VALUE Database_batch_query(VALUE self, VALUE sql, VALUE parameters) {
   sqlite3_stmt *stmt;
 
   prepare_single_stmt(DB_GVL_MODE(db), db->sqlite3_db, &stmt, sql);
-  query_ctx ctx = QUERY_CTX(self, db, stmt, parameters, QUERY_MULTI_ROW, ALL_ROWS);
+  query_ctx ctx = QUERY_CTX(
+    self, sql, db, stmt, parameters,
+    Qnil, QUERY_HASH, ROW_MULTI, ALL_ROWS
+  );
 
   return rb_ensure(SAFE(safe_batch_query), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
 
 /* call-seq:
- *   db.batch_query_ary(sql, params_array) -> rows
- *   db.batch_query_ary(sql, enumerable) -> rows
- *   db.batch_query_ary(sql, callable) -> rows
- *   db.batch_query_ary(sql, params_array) { |rows| ... } -> changes
- *   db.batch_query_ary(sql, enumerable) { |rows| ... } -> changes
- *   db.batch_query_ary(sql, callable) { |rows| ... } -> changes
+ *   db.batch_query_ary(sql, params_source) -> rows
+ *   db.batch_query_ary(sql, params_source) { |rows| ... } -> changes
  *
  * Executes the given query for each list of parameters in the given paramter
  * source. If a block is given, it is called with the resulting rows for each
@@ -495,18 +589,17 @@ VALUE Database_batch_query_ary(VALUE self, VALUE sql, VALUE parameters) {
   sqlite3_stmt *stmt;
 
   prepare_single_stmt(DB_GVL_MODE(db), db->sqlite3_db, &stmt, sql);
-  query_ctx ctx = QUERY_CTX(self, db, stmt, parameters, QUERY_MULTI_ROW, ALL_ROWS);
+  query_ctx ctx = QUERY_CTX(
+    self, sql, db, stmt, parameters,
+    Qnil, QUERY_ARY, ROW_MULTI, ALL_ROWS
+  );
 
   return rb_ensure(SAFE(safe_batch_query_ary), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
 
 /* call-seq:
- *   db.batch_query_single_column(sql, params_array) -> rows
- *   db.batch_query_single_column(sql, enumerable) -> rows
- *   db.batch_query_single_column(sql, callable) -> rows
- *   db.batch_query_single_column(sql, params_array) { |rows| ... } -> changes
- *   db.batch_query_single_column(sql, enumerable) { |rows| ... } -> changes
- *   db.batch_query_single_column(sql, callable) { |rows| ... } -> changes
+ *   db.batch_query_argv(sql, params_source) -> rows
+ *   db.batch_query_argv(sql, params_source) { |rows| ... } -> changes
  *
  * Executes the given query for each list of parameters in the given paramter
  * source. If a block is given, it is called with the resulting rows for each
@@ -518,36 +611,37 @@ VALUE Database_batch_query_ary(VALUE self, VALUE sql, VALUE parameters) {
  *       [1, 2],
  *       [3, 4]
  *     ]
- *     db.batch_query_ary('insert into foo values (?, ?) returning baz', records)
+ *     db.batch_query_argv('insert into foo values (?, ?) returning baz', records)
  *     #=> [2, 4]
  * *
  * @param sql [String] query SQL
  * @param parameters [Array<Array, Hash>, Enumerable, Enumerator, Callable] parameters to run query with
  * @return [Array<any>, Integer] Total number of changes effected
  */
-VALUE Database_batch_query_single_column(VALUE self, VALUE sql, VALUE parameters) {
+VALUE Database_batch_query_argv(VALUE self, VALUE sql, VALUE parameters) {
   Database_t *db = self_to_open_database(self);
   sqlite3_stmt *stmt;
 
   prepare_single_stmt(DB_GVL_MODE(db), db->sqlite3_db, &stmt, sql);
-  query_ctx ctx = QUERY_CTX(self, db, stmt, parameters, QUERY_MULTI_ROW, ALL_ROWS);
+  query_ctx ctx = QUERY_CTX(
+    self, sql, db, stmt, parameters,
+    Qnil, QUERY_ARGV, ROW_MULTI, ALL_ROWS
+  );
 
-  return rb_ensure(SAFE(safe_batch_query_single_column), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
+  return rb_ensure(SAFE(safe_batch_query_argv), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
 }
 
-/* call-seq:
- *   db.columns(sql) -> columns
- *
- * Returns the column names for the given query, without running it.
+/* Returns the column names for the given query, without running it.
+ * 
+ * @return [Array<String>] column names
  */
 VALUE Database_columns(VALUE self, VALUE sql) {
-  return Database_perform_query(1, &sql, self, safe_query_columns);
+  return Database_perform_query(1, &sql, self, safe_query_columns, QUERY_HASH);
 }
 
-/* call-seq:
- *   db.last_insert_rowid -> int
- *
- * Returns the rowid of the last inserted row.
+/* Returns the rowid of the last inserted row.
+ * 
+ * @return [Integer] last rowid
  */
 VALUE Database_last_insert_rowid(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -555,10 +649,9 @@ VALUE Database_last_insert_rowid(VALUE self) {
   return INT2FIX(sqlite3_last_insert_rowid(db->sqlite3_db));
 }
 
-/* call-seq:
- *   db.changes -> int
- *
- * Returns the number of changes made to the database by the last operation.
+/* Returns the number of changes made to the database by the last operation.
+ * 
+ * @return [Integer] number of changes
  */
 VALUE Database_changes(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -566,10 +659,14 @@ VALUE Database_changes(VALUE self) {
   return INT2FIX(sqlite3_changes(db->sqlite3_db));
 }
 
-/* call-seq: db.filename -> string db.filename(db_name) -> string
- *
- * Returns the database filename. If db_name is given, returns the filename for
+/* Returns the database filename. If db_name is given, returns the filename for
  * the respective attached database.
+ * 
+ * @overload filename()
+ *   @return [String] database filename
+ * @overload filename(db_name)
+ *   @param db_name [String] attached database name
+ *   @return [String] database filename
  */
 VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
   const char *db_name;
@@ -582,10 +679,9 @@ VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
   return filename ? rb_str_new_cstr(filename) : Qnil;
 }
 
-/* call-seq:
- *   db.transaction_active? -> bool
- *
- * Returns true if a transaction is currently in progress.
+/* Returns true if a transaction is currently in progress.
+ * 
+ * @return [bool] is transaction in progress
  */
 VALUE Database_transaction_active_p(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -594,10 +690,10 @@ VALUE Database_transaction_active_p(VALUE self) {
 }
 
 #ifdef HAVE_SQLITE3_LOAD_EXTENSION
-/* call-seq:
- *   db.load_extension(path) -> db
- *
- * Loads an extension with the given path.
+/* Loads an extension with the given path.
+ * 
+ * @param path [String] extension file path
+ * @return [Extralite::Database] database
  */
 VALUE Database_load_extension(VALUE self, VALUE path) {
   Database_t *db = self_to_open_database(self);
@@ -614,30 +710,73 @@ VALUE Database_load_extension(VALUE self, VALUE path) {
 }
 #endif
 
+static inline VALUE Database_prepare(int argc, VALUE *argv, VALUE self, VALUE mode) {
+  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
+
+  VALUE args[] = { self, argv[0], mode};
+  VALUE query = rb_funcall_passing_block(cQuery, ID_new, 3, args);
+  if (argc > 1) rb_funcallv(query, ID_bind, argc - 1, argv + 1);
+  RB_GC_GUARD(query);
+  return query;
+}
+
 /* call-seq:
  *   db.prepare(sql) -> Extralite::Query
  *   db.prepare(sql, ...) -> Extralite::Query
+ *   db.prepare(sql, ...) { ... } -> Extralite::Query
  *
- * Creates a prepared statement with the given SQL query. If query parameters
- * are given, they are bound to the query.
+ * Creates a prepared query with the given SQL query in hash mode. If query
+ * parameters are given, they are bound to the query. If a block is given, it is
+ * used as a transform proc.
+ * 
+ * @param sql [String] SQL statement
+ * @return [Extralite::Query] prepared query
  */
-VALUE Database_prepare(int argc, VALUE *argv, VALUE self) {
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
-  VALUE query = rb_funcall(cQuery, ID_new, 2, self, argv[0]);
-  if (argc > 1) rb_funcallv(query, ID_bind, argc - 1, argv + 1);
-  RB_GC_GUARD(query);
-  return query;
+VALUE Database_prepare_hash(int argc, VALUE *argv, VALUE self) {
+  return Database_prepare(argc, argv, self, SYM_hash);
+}
+
+/* call-seq:
+ *   db.prepare_argv(sql) -> Extralite::Query
+ *   db.prepare_argv(sql, ...) -> Extralite::Query
+ *   db.prepare_argv(sql, ...) { ... } -> Extralite::Query
+ *
+ * Creates a prepared query with the given SQL query in argv mode. If query
+ * parameters are given, they are bound to the query. If a block is given, it is
+ * used as a transform proc.
+ * 
+ * @param sql [String] SQL statement
+ * @return [Extralite::Query] prepared query
+ */
+VALUE Database_prepare_argv(int argc, VALUE *argv, VALUE self) {
+  return Database_prepare(argc, argv, self, SYM_argv);
 }
 
 /* call-seq:
- *   db.interrupt -> db
+ *   db.prepare_ary(sql) -> Extralite::Query
+ *   db.prepare_ary(sql, ...) -> Extralite::Query
+ *   db.prepare_ary(sql, ...) { ... } -> Extralite::Query
  *
- * Interrupts a long running query. This method is to be called from a different
+ * Creates a prepared query with the given SQL query in ary mode. If query
+ * parameters are given, they are bound to the query. If a block is given, it is
+ * used as a transform proc.
+ * 
+ * @param sql [String] SQL statement
+ * @return [Extralite::Query] prepared query
+ */
+VALUE Database_prepare_ary(int argc, VALUE *argv, VALUE self) {
+  return Database_prepare(argc, argv, self, SYM_ary);
+}
+
+/* Interrupts a long running query. This method is to be called from a different
  * thread than the one running the query. Upon calling `#interrupt` the running
  * query will stop and raise an `Extralite::InterruptError` exception.
  *
  * It is not safe to call `#interrupt` on a database that is about to be closed.
- * For more information, consult the [sqlite3 API docs](https://sqlite.org/c3ref/interrupt.html).
+ * For more information, consult the [sqlite3 API
+ * docs](https://sqlite.org/c3ref/interrupt.html).
+ * 
+ * @return [Extralite::Database] database
  */
 VALUE Database_interrupt(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -711,16 +850,19 @@ VALUE backup_cleanup(VALUE ptr) {
   return Qnil;
 }
 
-/* call-seq:
- *   db.backup(dest) -> db
- *   db.backup(dest) { |remaining, total| } -> db
- *
- * Creates a backup of the database to the given destination, which can be
+/* Creates a backup of the database to the given destination, which can be
  * either a filename or a database instance. In order to monitor the backup
  * progress you can pass a block that will be called periodically by the backup
  * method with two arguments: the remaining page count, and the total page
  * count, which can be used to display the progress to the user or to collect
  * statistics.
+ * 
+ *     db_src.backup(db_dest) do |remaining, total|
+ *       puts "Backing up #{remaining}/#{total}"
+ *     end
+ * 
+ * @param dest [String, Extralite::Database] backup destination
+ * @return [Extralite::Database] source database
  */
 VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
   VALUE dst;
@@ -766,12 +908,17 @@ VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
-/* call-seq:
- *   Extralite.runtime_status(op[, reset]) -> [value, highwatermark]
- *
- * Returns runtime status values for the given op as an array containing the
+/* Returns runtime status values for the given op as an array containing the
  * current value and the high water mark value. To reset the high water mark,
  * pass true as reset.
+ *
+ * @overload runtime_status(op)
+ *   @param op [Integer] op
+ *   @return [Array<Integer>] array containing the value and high water mark
+ * @overload runtime_status(op, reset)
+ *   @param op [Integer] op
+ *   @param reset [Integer, bool] reset flag
+ *   @return [Array<Integer>] array containing the value and high water mark
  */
 VALUE Extralite_runtime_status(int argc, VALUE* argv, VALUE self) {
   VALUE op, reset;
@@ -785,12 +932,17 @@ VALUE Extralite_runtime_status(int argc, VALUE* argv, VALUE self) {
   return rb_ary_new3(2, LONG2FIX(cur), LONG2FIX(hwm));
 }
 
-/* call-seq:
- *   db.status(op[, reset]) -> [value, highwatermark]
- *
- * Returns database status values for the given op as an array containing the
+/* Returns database status values for the given op as an array containing the
  * current value and the high water mark value. To reset the high water mark,
  * pass true as reset.
+ * 
+ * @overload status(op)
+ *   @param op [Integer] op
+ *   @return [Array<Integer>] array containing the value and high water mark
+ * @overload status(op, reset)
+ *   @param op [Integer] op
+ *   @param reset [Integer, bool] reset flag
+ *   @return [Array<Integer>] array containing the value and high water mark
  */
 VALUE Database_status(int argc, VALUE *argv, VALUE self) {
   VALUE op, reset;
@@ -806,12 +958,16 @@ VALUE Database_status(int argc, VALUE *argv, VALUE self) {
   return rb_ary_new3(2, INT2NUM(cur), INT2NUM(hwm));
 }
 
-/* call-seq:
- *   db.limit(category) -> value
- *   db.limit(category, new_value) -> prev_value
- *
- * Returns the current limit for the given category. If a new value is given,
+/* Returns the current limit for the given category. If a new value is given,
  * sets the limit to the new value and returns the previous value.
+ * 
+ * @overload limit(category)
+ *   @param category [Integer] category
+ *   @return [Integer] limit value
+ * @overload limit(category, new_value)
+ *   @param category [Integer] category
+ *   @param new_value [Integer] new value
+ *   @return [Integer] old value
  */
 VALUE Database_limit(int argc, VALUE *argv, VALUE self) {
   VALUE category, new_value;
@@ -827,12 +983,18 @@ VALUE Database_limit(int argc, VALUE *argv, VALUE self) {
   return INT2NUM(value);
 }
 
-/* call-seq:
- *   db.busy_timeout=(sec) -> db
- *   db.busy_timeout=nil -> db
+/* Sets the busy timeout for the database, in seconds or fractions thereof. To
+ * disable the busy timeout, set it to 0 or nil. When the busy timeout is set to
+ * a value larger than zero, running a query when the database is locked will
+ * cause the program to wait for the database to become available. If the
+ * database is still locked when the timeout period has elapsed, the query will
+ * fail with a `Extralite::BusyError` exception.
+ * 
+ * Setting the busy timeout allows other threads to run while waiting for the
+ * database to become available. See also `#on_progress`.
  *
- * Sets the busy timeout for the database, in seconds or fractions thereof. To
- * disable the busy timeout, set it to 0 or nil.
+ * @param sec [Number, nil] timeout value
+ * @return [Extralite::Database] database
  */
 VALUE Database_busy_timeout_set(VALUE self, VALUE sec) {
   Database_t *db = self_to_open_database(self);
@@ -844,10 +1006,9 @@ VALUE Database_busy_timeout_set(VALUE self, VALUE sec) {
   return self;
 }
 
-/* call-seq:
- *   db.total_changes -> value
- *
- * Returns the total number of changes made to the database since opening it.
+/* Returns the total number of changes made to the database since opening it.
+ * 
+ * @return [Integer] total changes
  */
 VALUE Database_total_changes(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -856,12 +1017,10 @@ VALUE Database_total_changes(VALUE self) {
   return INT2NUM(value);
 }
 
-/* call-seq:
- *   db.trace { |sql| } -> db
- *   db.trace -> db
- *
- * Installs or removes a block that will be invoked for every SQL statement
- * executed.
+/* Installs or removes a block that will be invoked for every SQL statement
+ * executed. To stop tracing, call `#trace` without a block.
+ * 
+ * @return [Extralite::Database] database
  */
 VALUE Database_trace(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -876,11 +1035,11 @@ VALUE Database_trace(VALUE self) {
  * or undo the changes. The given table names specify which tables should be
  * tracked for changes. Passing a value of nil causes all tables to be tracked.
  * 
- *   changeset = db.track_changes(:foo, :bar) do
- *     perform_a_bunch_of_queries
- *   end
+ *     changeset = db.track_changes(:foo, :bar) do
+ *       perform_a_bunch_of_queries
+ *     end
  * 
- *   File.open('my.changes', 'w+') { |f| f << changeset.to_blob }
+ *     File.open('my.changes', 'w+') { |f| f << changeset.to_blob }
  * 
  * @param table [String, Symbol] table to track
  * @return [Extralite::Changeset] changeset
@@ -899,101 +1058,236 @@ VALUE Database_track_changes(int argc, VALUE *argv, VALUE self) {
 }
 #endif
 
-int Database_progress_handler(void *ptr) {
-  Database_t *db = (Database_t *)ptr;
-  rb_funcall(db->progress_handler_proc, ID_call, 0);
-  return 0;
+void Database_reset_progress_handler(VALUE self, Database_t *db) {
+  db->progress_handler.mode = PROGRESS_NONE;
+  RB_OBJ_WRITE(self, &db->progress_handler.proc, Qnil);
+  sqlite3_progress_handler(db->sqlite3_db, 0, NULL, NULL);
+  sqlite3_busy_handler(db->sqlite3_db, NULL, NULL);
 }
 
-int Database_busy_handler(void *ptr, int v) {
-  Database_t *db = (Database_t *)ptr;
-  rb_funcall(db->progress_handler_proc, ID_call, 0);
-  return 1;
+static inline enum progress_handler_mode symbol_to_progress_mode(VALUE mode) {
+  if (mode == SYM_at_least_once)  return PROGRESS_AT_LEAST_ONCE;
+  if (mode == SYM_once)           return PROGRESS_ONCE;
+  if (mode == SYM_normal)         return PROGRESS_NORMAL;
+  if (mode == SYM_none)           return PROGRESS_NONE;
+  rb_raise(eArgumentError, "Invalid progress handler mode");
 }
 
-void Database_reset_progress_handler(VALUE self, Database_t *db) {
-  RB_OBJ_WRITE(self, &db->progress_handler_proc, Qnil);
-  sqlite3_progress_handler(db->sqlite3_db, 0, NULL, NULL);
-  sqlite3_busy_handler(db->sqlite3_db, NULL, NULL);
+inline void Database_issue_query(Database_t *db, VALUE sql) {
+  if (db->trace_proc != Qnil) rb_funcall(db->trace_proc, ID_call, 1, sql);
+  switch (db->progress_handler.mode) {
+    case PROGRESS_AT_LEAST_ONCE:
+    case PROGRESS_ONCE:
+      rb_funcall(db->progress_handler.proc, ID_call, 0);
+    default:
+      ; // do nothing
+
+  }
 }
 
-/* call-seq:
- *   db.on_progress(period) { } -> db
- *   db.on_progress(0) -> db
- *
- * Installs or removes a progress handler that will be executed periodically
+struct progress_handler parse_progress_handler_opts(VALUE opts) {
+  static ID kw_ids[3];
+  VALUE kw_args[3];
+  struct progress_handler prog = {
+    .mode   = rb_block_given_p() ? PROGRESS_NORMAL : PROGRESS_NONE,
+    .proc   = rb_block_given_p() ? rb_block_proc() : Qnil,
+    .period = DEFAULT_PROGRESS_HANDLER_PERIOD,
+    .tick   = DEFAULT_PROGRESS_HANDLER_TICK
+  };
+
+  if (!NIL_P(opts)) {
+    if (!kw_ids[0]) {
+      CONST_ID(kw_ids[0], "period");
+      CONST_ID(kw_ids[1], "tick");
+      CONST_ID(kw_ids[2], "mode");
+    }
+
+    rb_get_kwargs(opts, kw_ids, 0, 3, kw_args);
+    if (kw_args[0] != Qundef) { prog.period = NUM2INT(kw_args[0]); }
+    if (kw_args[1] != Qundef) { prog.tick   = NUM2INT(kw_args[1]); }
+    if (kw_args[2] != Qundef) { prog.mode   = symbol_to_progress_mode(kw_args[2]); }
+    if (prog.tick > prog.period) prog.tick = prog.period;
+  }
+  if (NIL_P(prog.proc) || (prog.period <= 0)) prog.mode = PROGRESS_NONE;
+  if (prog.mode == PROGRESS_NONE) prog.proc = Qnil;
+
+  return prog;
+}
+
+/* Installs or removes a progress handler that will be executed periodically
  * while a query is running. This method can be used to support switching
  * between fibers and threads or implementing timeouts for running queries.
  *
- * The given period parameter specifies the approximate number of SQLite virtual
- * machine instructions that are evaluated between successive invocations of the
- * progress handler. A period of less than 1 removes the progress handler.
+ * The `period` parameter specifies the approximate number of SQLite
+ * virtual machine instructions that are evaluated between successive
+ * invocations of the progress handler. A period of less than 1 removes the
+ * progress handler. The default period value is 1000.
+ *
+ * The optional `tick` parameter specifies the granularity of how often the
+ * progress handler is called. The default tick value is 10, which means that
+ * Extralite's underlying progress callback will be called every 10 SQLite VM
+ * instructions. The given progress proc, however, will be only called every
+ * `period` (cumulative) VM instructions. This allows the progress handler to
+ * work correctly also when running simple queries that don't include many
+ * VM instructions. If the `tick` value is greater than the period value it is
+ * automatically capped to the period value.
+ * 
+ * The `mode` parameter controls the progress handler mode, which is one of the
+ * following:
+ * 
+ * - `:normal` (default): the progress handler proc is invoked on query
+ *   progress.
+ * - `:once`: the progress handler proc is invoked only once, when preparing the
+ *   query.
+ * - `:at_least_once`: the progress handler proc is invoked when prearing the
+ *   query, and on query progress.
  *
  * The progress handler is called also when the database is busy. This lets the
  * application perform work while waiting for the database to become unlocked,
  * or implement a timeout. Note that setting the database's busy_timeout _after_
  * setting a progress handler may lead to undefined behaviour in a concurrent
- * application.
+ * application. When busy, the progress handler proc is passed `true` as the
+ * first argument.
  *
  * When the progress handler is set, the gvl release threshold value is set to
  * -1, which means that the GVL will not be released at all when preparing or
  * running queries. It is the application's responsibility to let other threads
  * or fibers run by calling e.g. Thread.pass:
- * 
- *     db.on_progress(1000) do
+ *
+ *     db.on_progress do
  *       do_something_interesting
  *       Thread.pass # let other threads run
  *     end
- * 
- * Note that the progress handler is set globally for the database and that 
+ *
+ * Note that the progress handler is set globally for the database and that
  * Extralite does provide any hooks for telling which queries are currently
- * running or at what time they were started. This means that you'll need
- * to wrap the stock #query_xxx and #execute methods with your own code that
+ * running or at what time they were started. This means that you'll need to
+ * wrap the stock #query_xxx and #execute methods with your own code that
  * calculates timeouts, for example:
- * 
+ *
  *     def setup_progress_handler
- *       @db.on_progress(1000) do
+ *       @db.on_progress do
  *         raise TimeoutError if Time.now - @t0 >= @timeout
  *         Thread.pass
  *       end
  *     end
- * 
+ *
  *     def query(sql, *)
  *       @t0 = Time.now
  *       @db.query(sql, *)
  *     end
- * 
+ *
  * If the gvl release threshold is set to a value equal to or larger than 0
  * after setting the progress handler, the progress handler will be reset.
  *
  * @param period [Integer] progress handler period
+ * @param [Hash] opts progress options
+ * @option opts [Integer] :period period value (`1000` by default)
+ * @option opts [Integer] :tick tick value (`10` by default)
+ * @option opts [Symbol] :mode progress handler mode (`:normal` by default)
  * @returns [Extralite::Database] database
  */
-VALUE Database_on_progress(VALUE self, VALUE period) {
+VALUE Database_on_progress(int argc, VALUE *argv, VALUE self) {
   Database_t *db = self_to_open_database(self);
-  int period_int = NUM2INT(period);
+  VALUE opts;
+  struct progress_handler prog;
 
-  if (period_int > 0 && rb_block_given_p()) {
-    RB_OBJ_WRITE(self, &db->progress_handler_proc, rb_block_proc());
-    db->gvl_release_threshold = -1;
+  rb_scan_args(argc, argv, "00:", &opts);
+  prog = parse_progress_handler_opts(opts);
 
-    sqlite3_progress_handler(db->sqlite3_db, period_int, &Database_progress_handler, db);
-    sqlite3_busy_handler(db->sqlite3_db, &Database_busy_handler, db);
-  }
-  else {
-    RB_OBJ_WRITE(self, &db->progress_handler_proc, Qnil);
+  if (prog.mode == PROGRESS_NONE) {
+    Database_reset_progress_handler(self, db);
     db->gvl_release_threshold = DEFAULT_GVL_RELEASE_THRESHOLD;
-    sqlite3_progress_handler(db->sqlite3_db, 0, NULL, NULL);
-    sqlite3_busy_handler(db->sqlite3_db, NULL, NULL);
+    return self;
   }
 
+  db->gvl_release_threshold = -1;
+  db->progress_handler.mode       = prog.mode;
+  RB_OBJ_WRITE(self, &db->progress_handler.proc, prog.proc);
+  db->progress_handler.period     = prog.period;
+  db->progress_handler.tick       = prog.tick;
+  db->progress_handler.tick_count = 0;
+  db->progress_handler.call_count = 0;
+
+  // The PROGRESS_ONCE mode works by invoking the progress handler proc exactly
+  // once, before iterating over the result set, so in that mode we don't
+  // actually need to set the progress handler at the sqlite level.
+  if (prog.mode != PROGRESS_ONCE)
+    sqlite3_progress_handler(db->sqlite3_db, prog.tick, &Database_progress_handler, db);
+  if (prog.mode != PROGRESS_NONE)
+    sqlite3_busy_handler(db->sqlite3_db, &Database_busy_handler, db);
+
   return self;
 }
 
-/* call-seq:
- *   db.errcode -> errcode
+/* Installs or removes a global progress handler that will be executed
+ * periodically while a query is running. This method can be used to support
+ * switching between fibers and threads or implementing timeouts for running
+ * queries.
+ * 
+ * This method sets the progress handler settings and behaviour for all
+ * subsequently created `Database` instances. Calling this method will have no
+ * effect on already existing `Database` instances
+ *
+ * The `period` parameter specifies the approximate number of SQLite
+ * virtual machine instructions that are evaluated between successive
+ * invocations of the progress handler. A period of less than 1 removes the
+ * progress handler. The default period value is 1000.
+ *
+ * The optional `tick` parameter specifies the granularity of how often the
+ * progress handler is called. The default tick value is 10, which means that
+ * Extralite's underlying progress callback will be called every 10 SQLite VM
+ * instructions. The given progress proc, however, will be only called every
+ * `period` (cumulative) VM instructions. This allows the progress handler to
+ * work correctly also when running simple queries that don't include many
+ * VM instructions. If the `tick` value is greater than the period value it is
+ * automatically capped to the period value.
+ * 
+ * The `mode` parameter controls the progress handler mode, which is one of the
+ * following:
+ * 
+ * - `:normal` (default): the progress handler proc is invoked on query
+ *   progress.
+ * - `:once`: the progress handler proc is invoked only once, when preparing the
+ *   query.
+ * - `:at_least_once`: the progress handler proc is invoked when prearing the
+ *   query, and on query progress.
+ *
+ * The progress handler is called also when the database is busy. This lets the
+ * application perform work while waiting for the database to become unlocked,
+ * or implement a timeout. Note that setting the database's busy_timeout _after_
+ * setting a progress handler may lead to undefined behaviour in a concurrent
+ * application. When busy, the progress handler proc is passed `true` as the
+ * first argument.
+ *
+ * When the progress handler is set, the gvl release threshold value is set to
+ * -1, which means that the GVL will not be released at all when preparing or
+ * running queries. It is the application's responsibility to let other threads
+ * or fibers run by calling e.g. Thread.pass:
+ *
+ *     Extralite.on_progress do
+ *       do_something_interesting
+ *       Thread.pass # let other threads run
+ *     end
  *
- * Returns the last error code for the database.
+ * @param period [Integer] progress handler period
+ * @param [Hash] opts progress options
+ * @option opts [Integer] :period period value (`1000` by default)
+ * @option opts [Integer] :tick tick value (`10` by default)
+ * @option opts [Symbol] :mode progress handler mode (`:normal` by default)
+ * @returns [Extralite::Database] database
+ */
+VALUE Extralite_on_progress(int argc, VALUE *argv, VALUE self) {
+  VALUE opts;
+
+  rb_scan_args(argc, argv, "00:", &opts);
+  global_progress_handler = parse_progress_handler_opts(opts);
+  return self;
+}
+
+/* Returns the last error code for the database.
+ * 
+ * @return [Integer] last error code
  */
 VALUE Database_errcode(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -1001,10 +1295,9 @@ VALUE Database_errcode(VALUE self) {
   return INT2NUM(sqlite3_errcode(db->sqlite3_db));
 }
 
-/* call-seq:
- *   db.errmsg -> errmsg
- *
- * Returns the last error message for the database.
+/* Returns the last error message for the database.
+ * 
+ * @return [String] last error message
  */
 VALUE Database_errmsg(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -1013,10 +1306,10 @@ VALUE Database_errmsg(VALUE self) {
 }
 
 #ifdef HAVE_SQLITE3_ERROR_OFFSET
-/* call-seq:
- *   db.error_offset -> ofs
- *
- * Returns the offset for the last error
+/* Returns the offset for the last error. This is useful for indicating where in
+ * the SQL string an error was encountered.
+ * 
+ * @return [Integer] offset in the last submitted SQL string
  */
 VALUE Database_error_offset(VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -1052,14 +1345,24 @@ VALUE Database_gvl_release_threshold_get(VALUE 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
+/* Sets the database's GVL release threshold. The release policy changes
+ * according to the given value:
+ * 
+ * - Less than 0: the GVL is never released while running queries. This is the
+ *   policy used when a progress handler is set. For more information see
+ *   `#on_progress`.
+ * - 0: The GVL is released while preparing queries, but held when iterating
+ *   through records.
+ * - Greater than 0: the GVL is released while preparing queries, and released
+ *   periodically while iterating through records, according to the given
+ *   period. A value of 1 will release the GVL on every iterated record. A value
+ *   of 100 will release the GVL once for every 100 records.
+ *
+ * A value of nil sets the threshold to the default value, which is
  * currently 1000.
  *
- * @return [Integer, nil] New GVL release threshold
+ * @param [Integer, nil] GVL release threshold
+ * @return [Integer] GVL release threshold
  */
 VALUE Database_gvl_release_threshold_set(VALUE self, VALUE value) {
   Database_t *db = self_to_open_database(self);
@@ -1071,7 +1374,7 @@ VALUE Database_gvl_release_threshold_set(VALUE self, VALUE value) {
         if (value_int < -1)
           rb_raise(eArgumentError, "Invalid GVL release threshold value (expect integer >= -1)");
 
-        if (value_int > -1 && !NIL_P(db->progress_handler_proc))
+        if (value_int > -1 && db->progress_handler.mode != PROGRESS_NONE)
           Database_reset_progress_handler(self, db);
         db->gvl_release_threshold = value_int;
         break;
@@ -1090,87 +1393,106 @@ void Init_ExtraliteDatabase(void) {
   VALUE mExtralite = rb_define_module("Extralite");
   rb_define_singleton_method(mExtralite, "runtime_status", Extralite_runtime_status, -1);
   rb_define_singleton_method(mExtralite, "sqlite3_version", Extralite_sqlite3_version, 0);
+  rb_define_singleton_method(mExtralite, "on_progress", Extralite_on_progress, -1);
 
   cDatabase = rb_define_class_under(mExtralite, "Database", rb_cObject);
   rb_define_alloc_func(cDatabase, Database_allocate);
 
-  rb_define_method(cDatabase, "backup", Database_backup, -1);
-  rb_define_method(cDatabase, "busy_timeout=", Database_busy_timeout_set, 1);
-  rb_define_method(cDatabase, "changes", Database_changes, 0);
-  rb_define_method(cDatabase, "close", Database_close, 0);
-  rb_define_method(cDatabase, "closed?", Database_closed_p, 0);
-  rb_define_method(cDatabase, "columns", Database_columns, 1);
-  rb_define_method(cDatabase, "errcode", Database_errcode, 0);
-  rb_define_method(cDatabase, "errmsg", Database_errmsg, 0);
+  #define DEF(s, f, a) rb_define_method(cDatabase, s, f, a)
+
+  DEF("backup",                 Database_backup, -1);
+  DEF("batch_execute",          Database_batch_execute, 2);
+  DEF("batch_query",            Database_batch_query, 2);
+  DEF("batch_query_ary",        Database_batch_query_ary, 2);
+  DEF("batch_query_argv",       Database_batch_query_argv, 2);
+  DEF("batch_query_hash",       Database_batch_query, 2);
+  DEF("busy_timeout=",          Database_busy_timeout_set, 1);
+  DEF("changes",                Database_changes, 0);
+  DEF("close",                  Database_close, 0);
+  DEF("closed?",                Database_closed_p, 0);
+  DEF("columns",                Database_columns, 1);
+  DEF("errcode",                Database_errcode, 0);
+  DEF("errmsg",                 Database_errmsg, 0);
 
   #ifdef HAVE_SQLITE3_ERROR_OFFSET
-  rb_define_method(cDatabase, "error_offset", Database_error_offset, 0);
+  DEF("error_offset",           Database_error_offset, 0);
   #endif
 
-  rb_define_method(cDatabase, "execute", Database_execute, -1);
-  rb_define_method(cDatabase, "batch_execute", Database_batch_execute, 2);
-  rb_define_method(cDatabase, "batch_query", Database_batch_query, 2);
-  rb_define_method(cDatabase, "batch_query_ary", Database_batch_query_ary, 2);
-  rb_define_method(cDatabase, "batch_query_single_column", Database_batch_query_single_column, 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);
-  rb_define_method(cDatabase, "last_insert_rowid", Database_last_insert_rowid, 0);
-  rb_define_method(cDatabase, "limit", Database_limit, -1);
-  rb_define_method(cDatabase, "on_progress", Database_on_progress, 1);
-  rb_define_method(cDatabase, "prepare", Database_prepare, -1);
-  rb_define_method(cDatabase, "query", Database_query_hash, -1);
-  rb_define_method(cDatabase, "query_ary", Database_query_ary, -1);
-  rb_define_method(cDatabase, "query_hash", Database_query_hash, -1);
-  rb_define_method(cDatabase, "query_single_column", Database_query_single_column, -1);
-  rb_define_method(cDatabase, "query_single_row", Database_query_single_row, -1);
-  rb_define_method(cDatabase, "query_single_value", Database_query_single_value, -1);
-  rb_define_method(cDatabase, "read_only?", Database_read_only_p, 0);
-  rb_define_method(cDatabase, "status", Database_status, -1);
-  rb_define_method(cDatabase, "total_changes", Database_total_changes, 0);
-  rb_define_method(cDatabase, "trace", Database_trace, 0);
+  DEF("execute",                Database_execute, -1);
+  DEF("filename",               Database_filename, -1);
+  DEF("gvl_release_threshold",  Database_gvl_release_threshold_get, 0);
+  DEF("gvl_release_threshold=", Database_gvl_release_threshold_set, 1);
+  DEF("initialize",             Database_initialize, -1);
+  DEF("inspect",                Database_inspect, 0);
+  DEF("interrupt",              Database_interrupt, 0);
+  DEF("last_insert_rowid",      Database_last_insert_rowid, 0);
+  DEF("limit",                  Database_limit, -1);
+
+  #ifdef HAVE_SQLITE3_LOAD_EXTENSION
+  DEF("load_extension",         Database_load_extension, 1);
+  #endif
+
+  DEF("on_progress",            Database_on_progress, -1);
+  DEF("prepare",                Database_prepare_hash, -1);
+  DEF("prepare_argv",           Database_prepare_argv, -1);
+  DEF("prepare_ary",            Database_prepare_ary, -1);
+  DEF("prepare_hash",           Database_prepare_hash, -1);
+  DEF("query",                  Database_query, -1);
+  DEF("query_argv",             Database_query_argv, -1);
+  DEF("query_ary",              Database_query_ary, -1);
+  DEF("query_hash",             Database_query, -1);
+  DEF("query_single",           Database_query_single, -1);
+  DEF("query_single_ary",       Database_query_single_ary, -1);
+  DEF("query_single_argv",      Database_query_single_argv, -1);
+  DEF("query_single_hash",      Database_query_single, -1);
+  DEF("read_only?",             Database_read_only_p, 0);
+  DEF("status",                 Database_status, -1);
+  DEF("total_changes",          Database_total_changes, 0);
+  DEF("trace",                  Database_trace, 0);
 
   #ifdef EXTRALITE_ENABLE_CHANGESET
-  rb_define_method(cDatabase, "track_changes", Database_track_changes, -1);
+  DEF("track_changes",          Database_track_changes, -1);
   #endif
   
-  rb_define_method(cDatabase, "transaction_active?", Database_transaction_active_p, 0);
+  DEF("transaction_active?",    Database_transaction_active_p, 0);
 
-#ifdef HAVE_SQLITE3_LOAD_EXTENSION
-  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);
+  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);
   cParameterError = rb_define_class_under(mExtralite, "ParameterError", cError);
-
-  eArgumentError = rb_const_get(rb_cObject, rb_intern("ArgumentError"));
-
-  ID_bind   = rb_intern("bind");
-  ID_call   = rb_intern("call");
-  ID_each   = rb_intern("each");
-  ID_keys   = rb_intern("keys");
-  ID_new    = rb_intern("new");
-  ID_strip  = rb_intern("strip");
-  ID_to_s   = rb_intern("to_s");
-  ID_track  = rb_intern("track");
-
+  eArgumentError  = rb_const_get(rb_cObject, rb_intern("ArgumentError"));
+
+  ID_bind         = rb_intern("bind");
+  ID_call         = rb_intern("call");
+  ID_each         = rb_intern("each");
+  ID_keys         = rb_intern("keys");
+  ID_new          = rb_intern("new");
+  ID_pragma       = rb_intern("pragma");
+  ID_strip        = rb_intern("strip");
+  ID_to_s         = rb_intern("to_s");
+  ID_track        = rb_intern("track");
+
+  SYM_at_least_once         = ID2SYM(rb_intern("at_least_once"));
   SYM_gvl_release_threshold = ID2SYM(rb_intern("gvl_release_threshold"));
+  SYM_once                  = ID2SYM(rb_intern("once"));
+  SYM_none                  = ID2SYM(rb_intern("none"));
+  SYM_normal                = ID2SYM(rb_intern("normal"));
+  SYM_pragma                = ID2SYM(rb_intern("pragma"));
   SYM_read_only             = ID2SYM(rb_intern("read_only"));
-  SYM_synchronous           = ID2SYM(rb_intern("synchronous"));
-  SYM_wal_journal_mode      = ID2SYM(rb_intern("wal_journal_mode"));
+  SYM_wal                   = ID2SYM(rb_intern("wal"));
 
+  rb_gc_register_mark_object(SYM_at_least_once);
   rb_gc_register_mark_object(SYM_gvl_release_threshold);
+  rb_gc_register_mark_object(SYM_once);
+  rb_gc_register_mark_object(SYM_none);
+  rb_gc_register_mark_object(SYM_normal);
+  rb_gc_register_mark_object(SYM_pragma);
   rb_gc_register_mark_object(SYM_read_only);
-  rb_gc_register_mark_object(SYM_synchronous);
-  rb_gc_register_mark_object(SYM_wal_journal_mode);
+  rb_gc_register_mark_object(SYM_wal);
+
+  rb_gc_register_mark_object(global_progress_handler.proc);
 
   UTF8_ENCODING = rb_utf8_encoding();
 }