extralite 0.2.1 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edc158d606131bab091a3a9053a00a540728e53b12aa6165ec69f3611d5c449a
-  data.tar.gz: 826223da4bcd18ff70bc5d6f81c08c2ae8aa486387cd2277d0275268a1917853
+  metadata.gz: 9c69948d51f689ead3e4ccf008bc7b0670085d0c987d39359bb38172b9993b58
+  data.tar.gz: 776ed4e4f95cdb405b9b3be277d0aaa5a27fcd0e84aff8f6ebb3aeece531b1cf
 SHA512:
-  metadata.gz: c5fa113e40bf4ed2f4b2d89267386cd901e7346462ae080a8ba9771c0b8da2d95ce0473e584031210c02b4b3e9785d607afb8886da1c8d75fcadb9bb5022181d
-  data.tar.gz: df5a8b1025cd8278b5a929415bd62581d79b9769cd57f0353b3163fdb5d3f81a2c9ccd23901a4dade805e58add9436671e728aaead945ffed8239cb4dc619e17
+  metadata.gz: 472db7ae94e195e647712ce04213538b229bcfebc3f9ec22b3f8e69dceb0a5cbba9000e14147a27ed2e26231aa7c73b43585a45be369f94d8cd2507643dd88b9
+  data.tar.gz: 6475f99ebe990b9b073f77379f58ddcd4fa0f678fb32e64b39021e3aa7b6d6f9343c8f02d69cce1826a9d156c8b0918985536732af5a11be2bda28524524e8c2

data/CHANGELOG.md

