extralite 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22e7b14b0233f008d2b7e0c252d14eee96c736f028266eac5be6193356ce9969
-  data.tar.gz: a2e4b6c13ecb6bf1c660b621c3da919ff9ab9d460cefe6bf1d4a2dc06e16b285
+  metadata.gz: d0aae9850a753861706c0f8d5dc7323f5e682524767dc2a170c984ab56a52fc3
+  data.tar.gz: 475a2af8fce7e4d2c020ae1c0501bf54917c2ca6002ea69b702f1b48f9b076ad
 SHA512:
-  metadata.gz: 79b7e334dc09a45c6819027e8d6ee3a2e2e16faa82f4811989562caba93a688a629c78d9c3a53564d89a47ca9aa7ee9f2447663761d8931dd0cf2c4d69a8ed15
-  data.tar.gz: 9312ce8e55e1bfb121f36c93820b701217fc5abb90b5d3c2995a871c0ced0f876d9abd26b6a60cdcc57bb920a982eeb3ce572dd1f6c674a56f8227abde7fd19a
+  metadata.gz: 40241318fd77231731516f2a033ae2df6e08c97c264977e067c0e5e8d536cba3ba373a78df087b20bcefd244c78d45198f752808ba289aeb2ea8a40b280291f4
+  data.tar.gz: a4108bc234202f71971a7c0bb3360c44bdf16241cadd6b4411bc522e63742e2f86f9d876deac71648ddd787ff161b8d746b63c2107d1e3e492edca2508ee7aa5

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 3.1.0 2026-09-22
+
+- Update bundled SQLite to 3.53.4
+- Add `stmt_cache` option to `Database#initialize`
+- Implement automatic stmt caching for parametric queries
+- Change handling of multi stmt query and execute invocations.
+  - For #execute, accept multiple statements but raise error if parameters are given
+  - For #query, raise error on multiple statements
+
 ## 3.0.1 2026-07-21
 
 - Fix passing nil transform to `DB#prepare`

data/README.md

@@ -32,7 +32,7 @@ databases.
 Extralite comes in two flavors: the `extralite` gem which uses the
 system-installed sqlite3 library, and the `extralite-bundle` gem which bundles
 the latest version of SQLite
