extralite 1.12 → 1.13

data/ext/extralite/database.c

@@ -0,0 +1,385 @@
+#include <stdio.h>
+#include "extralite.h"
+
+VALUE cDatabase;
+VALUE cError;
+VALUE cSQLError;
+VALUE cBusyError;
+
+ID ID_KEYS;
+ID ID_NEW;
+ID ID_STRIP;
+ID ID_TO_S;
+
+static size_t Database_size(const void *ptr) {
+  return sizeof(Database_t);
+}
+
+static void Database_free(void *ptr) {
+  Database_t *db = ptr;
+  if (db->sqlite3_db) sqlite3_close(db->sqlite3_db);
+  free(ptr);
+}
+
+static const rb_data_type_t Database_type = {
+    "Database",
+    {0, Database_free, Database_size,},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE Database_allocate(VALUE klass) {
+  Database_t *db = ALLOC(Database_t);
+  db->sqlite3_db = 0;
+  return TypedData_Wrap_Struct(klass, &Database_type, db);
+}
+
+#define GetDatabase(obj, database) \
+  TypedData_Get_Struct((obj), Database_t, &Database_type, (database))
+
+// make sure the database is open
+#define GetOpenDatabase(obj, database) { \
+  TypedData_Get_Struct((obj), Database_t, &Database_type, (database)); \
+  if (!(database)->sqlite3_db) { \
+    rb_raise(cError, "Database is closed"); \
+  } \
+}
+
+sqlite3 *Database_sqlite3_db(VALUE self) {
+  Database_t *db;
+  GetDatabase(self, db);
+  return db->sqlite3_db;
+}
+
+/* call-seq:
+ *   Extralite.sqlite3_version -> version
+ *
+ * Returns the sqlite3 version used by Extralite.
+ */
+
+VALUE Extralite_sqlite3_version(VALUE self) {
+  return rb_str_new_cstr(sqlite3_version);
+}
+
+/* call-seq:
+ *   db.initialize(path)
+ *
+ * Initializes a new SQLite database with the given path.
+ */
+
+VALUE Database_initialize(VALUE self, VALUE path) {
+  int rc;
+  Database_t *db;
+  GetDatabase(self, db);
+
+  rc = sqlite3_open(StringValueCStr(path), &db->sqlite3_db);
+  if (rc) {
+    sqlite3_close(db->sqlite3_db);
+    rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
+  }
+
+  rc = sqlite3_enable_load_extension(db->sqlite3_db, 1);
+  if (rc) {
+    sqlite3_close(db->sqlite3_db);
+    rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
+  }
+
+  return Qnil;
+}
+
+/* call-seq:
+ *   db.close -> db
+ *
+ * Closes the database.
+ */
+VALUE Database_close(VALUE self) {
+  int rc;
+  Database_t *db;
+  GetDatabase(self, db);
+
+  rc = sqlite3_close(db->sqlite3_db);
+  if (rc) {
+    rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
+  }
+
+  db->sqlite3_db = 0;
+  return self;
+}
+
+/* call-seq:
+ *   db.closed? -> bool
+ *
+ * Returns true if the database is closed.
+ *
+ * @return [bool] is database closed
+ */
+VALUE Database_closed_p(VALUE self) {
+  Database_t *db;
+  GetDatabase(self, db);
+
+  return db->sqlite3_db ? Qfalse : Qtrue;
+}
+
+static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VALUE (*call)(query_ctx *)) {
+  Database_t *db;
+  sqlite3_stmt *stmt;
+  VALUE sql;
+
+  // extract query from args
+  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
+  sql = rb_funcall(argv[0], ID_STRIP, 0);
+  if (RSTRING_LEN(sql) == 0) return Qnil;
+
+  // prepare query ctx
+  GetOpenDatabase(self, db);
+  prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
+  bind_all_parameters(stmt, argc - 1, argv + 1);
+  query_ctx ctx = { self, db->sqlite3_db, stmt };
+
+  return rb_ensure(SAFE(call), (VALUE)&ctx, SAFE(cleanup_stmt), (VALUE)&ctx);
+}
+
+/* call-seq:
+ *    db.query(sql, *parameters, &block) -> [...]
+ *    db.query_hash(sql, *parameters, &block) -> [...]
+ *
+ * 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 a least, 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)
+ */
+VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_hash);
+}
+
+/* call-seq:
+ *   db.query_ary(sql, *parameters, &block) -> [...]
+ *
+ * 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
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_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:
+ *
+ *     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)
+ */
+VALUE Database_query_ary(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_ary);
+}
+
+/* call-seq:
+ *   db.query_single_row(sql, *parameters) -> {...}
+ *
+ * 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 a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_row('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_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)
+ */
+VALUE Database_query_single_row(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_single_row);
+}
+
+/* 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.
+ *
+ * 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 a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_column('select x 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_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)
+ */
+VALUE Database_query_single_column(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_single_column);
+}
+
+/* call-seq:
+ *   db.query_single_value(sql, *parameters) -> value
+ *
+ * Runs a query returning a single value from the first row.
+ *
+ * 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 a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_value('select x 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_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)
+ */
+VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
+  return Database_perform_query(argc, argv, self, safe_query_single_value);
+}
+
+/* call-seq:
+ *   db.last_insert_rowid -> int
+ *
+ * Returns the rowid of the last inserted row.
+ */
+VALUE Database_last_insert_rowid(VALUE self) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  return INT2NUM(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.
+ */
+VALUE Database_changes(VALUE self) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  return INT2NUM(sqlite3_changes(db->sqlite3_db));
+}
+
+/* call-seq:
+ *   db.filename -> string
+ *
+ * Returns the database filename.
+ */
+VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
+  const char *db_name;
+  const char *filename;
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  rb_check_arity(argc, 0, 1);
+  db_name = (argc == 1) ? StringValueCStr(argv[0]) : "main";
+  filename = sqlite3_db_filename(db->sqlite3_db, db_name);
+  return filename ? rb_str_new_cstr(filename) : Qnil;
+}
+
+/* call-seq:
+ *   db.transaction_active? -> bool
+ *
+ * Returns true if a transaction is currently in progress.
+ */
+VALUE Database_transaction_active_p(VALUE self) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+
+  return sqlite3_get_autocommit(db->sqlite3_db) ? Qfalse : Qtrue;
+}
+
+/* call-seq:
+ *   db.load_extension(path) -> db
+ *
+ * Loads an extension with the given path.
+ */
+VALUE Database_load_extension(VALUE self, VALUE path) {
+  Database_t *db;
+  GetOpenDatabase(self, db);
+  char *err_msg;
+
+  int rc = sqlite3_load_extension(db->sqlite3_db, RSTRING_PTR(path), 0, &err_msg);
+  if (rc != SQLITE_OK) {
+    VALUE error = rb_exc_new2(cError, err_msg);
+    sqlite3_free(err_msg);
+    rb_exc_raise(error);
+  }
+
+  return self;
+}
+
+/* call-seq:
+ *   db.prepare(sql) -> Extralite::PreparedStatement
+ *
+ * Creates a prepared statement with the given SQL query.
+ */
+VALUE Database_prepare(VALUE self, VALUE sql) {
+  return rb_funcall(cPreparedStatement, ID_NEW, 2, self, sql);
+}
+
+void Init_ExtraliteDatabase() {
+  VALUE mExtralite = rb_define_module("Extralite");
+  rb_define_singleton_method(mExtralite, "sqlite3_version", Extralite_sqlite3_version, 0);
+
+  cDatabase = rb_define_class_under(mExtralite, "Database", rb_cObject);
+  rb_define_alloc_func(cDatabase, Database_allocate);
+
+  rb_define_method(cDatabase, "initialize", Database_initialize, 1);
+  rb_define_method(cDatabase, "close", Database_close, 0);
+  rb_define_method(cDatabase, "closed?", Database_closed_p, 0);
+
+  rb_define_method(cDatabase, "query", Database_query_hash, -1);
+  rb_define_method(cDatabase, "query_hash", Database_query_hash, -1);
+  rb_define_method(cDatabase, "query_ary", Database_query_ary, -1);
+  rb_define_method(cDatabase, "query_single_row", Database_query_single_row, -1);
+  rb_define_method(cDatabase, "query_single_column", Database_query_single_column, -1);
+  rb_define_method(cDatabase, "query_single_value", Database_query_single_value, -1);
+
+  rb_define_method(cDatabase, "last_insert_rowid", Database_last_insert_rowid, 0);
+  rb_define_method(cDatabase, "changes", Database_changes, 0);
+  rb_define_method(cDatabase, "filename", Database_filename, -1);
+  rb_define_method(cDatabase, "transaction_active?", Database_transaction_active_p, 0);
+  rb_define_method(cDatabase, "load_extension", Database_load_extension, 1);
+
+  rb_define_method(cDatabase, "prepare", Database_prepare, 1);
+
+  cError = rb_define_class_under(mExtralite, "Error", rb_eRuntimeError);
+  cSQLError = rb_define_class_under(mExtralite, "SQLError", cError);
+  cBusyError = rb_define_class_under(mExtralite, "BusyError", cError);
+  rb_gc_register_mark_object(cError);
+  rb_gc_register_mark_object(cSQLError);
+  rb_gc_register_mark_object(cBusyError);
+
+  ID_KEYS   = rb_intern("keys");
+  ID_NEW    = rb_intern("new");
+  ID_STRIP  = rb_intern("strip");
+  ID_TO_S   = rb_intern("to_s");
+}

