extralite 0.6 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89b99ba7c6d26fc887574bf943f8e07f4c27f0c058a99723be73d7b64a90b3d5
-  data.tar.gz: 41c9bc62b91d78d0507d58b6a3e150608aae813b7b929410f23b0389a8b8c98f
+  metadata.gz: 9c69948d51f689ead3e4ccf008bc7b0670085d0c987d39359bb38172b9993b58
+  data.tar.gz: 776ed4e4f95cdb405b9b3be277d0aaa5a27fcd0e84aff8f6ebb3aeece531b1cf
 SHA512:
-  metadata.gz: 6c29b92468cdf3a2fe9f65088c579a901ff981b11c68d8dc32c99508c4ab7fae5a8d9a348e2310dcf18b0980edac9f3503889de76e097c6d27c6c3fb20480245
-  data.tar.gz: 49c703000e9285cff90dadd0d64f40690d96a6f6c59305021dca0561d41aff6fedcc64a4918ce16337acbb7537fd91c73f2b1d65953cdff8be591773844c3465
+  metadata.gz: 472db7ae94e195e647712ce04213538b229bcfebc3f9ec22b3f8e69dceb0a5cbba9000e14147a27ed2e26231aa7c73b43585a45be369f94d8cd2507643dd88b9
+  data.tar.gz: 6475f99ebe990b9b073f77379f58ddcd4fa0f678fb32e64b39021e3aa7b6d6f9343c8f02d69cce1826a9d156c8b0918985536732af5a11be2bda28524524e8c2

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 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`

data/Gemfile.lock

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

data/README.md

@@ -1,17 +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 methods for different data access patterns: row as hash, row as array, single
-  single row, 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.
+- Load extensions (loading of extensions is autmatically enabled. You can find
+  some useful extensions here: https://github.com/nalgeon/sqlean.)
 
 ### Usage
 
@@ -19,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 }]
@@ -53,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,6 +1,6 @@
 #include <stdio.h>
 #include "ruby.h"
-#include "../sqlite3/sqlite3.h"
+#include <sqlite3.h>
 
 VALUE cError;
 VALUE cSQLError;
@@ -165,235 +165,209 @@ inline void prepare_multi_stmt(sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
   }
 }
 
-VALUE Database_query_hash(int argc, VALUE *argv, VALUE self) {
+inline int stmt_iterate(sqlite3_stmt *stmt, sqlite3 *db) {
   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 = rb_funcall(argv[0], ID_STRIP, 0);
-  if (RSTRING_LEN(sql) == 0) return Qnil;
-
-  GetDatabase(self, db);
-
-  prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
-  bind_all_parameters(stmt, argc, argv);
-  column_count = sqlite3_column_count(stmt);
-  column_names = get_column_names(stmt, column_count);
-
-  // 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_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(cBusyError, "Database is busy");
     case SQLITE_ERROR:
-      sqlite3_finalize(stmt);
-      rb_raise(cSQLError, "%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;
 }
 
-VALUE Database_query_ary(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
-  int column_count;
+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 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 = rb_funcall(argv[0], ID_STRIP, 0);
-  if (RSTRING_LEN(sql) == 0) return Qnil;
-  GetDatabase(self, db);
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
-  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:
-      sqlite3_finalize(stmt);
-      rb_raise(cBusyError, "Database is busy");
-    case SQLITE_ERROR:
-      sqlite3_finalize(stmt);
-      rb_raise(cSQLError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    default:
-      sqlite3_finalize(stmt);
-      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_row(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
-  int column_count;
+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;
 
-  rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
-  sql = rb_funcall(argv[0], ID_STRIP, 0);
-  if (RSTRING_LEN(sql) == 0) return Qnil;
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  GetDatabase(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);
 
-  prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
-  bind_all_parameters(stmt, argc, argv);
-  column_count = sqlite3_column_count(stmt);
-  column_names = get_column_names(stmt, column_count);
+  if (stmt_iterate(ctx->stmt, db->sqlite3_db))
+    row = row_to_hash(ctx->stmt, column_count, column_names);
 
-  rc = sqlite3_step(stmt);
-  switch (rc) {
-    case SQLITE_ROW:
-      row = row_to_hash(stmt, column_count, column_names);
-      break;
-    case SQLITE_DONE:
-      break;
-    case SQLITE_BUSY:
-      rb_raise(cBusyError, "Database is busy");
-    case SQLITE_ERROR:
-      rb_raise(cSQLError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    default:
-      rb_raise(cError, "Invalid return code for sqlite3_step: %d", rc);
-  }
-
-  sqlite3_finalize(stmt);
   RB_GC_GUARD(row);
   RB_GC_GUARD(column_names);
   return row;
 }
 
-VALUE Database_query_single_column(int argc, VALUE *argv, VALUE self) {
-  int rc;
-  sqlite3_stmt* stmt;
+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 = rb_funcall(argv[0], ID_STRIP, 0);
-  if (RSTRING_LEN(sql) == 0) return Qnil;
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  GetDatabase(self, db);
-
-  prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
-  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:
-      sqlite3_finalize(stmt);
-      rb_raise(cBusyError, "Database is busy");
-    case SQLITE_ERROR:
-      sqlite3_finalize(stmt);
-      rb_raise(cSQLError, "%s", sqlite3_errmsg(db->sqlite3_db));
-    default:
-      sqlite3_finalize(stmt);
-      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 = rb_funcall(argv[0], ID_STRIP, 0);
-  if (RSTRING_LEN(sql) == 0) return Qnil;
-
-  GetDatabase(self, db);
+  check_arity_and_prepare_sql(ctx->argc, ctx->argv, sql);
+  GetDatabase(ctx->self, db);
 
-  prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
-  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_DONE:
-      break;
-    case SQLITE_BUSY:
-      rb_raise(cBusyError, "Database is busy");
-    case SQLITE_ERROR:
-      rb_raise(cSQLError, "%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);