-([3.53.3](https://sqlite.org/releaselog/3_53_3.html)), offering access to the
+([3.53.4](https://sqlite.org/releaselog/3_53_4.html)), offering access to the
 latest features and enhancements.
 
 ## Features
@@ -49,6 +49,7 @@ latest features and enhancements.
   allowing iterating through single records or batches of records.
 - [Prepared queries](#prepared-queries).
 - [Parameter binding](#parameter-binding).
+- [Automatic query caching] for queries with parameters.
 - [Batch execution](#batch-execution-of-queries) of queries.
 - [transactions and savepoints](#transactions-and-savepoints).
 - Advanced features: load [SQLite extensions](#loading-extensions), create
@@ -69,6 +70,7 @@ latest features and enhancements.
 - [Data Types](#data-types)
 - [Prepared Queries](#prepared-queries)
 - [Batch Execution of Queries](#batch-execution-of-queries)
+- [Automatic query caching](#automatic-query-caching)
 - [Transactions and Savepoints](#transactions-and-savepoints)
 - [Database Information](#database-information)
 - [Error Handling](#error-handling)
@@ -653,6 +655,13 @@ query.batch_query([[42, 3], [43, 6]])
 #=> [{ x: 42, y: 2, z: 3 }, { x: 43, y: 5, z: 6 }]
 ```
 
+## Automatic query caching
+
+Extralite implements automatic caching of parametric queries. This means that
+any time you run one of the `execute` or `query_xxx` methods with parameters,
+Extralite will only prepare the query once, and the underlying `sqlite_stmt`
+object will be cached for reuse.
+
 ## Transactions and Savepoints
 
 All reads and writes to SQLite databases occur within a

data/Rakefile

@@ -28,7 +28,7 @@ end
 task :release do
   require_relative './lib/extralite/version'
   version = Extralite::VERSION
-  
+
   puts 'Building extralite...'
   `gem build extralite.gemspec`
 
@@ -66,4 +66,4 @@ begin
   end
 rescue LoadError => e
   warn("NOTE: ruby_memcheck is not available in this environment: #{e}")
-end
+end

data/TODO.md

@@ -28,7 +28,7 @@ end
 ]
 ```
 
-- Can we get rid of the hash container?
+- Use single value instead of hash
 
 ```ruby
 Extralite::Transform.new do
@@ -38,7 +38,7 @@ Extralite::Transform.new do
     content: text,
     _tag_id: skip,
     tags: [
-      name: text
+      { name: text.unbox }
     ]
   }
 end

data/examples/pubsub_store_polyphony.rb

@@ -62,7 +62,7 @@ class PubSub
     create table if not exists messages(
       subscriber_id integer,
       topic text,
-      message text, 
+      message text,
       foreign key (subscriber_id, topic)
         references subscriber_topics(subscriber_id, topic)
         on delete cascade

data/ext/extralite/common.c

@@ -157,11 +157,6 @@ static inline void column_names_set(struct column_names *names, int idx, VALUE v
     rb_ary_push(names->array, value);
 }
 
-static inline VALUE column_names_get(struct column_names *names, int idx) {
-  return (names->count <= MAX_EMBEDDED_COLUMN_NAMES) ?
-    names->names[idx] : RARRAY_AREF(names->array, idx);
-}
-
 static inline struct column_names get_column_names(sqlite3_stmt *stmt, int column_count) {
   struct column_names names;
   column_names_setup(&names, column_count);
@@ -213,108 +208,202 @@ static inline void row_to_splat_values(sqlite3_stmt *stmt, int column_count, VAL
   }
 }
 
-typedef struct {
-  sqlite3 *db;
-  sqlite3_stmt **stmt;
-  const char *str;
-  long len;
-  int rc;
-} prepare_stmt_ctx;
+static inline void lookup_cache_entry(stmt_ctx *ctx) {
+  VALUE cached = rb_hash_aref(ctx->stmt_cache, ctx->sql);
+  *(ctx->stmtptr) = NIL_P(cached) ? NULL : (sqlite3_stmt *)NUM2ULONG(cached);
+  if (*(ctx->stmtptr)) {
+    sqlite3_reset(*(ctx->stmtptr));
+    ctx->flags |= STMT_CTX_F_CACHE_HIT;
+  }
+}
+
+static inline void finalize_stmt_ctx(stmt_ctx *ctx) {
+  if (!*(ctx->stmtptr)) return;
+
+  if (!(ctx->flags & STMT_CTX_F_USE_CACHE)) {
+    sqlite3_finalize(*(ctx->stmtptr));
+    *(ctx->stmtptr) = NULL;
+    return;
+  }
+
+  if (!(ctx->flags & STMT_CTX_F_CACHE_HIT))
+    rb_hash_aset(ctx->stmt_cache, ctx->sql, ULONG2NUM((uint64_t)*(ctx->stmtptr)));
+}
+
+void make_stmt_ctx(
+  stmt_ctx *ctx, Database_t *db, sqlite3_stmt **stmt, VALUE sql, int argc, VALUE *argv
+) {
+  ctx->stmt_cache = db->stmt_cache;
+  ctx->sql = sql;
+
+  ctx->db = db->sqlite3_db;
+  ctx->stmtptr = stmt;
+
+  int use_cache = (argc > 0) && (db->flags & DB_F_STMT_CACHE);
+  ctx->flags = use_cache ? STMT_CTX_F_USE_CACHE : 0;
+  if (use_cache) {
+    lookup_cache_entry(ctx);
+    if (ctx->flags & STMT_CTX_F_CACHE_HIT)
+      sqlite3_clear_bindings(*(ctx->stmtptr));
+  }
+
+  if (!use_cache || !(*(ctx->stmtptr))) {
+    ctx->str = RSTRING_PTR(sql);
+    ctx->len = RSTRING_LEN(sql);
+  }
+
+  ctx->gvl_mode = db->gvl_release_threshold < 0 ? GVL_HOLD : GVL_RELEASE;
+  ctx->rc = 0;
+  ctx->total_changes = 0;
+  ctx->argc = argc;
+  ctx->argv = argv;
+}
+
+static inline int exec_stmt_iterate(sqlite3_stmt *stmt) {
+  while (true) {
+    int rc = sqlite3_step(stmt);
+    switch (rc) {
+      case SQLITE_ROW:  continue;
+      case SQLITE_DONE: return 0;
+      default:          return rc;
+    }
+  }
+}
+
+static inline void finalize_stmt(sqlite3_stmt **stmt) {
+  if (*stmt) {
+    sqlite3_finalize(*stmt);
+    *stmt = NULL;
+  }
+}
+
+static inline void *exec_bind_parameters(void *ptr) {
+  stmt_ctx *ctx = (stmt_ctx *)ptr;
+  bind_all_parameters(*(ctx->stmtptr), ctx->argc, ctx->argv);
+  return NULL;
+}
+
+void *exec_multi_stmt_impl(void *ptr) {
+  stmt_ctx *ctx = (stmt_ctx *)ptr;
+
+  if (ctx->flags & STMT_CTX_F_CACHE_HIT) {
+    rb_thread_call_with_gvl(exec_bind_parameters, ctx);
+    ctx->rc = exec_stmt_iterate(*(ctx->stmtptr));
+    if (ctx->rc == SQLITE_OK)
+      ctx->total_changes += sqlite3_changes(ctx->db);
+    else
+      ctx->total_changes = 0;
+    finalize_stmt_ctx(ctx);
+    return NULL;
+  }
 
-void *prepare_multi_stmt_impl(void *ptr) {
-  prepare_stmt_ctx *ctx = (prepare_stmt_ctx *)ptr;
   const char *rest = NULL;
   const char *str = ctx->str;
   const char *end = ctx->str + ctx->len;
+  sqlite3_stmt *next_stmt = NULL;
+  ctx->total_changes = 0;
   while (1) {
-    ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmt, &rest);
-    if (ctx->rc) {
-      // error
-      sqlite3_finalize(*ctx->stmt);
-      return NULL;
+    if (next_stmt) {
+      *(ctx->stmtptr) = next_stmt;
+      next_stmt = NULL;
+      ctx->rc = SQLITE_OK;
+    }
+    else
+      ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmtptr, &rest);
+
+    if ((ctx->rc != SQLITE_OK) || !(*(ctx->stmtptr))) goto done;
+    if (ctx->argc) {
+      // parameters were provided - check if str contains multiple statements
+      if (rest != end) {
+        int res = sqlite3_prepare_v2(ctx->db, rest, end-rest, &next_stmt, NULL);
+        if (next_stmt) res = SQLITE_MISUSE;
+        if (res != SQLITE_OK) {
+          ctx->rc = res;
+          goto done;
+        }
+      }
+      rb_thread_call_with_gvl(exec_bind_parameters, ctx);
     }
 
-    if (rest == end) return NULL;
+    ctx->rc = exec_stmt_iterate(*(ctx->stmtptr));
+    if (ctx->rc != SQLITE_OK) goto done;
 
-    // perform current query, but discard its results
-    ctx->rc = sqlite3_step(*ctx->stmt);
-    sqlite3_finalize(*ctx->stmt);
-    switch (ctx->rc) {
-    case SQLITE_BUSY:
-    case SQLITE_ERROR:
-    case SQLITE_MISUSE:
-      return NULL;
-    }
+    ctx->total_changes += sqlite3_changes(ctx->db);
+    finalize_stmt_ctx(ctx);
+
+    if (rest == end) return NULL;
     str = rest;
   }
+done:
+  finalize_stmt(&next_stmt);
+  finalize_stmt_ctx(ctx);
   return NULL;
 }
 
+inline int raise_error(stmt_ctx *ctx) {
+  switch (ctx->rc) {
+  case SQLITE_BUSY:
+    rb_raise(cBusyError, "Database is busy");
+  case SQLITE_ERROR:
+    rb_raise(cSQLError, "%s", sqlite3_errmsg(ctx->db));
+  case SQLITE_MISUSE:
+    rb_raise(cError, "Multiple statements cannot take parameters");
+  default:
+    rb_raise(cError, "%s", sqlite3_errmsg(ctx->db));
+  }
+  return 0;
+}
+
 /*
 This function prepares a statement from an SQL string containing one or more SQL
 statements. It will release the GVL while the statements are being prepared and
 executed. All statements excluding the last one are executed. The last statement
 is not executed, but instead handed back to the caller for looping over results.
+
+@return [int] total changes
 */
-void prepare_multi_stmt(enum gvl_mode mode, sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
-  prepare_stmt_ctx ctx = {db, stmt, RSTRING_PTR(sql), RSTRING_LEN(sql), 0};
-  gvl_call(mode, prepare_multi_stmt_impl, (void *)&ctx);
-  RB_GC_GUARD(sql);
+int exec_multi_stmt(stmt_ctx *ctx) {
+  gvl_call(ctx->gvl_mode, exec_multi_stmt_impl, (void *)ctx);
+  if (ctx->rc == SQLITE_OK) return ctx->total_changes;
 
-  switch (ctx.rc) {
-  case 0:
-    return;
-  case SQLITE_BUSY:
-    rb_raise(cBusyError, "Database is busy");
-  case SQLITE_ERROR:
-    rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
-  default:
-    rb_raise(cError, "%s", sqlite3_errmsg(db));
-  }
+  if (*(ctx->stmtptr)) sqlite3_finalize(*(ctx->stmtptr));
+  return raise_error(ctx);
 }
 
-#define SQLITE_MULTI_STMT -1
+////////////////////////////////////////////////////////////////////////////////
+
+void *prep_single_stmt_impl(void *ptr) {
+  stmt_ctx *ctx = (stmt_ctx *)ptr;
+
+  if (ctx->flags & STMT_CTX_F_CACHE_HIT) return NULL;
 
-void *prepare_single_stmt_impl(void *ptr) {
-  prepare_stmt_ctx *ctx = (prepare_stmt_ctx *)ptr;
   const char *rest = NULL;
   const char *str = ctx->str;
   const char *end = ctx->str + ctx->len;
 
-  ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmt, &rest);
-  if (ctx->rc)
-    goto discard_stmt;
-  else if (rest != end) {
-    ctx->rc = SQLITE_MULTI_STMT;
-    goto discard_stmt;
+  ctx->rc = sqlite3_prepare_v2(ctx->db, str, end - str, ctx->stmtptr, &rest);
+  if (ctx->rc != SQLITE_OK) {
+    finalize_stmt(ctx->stmtptr);
+    return NULL;
   }
-  goto end;
-discard_stmt:
-  if (*ctx->stmt) {
-    sqlite3_finalize(*ctx->stmt);
-    *ctx->stmt = NULL;
+  if (rest != end) {
+    sqlite3_stmt *next = NULL;
+    ctx->rc = sqlite3_prepare_v2(ctx->db, rest, end - rest, &next, NULL);
+    if (next) {
+      sqlite3_finalize(next);
+      ctx->rc = SQLITE_MISUSE;
+    }
+    if (ctx->rc != SQLITE_OK) finalize_stmt(ctx->stmtptr);
   }
-end:
   return NULL;
 }
 
-void prepare_single_stmt(enum gvl_mode mode, sqlite3 *db, sqlite3_stmt **stmt, VALUE sql) {
-  prepare_stmt_ctx ctx = {db, stmt, RSTRING_PTR(sql), RSTRING_LEN(sql), 0};
-  gvl_call(mode, prepare_single_stmt_impl, (void *)&ctx);
-  RB_GC_GUARD(sql);
+void prep_single_stmt(stmt_ctx *ctx) {
+  gvl_call(ctx->gvl_mode, prep_single_stmt_impl, (void *)ctx);
+  if (ctx->rc == SQLITE_OK) return;
 
-  switch (ctx.rc) {
-  case 0:
-    return;
-  case SQLITE_BUSY:
-    rb_raise(cBusyError, "Database is busy");
-  case SQLITE_ERROR:
-    rb_raise(cSQLError, "%s", sqlite3_errmsg(db));
-  case SQLITE_MULTI_STMT:
-    rb_raise(cError, "A prepared statement does not accept SQL strings with multiple queries");
-  default:
-    rb_raise(cError, "%s", sqlite3_errmsg(db));
-  }
+  if (*(ctx->stmtptr)) sqlite3_finalize(*(ctx->stmtptr));
+  raise_error(ctx);
 }
 
 struct step_ctx {
@@ -362,7 +451,15 @@ inline int stmt_iterate(query_ctx *ctx) {
 }
 
 VALUE cleanup_stmt(query_ctx *ctx) {
-  if (ctx->stmt) sqlite3_finalize(ctx->stmt);
+  if (!ctx->stmt) goto done;
+
+  if (ctx->flags & STMT_CTX_F_USE_CACHE) {
+    if (!(ctx->flags & STMT_CTX_F_CACHE_HIT))
+      rb_hash_aset(ctx->db->stmt_cache, ctx->sql, ULONG2NUM((uint64_t)(ctx->stmt)));
+  }
+  else
+    sqlite3_finalize(ctx->stmt);
+done:
   return Qnil;
 }
 
@@ -517,7 +614,7 @@ VALUE safe_query_transform(query_ctx *ctx) {
   VALUE array = rb_ary_new();
   VALUE identity_storage = rb_hash_new();
   VALUE row = Qnil;
-  // int column_count = sqlite3_column_count(ctx->stmt);
+  // int column_count = sqlite3_column_count(ctx->stmtptr);
   struct transform_node *transform_root = get_transform_root(ctx->transform);
 
   int row_count = 0;
@@ -542,17 +639,17 @@ done:
       return rb_ary_entry(array, 0);
   }
 
-  return Qnil;
   RB_GC_GUARD(identity_storage);
   RB_GC_GUARD(row);
   RB_GC_GUARD(array);
+  return Qnil;
 }
 
 VALUE safe_query_single_row_transform(query_ctx *ctx) {
   VALUE array = rb_ary_new();
   VALUE identity_storage = rb_hash_new();
   VALUE row = Qnil;
-  // int column_count = sqlite3_column_count(ctx->stmt);
+  // int column_count = sqlite3_column_count(ctx->stmtptr);
   struct transform_node *transform_root = get_transform_root(ctx->transform);
 
   int row_count = 0;
@@ -572,10 +669,10 @@ VALUE safe_query_single_row_transform(query_ctx *ctx) {
       return row;
   }
 
-  return Qnil;
   RB_GC_GUARD(identity_storage);
   RB_GC_GUARD(row);
   RB_GC_GUARD(array);
+  return Qnil;
 }
 
 VALUE safe_query_splat(query_ctx *ctx);
@@ -1008,3 +1105,7 @@ VALUE safe_query_changes(query_ctx *ctx) {
   while (stmt_iterate(ctx));
   return INT2FIX(sqlite3_changes(ctx->sqlite3_db));
 }
+
+VALUE safe_total_changes(query_ctx *ctx) {
+  return INT2FIX(ctx->total_changes);
+}