data/ext/extralite/extralite.h

@@ -0,0 +1,59 @@
+#ifndef EXTRALITE_H
+#define EXTRALITE_H
+
+#include "ruby.h"
+#include "ruby/thread.h"
+#include <sqlite3.h>
+
+// debug utility
+#define INSPECT(str, obj) { \
+  printf(str); \
+  VALUE s = rb_funcall(obj, rb_intern("inspect"), 0); \
+  printf(": %s\n", StringValueCStr(s)); \
+}
+
+#define SAFE(f) (VALUE (*)(VALUE))(f)
+
+extern VALUE cDatabase;
+extern VALUE cPreparedStatement;
+
+extern VALUE cError;
+extern VALUE cSQLError;
+extern VALUE cBusyError;
+
+extern ID ID_KEYS;
+extern ID ID_NEW;
+extern ID ID_STRIP;
+extern ID ID_TO_S;
+
+typedef struct {
+  sqlite3 *sqlite3_db;
+} Database_t;
+
+typedef struct {
+  VALUE db;
+  VALUE sql;
+  sqlite3 *sqlite3_db;
+  sqlite3_stmt *stmt;
+} PreparedStatement_t;
+
+typedef struct {
+  VALUE self;
+  sqlite3 *sqlite3_db;
+  sqlite3_stmt *stmt;
+} query_ctx;
+
+VALUE safe_query_ary(query_ctx *ctx);
+VALUE safe_query_hash(query_ctx *ctx);
+VALUE safe_query_single_column(query_ctx *ctx);
+VALUE safe_query_single_row(query_ctx *ctx);
+VALUE safe_query_single_value(query_ctx *ctx);
+
+void prepare_single_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql);
+void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql);
+void bind_all_parameters(sqlite3_stmt *stmt, int argc, VALUE *argv);
+VALUE cleanup_stmt(query_ctx *ctx);
+
+sqlite3 *Database_sqlite3_db(VALUE self);
+
+#endif /* EXTRALITE_H */