@@ -1,4 +1,26 @@
-## 0.2 2021-05-24
+## 1.0 2021-05-27
+
+- Refactor C code
+- Use `rb_ensure` to finalize stmt
+- Remove bundled `sqlite3.h`, use system-wide header file instead
+
+## 0.6 2021-05-25
+
+- Add more specific errors: `SQLError`, `BusyError`
+
+## 0.5 2021-05-25
+
+- Implement `Database#query_single_row`
+
+## 0.4 2021-05-24
+
+- Add support for loading extensions
+
+## 0.3 2021-05-24
+
+- Add support for running multiple statements
+
+## 0.2 2021-05-23
 
 - Implement `Database#transaction_active?`
 - Add tests

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    extralite (0.2.1)
+    extralite (1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,16 +1,21 @@
 ## Extralite
 
-Extralite is an extra-lightweight SQLite3 wrapper for Ruby. It provides a single
-class with a minimal set of methods to interact with an SQLite3 database.
+Extralite is an extra-lightweight (~365 lines of C-code) SQLite3 wrapper for
+Ruby. It provides a single class with a minimal set of methods to interact with
+an SQLite3 database.
 
 ### Features
 
-- A variety of ways to get back query results: row as hash, row as array, single
-  column, single value.
+- A variety of methods for different data access patterns: row as hash, row as
+  array, single single row, single column, single value.
 - Iterate over records with a block, or collect records into an array.
 - Parameter binding.
+- Correctly execute strings with multiple semicolon-separated queries (handy for
+  creating/modifying schemas).
 - Get last insert rowid.
 - Get number of rows changed by last query.
+- Load extensions (loading of extensions is autmatically enabled. You can find
+  some useful extensions here: https://github.com/nalgeon/sqlean.)
 
 ### Usage
 
@@ -18,7 +23,7 @@ class with a minimal set of methods to interact with an SQLite3 database.
 require 'extralite'
 
 # open a database
-db = Extralite::Database.new('mydb')
+db = Extralite::Database.new('/tmp/my.db')
 
 # get query results as array of hashes
 db.query('select 1 as foo') #=> [{ :foo => 1 }]
@@ -34,6 +39,9 @@ db.query_ary('select 1, 2, 3') #=> [[1, 2, 3]]
 db.query_ary('select 1, 2, 3') { |r| p r }
 # [1, 2, 3]
 
+# get a single row as a hash
+db.query_single_row("select 1 as foo") #=> { :foo => 1 }
+
 # get single column query results as array of values
 db.query_single_column('select 42') #=> [42]
 # or iterate over results
@@ -49,9 +57,33 @@ db.query_hash('select ? as foo, ? as bar', 1, 2) #=> [{ :foo => 1, :bar => 2 }]
 # get last insert rowid
 rowid = db.last_insert_id
 
-# get rows changed in last query
-rows_changed = db.changes
+# get number of rows changed in last query
+number_of_rows_affected = db.changes
 
 # get db filename
-Extralite::Database.new('/tmp/my.db').filename #=> "/tmp/my.db"
+db.filename #=> "/tmp/my.db"
+
+# load an extension
+db.load_extension('/path/to/extension.so')
 ```
+
+### Why not just use the sqlite3 gem?
+
+The sqlite3-ruby gem is a popular, solid, well-maintained project, used by
+thousands of developers. I've been doing a lot of work with SQLite3 lately, and
+wanted to have a simpler API that gives me query results in a variety of ways.
+Thus extralite was born.
+
+### What about concurrency?
+
+Extralite currently does not release the GVL. This means that even if queries
+are executed on a separate thread, no other Ruby threads will be scheduled while
+SQLite3 is busy fetching the next record.
+
+In the future Extralite might be changed to release the GVL each time
+`sqlite3_step` is called.
+
+### Can I use it with an ORM like ActiveRecord or Sequel?
+
+Not yet, but you are welcome to contribute adapters for those projects. I will
+be releasing my own not-an-ORM tool in the near future.

data/ext/extralite/extralite.c

@@ -1,8 +1,11 @@
 #include <stdio.h>
 #include "ruby.h"
-#include "../sqlite3/sqlite3.h"
+#include <sqlite3.h>
 
 VALUE cError;
+VALUE cSQLError;
+VALUE cBusyError;
+ID ID_STRIP;
 
 typedef struct Database_t {
   sqlite3 *sqlite3_db;
@@ -44,10 +47,14 @@ VALUE Database_initialize(VALUE self, VALUE path) {
 
   rc = sqlite3_open(StringValueCStr(path), &db->sqlite3_db);
   if (rc) {
-    fprintf(stderr, "Can't open database: %s\n", sqlite3_errmsg(db->sqlite3_db));
     sqlite3_close(db->sqlite3_db);
-    // TODO: raise error
-    return Qfalse;
+    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;
@@ -123,215 +130,244 @@ static inline VALUE row_to_hash(sqlite3_stmt *stmt, int column_count, VALUE colu
   return row;
 }
 
-VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
-  int column_count;
-  Database_t *db;
-  VALUE result = self;
-  int yield_to_block = rb_block_given_p();
-  VALUE row;
-  VALUE column_names;
-  VALUE sql;
-  
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
-  sql = argv[0];
-  GetDatabase(self, db);
-
-  rc = sqlite3_prepare(db->sqlite3_db, RSTRING_PTR(sql), RSTRING_LEN(sql), &stmt, 0);
-  if (rc) {
-    sqlite3_finalize(stmt);
-    rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    return Qnil;
+static inline VALUE row_to_ary(sqlite3_stmt *stmt, int column_count) {
+  VALUE row = rb_ary_new2(column_count);
+  for (int i = 0; i < column_count; i++) {
+    VALUE value = get_column_value(stmt, i, sqlite3_column_type(stmt, i));
+    rb_ary_push(row, value);
   }
+  return row;
+}
 
-  bind_all_parameters(stmt, argc, argv);
-  column_count = sqlite3_column_count(stmt);
-  column_names = get_column_names(stmt, column_count);
+inline void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
+  const char *rest = 0;
+  const char *ptr = RSTRING_PTR(sql);
+  const char *end = ptr + RSTRING_LEN(sql);
+  while (1) {
+    int rc = sqlite3_prepare(db, ptr, end - ptr, stmt, &rest);
+    if (rc) {
+      sqlite3_finalize(*stmt);
+      rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
+    }
 
-  // block not given, so prepare the array of records to be returned
-  if (!yield_to_block) result = rb_ary_new();
+    if (rest == end) return;
     
-step:
+    // perform current query, but discard its results
+    rc = sqlite3_step(*stmt);
+    sqlite3_finalize(*stmt);
+    switch (rc) {
+    case SQLITE_BUSY:
+      rb_raise(cBusyError, "Database is busy");
+    case SQLITE_ERROR:
+      rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
+    }
+    ptr = rest;
+  }
+}
+
+inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
+  int rc;
   rc = sqlite3_step(stmt);
   switch (rc) {
     case SQLITE_ROW:
-      row = row_to_hash(stmt, column_count, column_names);
-      if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
-      goto step;
+      return 1;
     case SQLITE_DONE:
-      break;
+      return 0;
     case SQLITE_BUSY:
-      sqlite3_finalize(stmt);
-      rb_raise(cError, "Database is busy");
+      rb_raise(cBusyError, "Database is busy");
     case SQLITE_ERROR:
-      sqlite3_finalize(stmt);
-      rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
+      rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
     default:
-      sqlite3_finalize(stmt);
       rb_raise(cError, "Invalid return code for sqlite3_step: %d", rc);
   }
-  // TODO, use ensure to finalize statement
-  sqlite3_finalize(stmt);
+
+  return 0;
+}
+
+typedef struct query_ctx {
+  VALUE self;
+  int argc;
+  VALUE *argv;
+  sqlite3_stmt *stmt;
+} query_ctx;
+
+VALUE cleanup_stmt(VALUE arg) {
+  query_ctx *ctx = (query_ctx *)arg;
+  sqlite3_finalize(ctx->stmt);
+  return Qnil;
+}
+
+#define check_arity_and_prepare_sql(argc, argv, sql) { \
+  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); \
+  sql = rb_funcall(argv[0], ID_STRIP, 0); \
+  if (RSTRING_LEN(sql) == 0) return Qnil; \
+}
+
+VALUE safe_query_hash(VALUE arg) {
+  query_ctx *ctx = (query_ctx *)arg;
+  Database_t *db;
+  VALUE result = ctx->self;
+  int yield_to_block = rb_block_given_p();
+  VALUE row;
+  VALUE sql;
+  int column_count;
+  VALUE column_names;
+
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
+
+  prepare_multi_stmt(db->sqlite3_db, &ctx->stmt, sql);
+  bind_all_parameters(ctx->stmt, ctx->argc, ctx->argv);
+  column_count = sqlite3_column_count(ctx->stmt);
+  column_names = get_column_names(ctx->stmt, column_count);
+
+  // block not given, so prepare the array of records to be returned
+  if (!yield_to_block) result = rb_ary_new();
+
+  while (stmt_iterate(ctx->stmt, db->sqlite3_db)) {
+    row = row_to_hash(ctx->stmt, column_count, column_names);
+    if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
+  }
+
   RB_GC_GUARD(column_names);
   RB_GC_GUARD(row);
   RB_GC_GUARD(result);
   return result;
 }
 
-static inline VALUE row_to_ary(sqlite3_stmt *stmt, int column_count) {
-  VALUE row = rb_ary_new2(column_count);
-  for (int i = 0; i < column_count; i++) {
-    VALUE value = get_column_value(stmt, i, sqlite3_column_type(stmt, i));
-    rb_ary_push(row, value);
-  }
-  return row;
+VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
+  query_ctx ctx = { self, argc, argv, 0 };
+  return rb_ensure(safe_query_hash, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
 }
 
-VALUE Database_query_ary(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
-  int column_count;
+VALUE safe_query_ary(VALUE arg) {
+  query_ctx *ctx = (query_ctx *)arg;
   Database_t *db;
-  VALUE result = self;
+  int column_count;
+  VALUE result = ctx->self;
   int yield_to_block = rb_block_given_p();
   VALUE row;
   VALUE sql;
 
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
-  sql = argv[0];
-  GetDatabase(self, db);
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  rc = sqlite3_prepare(db->sqlite3_db, RSTRING_PTR(sql), RSTRING_LEN(sql), &stmt, 0);
-  if (rc) {
-    fprintf(stderr, "Failed to prepare statement: %s\n", sqlite3_errmsg(db->sqlite3_db));
-    sqlite3_finalize(stmt);
-    // TODO: raise error
-    return Qfalse;
-  }
-
-  bind_all_parameters(stmt, argc, argv);
-  column_count = sqlite3_column_count(stmt);
+  prepare_multi_stmt(db->sqlite3_db, &ctx->stmt, sql);
+  bind_all_parameters(ctx->stmt, ctx->argc, ctx->argv);
+  column_count = sqlite3_column_count(ctx->stmt);
 
   // block not given, so prepare the array of records to be returned
   if (!yield_to_block) result = rb_ary_new();
-step:
-  rc = sqlite3_step(stmt);
-  switch (rc) {
-    case SQLITE_ROW:
-      row = row_to_ary(stmt, column_count);
-      if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
-      goto step;
-    case SQLITE_DONE:
-      break;
-    case SQLITE_BUSY:
-      rb_raise(cError, "Database is busy");
-    case SQLITE_ERROR:
-      rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    default:
-      rb_raise(cError, "Invalid return code for sqlite3_step: %d", rc);
+
+  while (stmt_iterate(ctx->stmt, db->sqlite3_db)) {
+    row = row_to_ary(ctx->stmt, column_count);
+    if (yield_to_block) rb_yield(row); else rb_ary_push(result, row);
   }
-  sqlite3_finalize(stmt);
+  
   RB_GC_GUARD(row);
   RB_GC_GUARD(result);
   return result;
 }
 
-VALUE Database_query_single_column(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
+VALUE Database_query_ary(int argc, VALUE *argv, VALUE self) {
+  query_ctx ctx = { self, argc, argv, 0 };
+  return rb_ensure(safe_query_ary, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
+}
+
+VALUE safe_query_single_row(VALUE arg) {
+  query_ctx *ctx = (query_ctx *)arg;
+  Database_t *db;
+  int column_count;
+  VALUE sql;
+  VALUE row = Qnil;
+  VALUE column_names;
+
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
+
+  prepare_multi_stmt(db->sqlite3_db, &ctx->stmt, sql);
+  bind_all_parameters(ctx->stmt, ctx->argc, ctx->argv);
+  column_count = sqlite3_column_count(ctx->stmt);
+  column_names = get_column_names(ctx->stmt, column_count);
+
+  if (stmt_iterate(ctx->stmt, db->sqlite3_db))
+    row = row_to_hash(ctx->stmt, column_count, column_names);
+
+  RB_GC_GUARD(row);
+  RB_GC_GUARD(column_names);
+  return row;
+}
+
+VALUE Database_query_single_row(int argc, VALUE *argv, VALUE self) {
+  query_ctx ctx = { self, argc, argv, 0 };
+  return rb_ensure(safe_query_single_row, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
+}
+
+VALUE safe_query_single_column(VALUE arg) {
+  query_ctx *ctx = (query_ctx *)arg;
+
   int column_count;
   Database_t *db;
-  VALUE result = self;
+  VALUE result = ctx->self;
   int yield_to_block = rb_block_given_p();
   VALUE sql;
   VALUE value;
 
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
-  sql = argv[0];
-  GetDatabase(self, db);
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  rc = sqlite3_prepare(db->sqlite3_db, RSTRING_PTR(sql), RSTRING_LEN(sql), &stmt, 0);
-  if (rc) {
-    fprintf(stderr, "Failed to prepare statement: %s\n", sqlite3_errmsg(db->sqlite3_db));
-    sqlite3_finalize(stmt);
-    // TODO: raise error
-    return Qfalse;
-  }
-
-  bind_all_parameters(stmt, argc, argv);
-  column_count = sqlite3_column_count(stmt);
+  prepare_multi_stmt(db->sqlite3_db, &ctx->stmt, sql);
+  bind_all_parameters(ctx->stmt, ctx->argc, ctx->argv);
+  column_count = sqlite3_column_count(ctx->stmt);
   if (column_count != 1)
     rb_raise(cError, "Expected query result to have 1 column");
 
   // block not given, so prepare the array of records to be returned
   if (!yield_to_block) result = rb_ary_new();
-step:
-  rc = sqlite3_step(stmt);
-  switch (rc) {
-    case SQLITE_ROW:
-      value = get_column_value(stmt, 0, sqlite3_column_type(stmt, 0));
-      if (yield_to_block) rb_yield(value); else rb_ary_push(result, value);
-      goto step;
-    case SQLITE_DONE:
-      break;
-    case SQLITE_BUSY:
-      rb_raise(cError, "Database is busy");
-    case SQLITE_ERROR:
-      rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    default:
-      rb_raise(cError, "Invalid return code for sqlite3_step: %d", rc);
+
+  while (stmt_iterate(ctx->stmt, db->sqlite3_db)) {
+    value = get_column_value(ctx->stmt, 0, sqlite3_column_type(ctx->stmt, 0));
+    if (yield_to_block) rb_yield(value); else rb_ary_push(result, value);
   }
 
-  sqlite3_finalize(stmt);
   RB_GC_GUARD(value);
   RB_GC_GUARD(result);
   return result;
 }
 
-VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
+VALUE Database_query_single_column(int argc, VALUE *argv, VALUE self) {
+  query_ctx ctx = { self, argc, argv, 0 };
+  return rb_ensure(safe_query_single_column, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
+}
+
+VALUE safe_query_single_value(VALUE arg) {
+  query_ctx *ctx = (query_ctx *)arg;
   int column_count;
   Database_t *db;
   VALUE sql;
   VALUE value = Qnil;
 
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
-  sql = argv[0];
-  GetDatabase(self, db);
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  rc = sqlite3_prepare(db->sqlite3_db, RSTRING_PTR(sql), RSTRING_LEN(sql), &stmt, 0);
-  if (rc) {
-    fprintf(stderr, "Failed to prepare statement: %s\n", sqlite3_errmsg(db->sqlite3_db));
-    sqlite3_finalize(stmt);
-    // TODO: raise error
-    return Qfalse;
-  }
-
-  bind_all_parameters(stmt, argc, argv);
-  column_count = sqlite3_column_count(stmt);
+  prepare_multi_stmt(db->sqlite3_db, &ctx->stmt, sql);
+  bind_all_parameters(ctx->stmt, ctx->argc, ctx->argv);
+  column_count = sqlite3_column_count(ctx->stmt);
   if (column_count != 1)
     rb_raise(cError, "Expected query result to have 1 column");
 
-  rc = sqlite3_step(stmt);
-  switch (rc) {
-    case SQLITE_ROW:
-      value = get_column_value(stmt, 0, sqlite3_column_type(stmt, 0));
-      break;
-    case SQLITE_BUSY:
-      rb_raise(cError, "Database is busy");
-    case SQLITE_ERROR:
-      rb_raise(cError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    default:
-      rb_raise(cError, "Invalid return code for sqlite3_step: %d", rc);
-  }
+  if (stmt_iterate(ctx->stmt, db->sqlite3_db))
+    value = get_column_value(ctx->stmt, 0, sqlite3_column_type(ctx->stmt, 0));
 
-  sqlite3_finalize(stmt);
   RB_GC_GUARD(value);
   return value;
 }
 
+VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
+  query_ctx ctx = { self, argc, argv, 0 };
+  return rb_ensure(safe_query_single_value, (VALUE)&ctx, cleanup_stmt, (VALUE)&ctx);
+}
+
 VALUE Database_last_insert_rowid(VALUE self) {
   Database_t *db;
   GetDatabase(self, db);
@@ -365,6 +401,21 @@ VALUE Database_transaction_active_p(VALUE self) {
   return sqlite3_get_autocommit(db->sqlite3_db) ? Qfalse : Qtrue;
 }
 
+VALUE Database_load_extension(VALUE self, VALUE path) {
+  Database_t *db;
+  GetDatabase(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;
+}
+
 void Init_Extralite() {
   VALUE mExtralite = rb_define_module("Extralite");
   VALUE cDatabase = rb_define_class_under(mExtralite, "Database", rb_cObject);
@@ -375,6 +426,7 @@ void Init_Extralite() {
   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);
   
@@ -382,6 +434,11 @@ void Init_Extralite() {
   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);
 
   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);
+
+  ID_STRIP = rb_intern("strip");
 }