data/ext/extralite/extralite_ext.c

@@ -1,5 +1,7 @@
-void Init_Extralite();
+void Init_ExtraliteDatabase();
+void Init_ExtralitePreparedStatement();
 
 void Init_extralite_ext() {
-  Init_Extralite();
+  Init_ExtraliteDatabase();
+  Init_ExtralitePreparedStatement();
 }

data/ext/extralite/prepared_statement.c

@@ -0,0 +1,238 @@
+#include <stdio.h>
+#include "extralite.h"
+
+VALUE cPreparedStatement;
+
+static size_t PreparedStatement_size(const void *ptr) {
+  return sizeof(PreparedStatement_t);
+}
+
+static void PreparedStatement_mark(void *ptr) {
+  PreparedStatement_t *stmt = ptr;
+  rb_gc_mark(stmt->db);
+  rb_gc_mark(stmt->sql);
+}
+
+static void PreparedStatement_free(void *ptr) {
+  PreparedStatement_t *stmt = ptr;
+  if (stmt->stmt) sqlite3_finalize(stmt->stmt);
+  free(ptr);
+}
+
+static const rb_data_type_t PreparedStatement_type = {
+    "Database",
+    {PreparedStatement_mark, PreparedStatement_free, PreparedStatement_size,},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE PreparedStatement_allocate(VALUE klass) {
+  PreparedStatement_t *stmt = ALLOC(PreparedStatement_t);
+  stmt->db = Qnil;
+  stmt->sqlite3_db = NULL;
+  stmt->stmt = NULL;
+  return TypedData_Wrap_Struct(klass, &PreparedStatement_type, stmt);
+}
+
+#define GetPreparedStatement(obj, stmt) \
+  TypedData_Get_Struct((obj), PreparedStatement_t, &PreparedStatement_type, (stmt))
+
+/* call-seq: initialize(db, sql)
+ *
+ * Initializes a new SQLite prepared statement with the given path.
+ */
+VALUE PreparedStatement_initialize(VALUE self, VALUE db, VALUE sql) {
+  // int rc;
+  PreparedStatement_t *stmt;
+  GetPreparedStatement(self, stmt);
+
+  sql = rb_funcall(sql, ID_STRIP, 0);
+  if (!RSTRING_LEN(sql))
+    rb_raise(cError, "Cannot prepare an empty SQL query");
+
+  stmt->db = db;
+  stmt->sqlite3_db = Database_sqlite3_db(db);
+  stmt->sql = sql;
+
+  // TODO: setup stmt
+  prepare_single_stmt(stmt->sqlite3_db, &stmt->stmt, sql);
+
+  return Qnil;
+}
+
+static inline VALUE PreparedStatement_perform_query(int argc, VALUE *argv, VALUE self, VALUE (*call)(query_ctx *)) {
+  PreparedStatement_t *stmt;
+  GetPreparedStatement(self, stmt);
+
+  sqlite3_reset(stmt->stmt);
+  sqlite3_clear_bindings(stmt->stmt);
+  bind_all_parameters(stmt->stmt, argc, argv);
+  query_ctx ctx = { self, stmt->sqlite3_db, stmt->stmt };
+  return call(&ctx);
+}
+
+/* call-seq:
+ *    query(sql, *parameters, &block) -> [...]
+ *    query_hash(sql, *parameters, &block) -> [...]
+ *
+ * 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 a least, 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)
+ */
+VALUE PreparedStatement_query_hash(int argc, VALUE *argv, VALUE self) {
+  return PreparedStatement_perform_query(argc, argv, self, safe_query_hash);
+}
+
+/* call-seq:
+ *   stmt.query_ary(sql, *parameters, &block) -> [...]
+ *
+ * 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
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_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:
+ *
+ *     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)
+ */
+VALUE PreparedStatement_query_ary(int argc, VALUE *argv, VALUE self) {
+  return PreparedStatement_perform_query(argc, argv, self, safe_query_ary);
+}
+
+/* call-seq:
+ *   stmt.query_single_row(sql, *parameters) -> {...}
+ *
+ * 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 a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_row('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_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)
+ */
+VALUE PreparedStatement_query_single_row(int argc, VALUE *argv, VALUE self) {
+  return PreparedStatement_perform_query(argc, argv, self, safe_query_single_row);
+}
+
+/* call-seq:
+ *   stmt.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.
+ *
+ * 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 a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_column('select x 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_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)
+ */
+VALUE PreparedStatement_query_single_column(int argc, VALUE *argv, VALUE self) {
+  return PreparedStatement_perform_query(argc, argv, self, safe_query_single_column);
+}
+
+/* call-seq:
+ *   stmt.query_single_value(sql, *parameters) -> value
+ *
+ * Runs a query returning a single value from the first row.
+ *
+ * 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 a least, the query should specify parameters using
+ * `?`:
+ *
+ *     db.query_single_value('select x 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_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)
+ */
+VALUE PreparedStatement_query_single_value(int argc, VALUE *argv, VALUE self) {
+  return PreparedStatement_perform_query(argc, argv, self, safe_query_single_value);
+}
+
+/* call-seq:
+ *   stmt.database -> database
+ *   stmt.db -> database
+ *
+ * Returns the database associated with the prepared statement.
+ */
+VALUE PreparedStatement_database(VALUE self) {
+  PreparedStatement_t *stmt;
+  GetPreparedStatement(self, stmt);
+  return stmt->db;
+}
+
+/* call-seq:
+ *   stmt.sql -> sql
+ *
+ * Returns the SQL query used for the prepared statement.
+ */
+VALUE PreparedStatement_sql(VALUE self) {
+  PreparedStatement_t *stmt;
+  GetPreparedStatement(self, stmt);
+  return stmt->sql;
+}
+
+void Init_ExtralitePreparedStatement() {
+  VALUE mExtralite = rb_define_module("Extralite");
+
+  cPreparedStatement = rb_define_class_under(mExtralite, "PreparedStatement", rb_cObject);
+  rb_define_alloc_func(cPreparedStatement, PreparedStatement_allocate);
+
+  rb_define_method(cPreparedStatement, "initialize", PreparedStatement_initialize, 2);
+  rb_define_method(cPreparedStatement, "database", PreparedStatement_database, 0);
+  rb_define_method(cPreparedStatement, "db", PreparedStatement_database, 0);
+  rb_define_method(cPreparedStatement, "sql", PreparedStatement_sql, 0);
+
+  rb_define_method(cPreparedStatement, "query", PreparedStatement_query_hash, -1);
+  rb_define_method(cPreparedStatement, "query_hash", PreparedStatement_query_hash, -1);
+  rb_define_method(cPreparedStatement, "query_ary", PreparedStatement_query_ary, -1);
+  rb_define_method(cPreparedStatement, "query_single_row", PreparedStatement_query_single_row, -1);
+  rb_define_method(cPreparedStatement, "query_single_column", PreparedStatement_query_single_column, -1);
+  rb_define_method(cPreparedStatement, "query_single_value", PreparedStatement_query_single_value, -1);
+}