extralite 2.0 → 2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d399062a5652d11c0e969dfb74f6c998015980e8831e221d2aece7ddb6cfc83d
-  data.tar.gz: '0759cd16b15124934c52d5e2a3f36620b165f5a205aaea707c3d957503038173'
+  metadata.gz: bd8cf56eff701ddf57586d6f7510d5959cdf81ff15e6a64c6ed8ff698f93b43b
+  data.tar.gz: 42000f8c83849577fd1672996969961357c5bbadb82d89d2168c74be7acfa303
 SHA512:
-  metadata.gz: 62ad641bd7661d326c3ba83eff0e7ecf5befdd12d7267608e748d6a7cf586d96e9f870cd179989cabb230b822e9d245ff9d1ed8877632ca33c7577858a639ded
-  data.tar.gz: 2984632a7bb790b354713396ac00856f0646c79aa22bb3a9bcd26995a127eb8cb86a5ca64efcbd91b1fcc8dd5a41f95e0bacefed7b5bacd477e9b689d79186a6
+  metadata.gz: 1159c965d8ce9bfade2c81de97b6ef311dcfdb84ce65eb85238aa6a23b29b786d31de2bb8f30f87a24a800b88d01475a7cb400b97245401d587bef365b140087
+  data.tar.gz: 74f975529a9efb7291524eaa4c285fadc6976377a607cd28e72cbd3010cbc9fd061264aabb9a5df1ce864f097ca330c9acd9dded62b8de7cc63c1217be88412a

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 2.1 2023-07-11
+
+- Implement `Database#execute`, `Query#execute` for data-manipulation queries
+- Add option for opening databases for read only access
+
 # 2.0 2023-07-08
 
 - Fix Sequel migrations (#8)

data/Gemfile.lock

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

data/TODO.md

@@ -1,5 +1,21 @@
-- Add option to open database in readonly mode, use sqlite3_open_v2
-  https://sqlite.org/c3ref/open.html
-
 - Improve tracing
-- Add `#inspect` method for `Database`, `Query`, `Iterator` classes
+- Transactions and savepoints:
+
+  - `DB#transaction {}` - does a `BEGIN..COMMIT` - non-reentrant!
+  - `DB#savepoint(name)` - creates a savepoint
+  - `DB#release(name)` - releases a savepoint
+  - `DB#rollback` - raises `Extralite::Rollback`, which is rescued by `DB#transaction`
+  - `DB#rollback_to(name)` - rolls back to a savepoint
+
+- More database methods:
+
+  - `Database#quote`
+  - `Database#busy_timeout=` https://sqlite.org/c3ref/busy_timeout.html
+  - `Database#cache_flush` https://sqlite.org/c3ref/db_cacheflush.html
+  - `Database#release_memory` https://sqlite.org/c3ref/db_release_memory.html
+
+- Security
+
+  - Enable extension loading by using
+    [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION](https://www.sqlite.org/c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableloadextension)
+    in order to prevent usage of `load_extension()` SQL function.

data/ext/extralite/common.c

@@ -396,3 +396,8 @@ VALUE safe_execute_multi(query_ctx *ctx) {
 VALUE safe_query_columns(query_ctx *ctx) {
   return get_column_names(ctx->stmt, sqlite3_column_count(ctx->stmt));
 }
+
+VALUE safe_query_changes(query_ctx *ctx) {
+  while (stmt_iterate(ctx));
+  return INT2FIX(sqlite3_changes(ctx->sqlite3_db));
+}

data/ext/extralite/database.c

@@ -6,6 +6,7 @@ VALUE cError;
 VALUE cSQLError;
 VALUE cBusyError;
 VALUE cInterruptError;
+VALUE eArgumentError;
 
 ID ID_bind;
 ID ID_call;
@@ -14,6 +15,8 @@ ID ID_new;
 ID ID_strip;
 ID ID_to_s;
 
+VALUE SYM_read_only;
+
 static size_t Database_size(const void *ptr) {
   return sizeof(Database_t);
 }
@@ -36,27 +39,21 @@ static VALUE Database_allocate(VALUE klass) {
   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"); \
-  } \
+inline Database_t *self_to_database(VALUE self) {
+  Database_t *db;
+  TypedData_Get_Struct(self, Database_t, &Database_type, db);
+  return db;
 }
 
-Database_t *Database_struct(VALUE self) {
-  Database_t *db;
-  GetDatabase(self, db);
+inline Database_t *self_to_open_database(VALUE self) {
+  Database_t *db = self_to_database(self);
+  if (!(db)->sqlite3_db) rb_raise(cError, "Database is closed");
+  
   return db;
 }
 
-sqlite3 *Database_sqlite3_db(VALUE self) {
-  Database_t *db;
-  GetDatabase(self, db);
-  return db->sqlite3_db;
+inline sqlite3 *Database_sqlite3_db(VALUE self) {
+  return self_to_database(self)->sqlite3_db;
 }
 
 /* call-seq:
@@ -69,18 +66,37 @@ VALUE Extralite_sqlite3_version(VALUE self) {
   return rb_str_new_cstr(sqlite3_version);
 }
 
-/* call-seq:
- *   db.initialize(path)
+static inline int db_open_flags_from_opts(VALUE opts) {
+  if (opts == Qnil) goto default_flags;
+
+  if (TYPE(opts) != T_HASH)
+    rb_raise(eArgumentError, "Expected hash as database initialization options");
+
+  VALUE read_only = rb_hash_aref(opts, SYM_read_only);
+  if (RTEST(read_only)) return SQLITE_OPEN_READONLY;
+default_flags:
+  return SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
+}
+
+/* Initializes a new SQLite database with the given path and options.
  *
- * Initializes a new SQLite database with the given path.
+ * @overload initialize(path)
+ *   @param path [String] file path (or ':memory:' for memory database)
+ *   @return [void]
+ * @overload initialize(path, read_only: false)
+ *   @param path [String] file path (or ':memory:' for memory database)
+ *   @param read_only [boolean] true for opening the database for reading only
+ *   @return [void]
  */
+VALUE Database_initialize(int argc, VALUE *argv, VALUE self) {
+  Database_t *db = self_to_database(self);
+  VALUE path;
+  VALUE opts = Qnil;
 
-VALUE Database_initialize(VALUE self, VALUE path) {
-  int rc;
-  Database_t *db;
-  GetDatabase(self, db);
+  rb_scan_args(argc, argv, "11", &path, &opts);
+  int flags = db_open_flags_from_opts(opts);
 
-  rc = sqlite3_open(StringValueCStr(path), &db->sqlite3_db);
+  int rc = sqlite3_open_v2(StringValueCStr(path), &db->sqlite3_db, flags, NULL);
   if (rc) {
     sqlite3_close_v2(db->sqlite3_db);
     rb_raise(cError, "%s", sqlite3_errstr(rc));
@@ -106,6 +122,16 @@ VALUE Database_initialize(VALUE self, VALUE path) {
   return Qnil;
 }
 
+/* Returns true if the database was open for read only access.
+ *
+ * @return [boolean] true if database is open for read only access
+ */
+VALUE Database_read_only_p(VALUE self) {
+  Database_t *db = self_to_database(self);
+  int open = sqlite3_db_readonly(db->sqlite3_db, "main");
+  return (open == 1) ? Qtrue : Qfalse;
+}
+
 /* call-seq:
  *   db.close -> db
  *
@@ -113,8 +139,7 @@ VALUE Database_initialize(VALUE self, VALUE path) {
  */
 VALUE Database_close(VALUE self) {
   int rc;
-  Database_t *db;
-  GetDatabase(self, db);
+  Database_t *db = self_to_database(self);
 
   rc = sqlite3_close_v2(db->sqlite3_db);
   if (rc) {
@@ -133,14 +158,12 @@ VALUE Database_close(VALUE self) {
  * @return [bool] is database closed
  */
 VALUE Database_closed_p(VALUE self) {
-  Database_t *db;
-  GetDatabase(self, db);
-
+  Database_t *db = self_to_database(self);
   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;
+  Database_t *db = self_to_open_database(self);
   sqlite3_stmt *stmt;
   VALUE sql;
 
@@ -150,7 +173,6 @@ static inline VALUE Database_perform_query(int argc, VALUE *argv, VALUE self, VA
   if (RSTRING_LEN(sql) == 0) return Qnil;
 
   // prepare query ctx
-  GetOpenDatabase(self, db);
   if (db->trace_block != Qnil) rb_funcall(db->trace_block, ID_call, 1, sql);
   prepare_multi_stmt(db->sqlite3_db, &stmt, sql);
   RB_GC_GUARD(sql);
@@ -286,6 +308,31 @@ 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.execute(sql, *parameters) -> changes
+ *
+ * Runs a query returning the total changes effected. This method should be used
+ * for data- or schema-manipulation queries.
+ *
+ * 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.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:
+ *
+ *     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);
+}
+
 /* call-seq:
  *   db.execute_multi(sql, params_array) -> changes
  *
@@ -301,13 +348,12 @@ VALUE Database_query_single_value(int argc, VALUE *argv, VALUE self) {
  *
  */
 VALUE Database_execute_multi(VALUE self, VALUE sql, VALUE params_array) {
-  Database_t *db;
+  Database_t *db = self_to_open_database(self);
   sqlite3_stmt *stmt;
 
   if (RSTRING_LEN(sql) == 0) return Qnil;
 
   // prepare query ctx
-  GetOpenDatabase(self, db);
   prepare_single_stmt(db->sqlite3_db, &stmt, sql);
   query_ctx ctx = { self, db->sqlite3_db, stmt, params_array, QUERY_MODE(QUERY_MULTI_ROW), ALL_ROWS };
 
@@ -329,8 +375,7 @@ VALUE Database_columns(VALUE self, VALUE sql) {
  * Returns the rowid of the last inserted row.
  */
 VALUE Database_last_insert_rowid(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   return INT2FIX(sqlite3_last_insert_rowid(db->sqlite3_db));
 }
@@ -341,8 +386,7 @@ VALUE Database_last_insert_rowid(VALUE self) {
  * Returns the number of changes made to the database by the last operation.
  */
 VALUE Database_changes(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   return INT2FIX(sqlite3_changes(db->sqlite3_db));
 }
@@ -355,8 +399,7 @@ VALUE Database_changes(VALUE self) {
 VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
   const char *db_name;
   const char *filename;
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   rb_check_arity(argc, 0, 1);
   db_name = (argc == 1) ? StringValueCStr(argv[0]) : "main";
@@ -370,8 +413,7 @@ VALUE Database_filename(int argc, VALUE *argv, VALUE self) {
  * Returns true if a transaction is currently in progress.
  */
 VALUE Database_transaction_active_p(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   return sqlite3_get_autocommit(db->sqlite3_db) ? Qfalse : Qtrue;
 }
@@ -383,8 +425,7 @@ VALUE Database_transaction_active_p(VALUE self) {
  * Loads an extension with the given path.
  */
 VALUE Database_load_extension(VALUE self, VALUE path) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
   char *err_msg;
 
   int rc = sqlite3_load_extension(db->sqlite3_db, RSTRING_PTR(path), 0, &err_msg);
@@ -422,8 +463,7 @@ VALUE Database_prepare(int argc, VALUE *argv, VALUE self) {
  * For more information, consult the [sqlite3 API docs](https://sqlite.org/c3ref/interrupt.html).
  */
 VALUE Database_interrupt(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   sqlite3_interrupt(db->sqlite3_db);
   return self;
@@ -515,8 +555,7 @@ VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
 
   int dst_is_fn = TYPE(dst) == T_STRING;
 
-  Database_t *src;
-  GetOpenDatabase(self, src);
+  Database_t *src = self_to_open_database(self);
   sqlite3 *dst_db;
 
   if (dst_is_fn) {
@@ -527,8 +566,7 @@ VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
     }
   }
   else {
-    Database_t *dst_struct;
-    GetOpenDatabase(dst, dst_struct);
+    Database_t *dst_struct = self_to_open_database(dst);
     dst_db = dst_struct->sqlite3_db;
   }
 
@@ -583,8 +621,7 @@ VALUE Database_status(int argc, VALUE *argv, VALUE self) {
 
   rb_scan_args(argc, argv, "11", &op, &reset);
 
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   int rc = sqlite3_db_status(db->sqlite3_db, NUM2INT(op), &cur, &hwm, RTEST(reset) ? 1 : 0);
   if (rc != SQLITE_OK) rb_raise(cError, "%s", sqlite3_errstr(rc));
@@ -604,8 +641,7 @@ VALUE Database_limit(int argc, VALUE *argv, VALUE self) {
 
   rb_scan_args(argc, argv, "11", &category, &new_value);
 
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   int value = sqlite3_limit(db->sqlite3_db, NUM2INT(category), RTEST(new_value) ? NUM2INT(new_value) : -1);
 
@@ -622,8 +658,7 @@ VALUE Database_limit(int argc, VALUE *argv, VALUE self) {
  * disable the busy timeout, set it to 0 or nil.
  */
 VALUE Database_busy_timeout_set(VALUE self, VALUE sec) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   int ms = (sec == Qnil) ? 0 : (int)(NUM2DBL(sec) * 1000);
   int rc = sqlite3_busy_timeout(db->sqlite3_db, ms);
@@ -638,8 +673,7 @@ VALUE Database_busy_timeout_set(VALUE self, VALUE sec) {
  * Returns the total number of changes made to the database since opening it.
  */
 VALUE Database_total_changes(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   int value = sqlite3_total_changes(db->sqlite3_db);
   return INT2NUM(value);
@@ -653,8 +687,7 @@ VALUE Database_total_changes(VALUE self) {
  * executed.
  */
 VALUE Database_trace(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   db->trace_block = rb_block_given_p() ? rb_block_proc() : Qnil;
   return self;
@@ -666,8 +699,7 @@ VALUE Database_trace(VALUE self) {
  * Returns the last error code for the database.
  */
 VALUE Database_errcode(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   return INT2NUM(sqlite3_errcode(db->sqlite3_db));
 }
@@ -678,8 +710,7 @@ VALUE Database_errcode(VALUE self) {
  * Returns the last error message for the database.
  */
 VALUE Database_errmsg(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   return rb_str_new2(sqlite3_errmsg(db->sqlite3_db));
 }
@@ -691,13 +722,25 @@ VALUE Database_errmsg(VALUE self) {
  * Returns the offset for the last error
  */
 VALUE Database_error_offset(VALUE self) {
-  Database_t *db;
-  GetOpenDatabase(self, db);
+  Database_t *db = self_to_open_database(self);
 
   return INT2NUM(sqlite3_error_offset(db->sqlite3_db));
 }
 #endif
 
+/* Returns a short string representation of the database instance, including the
+ * database filename.
+ *
+ * @return [String] string representation
+ */
+VALUE Database_inspect(VALUE self) {
+  VALUE cname = rb_class_name(CLASS_OF(self));
+  VALUE filename = Database_filename(0, NULL, self);
+  if (RSTRING_LEN(filename) == 0) filename = rb_str_new_literal(":memory:");
+
+  return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, filename);
+}
+
 void Init_ExtraliteDatabase(void) {
   VALUE mExtralite = rb_define_module("Extralite");
   rb_define_singleton_method(mExtralite, "runtime_status", Extralite_runtime_status, -1);
@@ -719,9 +762,11 @@ void Init_ExtraliteDatabase(void) {
   rb_define_method(cDatabase, "error_offset", Database_error_offset, 0);
   #endif
 
+  rb_define_method(cDatabase, "execute", Database_execute, -1);
   rb_define_method(cDatabase, "execute_multi", Database_execute_multi, 2);
   rb_define_method(cDatabase, "filename", Database_filename, -1);
-  rb_define_method(cDatabase, "initialize", Database_initialize, 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);
@@ -732,6 +777,7 @@ void Init_ExtraliteDatabase(void) {
   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);
@@ -750,10 +796,15 @@ void Init_ExtraliteDatabase(void) {
   rb_gc_register_mark_object(cBusyError);
   rb_gc_register_mark_object(cInterruptError);
 
+  eArgumentError = rb_const_get(rb_cObject, rb_intern("ArgumentError"));
+
   ID_bind   = rb_intern("bind");
   ID_call   = rb_intern("call");
   ID_keys   = rb_intern("keys");
   ID_new    = rb_intern("new");
   ID_strip  = rb_intern("strip");
   ID_to_s   = rb_intern("to_s");
+
+  SYM_read_only = ID2SYM(rb_intern("read_only"));
+  rb_gc_register_mark_object(SYM_read_only);
 }

data/ext/extralite/extralite.h

@@ -94,6 +94,7 @@ typedef struct {
 
 VALUE safe_execute_multi(query_ctx *ctx);
 VALUE safe_query_ary(query_ctx *ctx);
+VALUE safe_query_changes(query_ctx *ctx);
 VALUE safe_query_columns(query_ctx *ctx);
 VALUE safe_query_hash(query_ctx *ctx);
 VALUE safe_query_single_column(query_ctx *ctx);
@@ -120,6 +121,6 @@ int stmt_iterate(query_ctx *ctx);
 VALUE cleanup_stmt(query_ctx *ctx);
 
 sqlite3 *Database_sqlite3_db(VALUE self);
-Database_t *Database_struct(VALUE self);
+Database_t *self_to_database(VALUE self);
 
 #endif /* EXTRALITE_H */

data/ext/extralite/iterator.c

@@ -34,7 +34,7 @@ static VALUE Iterator_allocate(VALUE klass) {
   return TypedData_Wrap_Struct(klass, &Iterator_type, iterator);
 }
 
-static inline Iterator_t *value_to_iterator(VALUE obj) {
+static inline Iterator_t *self_to_iterator(VALUE obj) {
   Iterator_t *iterator;
   TypedData_Get_Struct((obj), Iterator_t, &Iterator_type, (iterator));
   return iterator;
@@ -61,7 +61,7 @@ static inline enum iterator_mode symbol_to_mode(VALUE sym) {
  * @return [void]
  */
 VALUE Iterator_initialize(VALUE self, VALUE query, VALUE mode) {
-  Iterator_t *iterator = value_to_iterator(self);
+  Iterator_t *iterator = self_to_iterator(self);
 
   iterator->query = query;
   iterator->mode = symbol_to_mode(mode);
@@ -92,7 +92,7 @@ inline each_method mode_to_each_method(enum iterator_mode mode) {
  */
 VALUE Iterator_each(VALUE self) {
   if (rb_block_given_p()) {
-    Iterator_t *iterator = value_to_iterator(self);
+    Iterator_t *iterator = self_to_iterator(self);
     each_method method = mode_to_each_method(iterator->mode);
     method(iterator->query);
   }
@@ -130,7 +130,7 @@ inline next_method mode_to_next_method(enum iterator_mode mode) {
  *   @return [Array, Extralite::Iterator] next rows or self if block is given
  */
 VALUE Iterator_next(int argc, VALUE *argv, VALUE self) {
-  Iterator_t *iterator = value_to_iterator(self);
+  Iterator_t *iterator = self_to_iterator(self);
   next_method method = mode_to_next_method(iterator->mode);
   VALUE result = method(argc, argv, iterator->query);
 
@@ -156,11 +156,34 @@ inline to_a_method mode_to_to_a_method(enum iterator_mode mode) {
  * @return [Array] array of query result set rows
  */
 VALUE Iterator_to_a(VALUE self) {
-  Iterator_t *iterator = value_to_iterator(self);
+  Iterator_t *iterator = self_to_iterator(self);
   to_a_method method = mode_to_to_a_method(iterator->mode);
   return method(iterator->query);
 }
 
+inline VALUE mode_to_symbol(Iterator_t *iterator) {
+  switch (iterator->mode) {
+    case ITERATOR_ARY:
+      return SYM_ary;
+    case ITERATOR_SINGLE_COLUMN:
+      return SYM_single_column;
+    default:
+      return SYM_hash;
+  }
+}
+
+/* Returns a short string representation of the iterator instance, including the
+ * SQL string.
+ *
+ * @return [String] string representation
+ */
+VALUE Iterator_inspect(VALUE self) {
+  VALUE cname = rb_class_name(CLASS_OF(self));
+  VALUE sym = mode_to_symbol(self_to_iterator(self));
+  
+  return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, sym);
+}
+
 void Init_ExtraliteIterator(void) {
   VALUE mExtralite = rb_define_module("Extralite");
 
@@ -171,10 +194,15 @@ void Init_ExtraliteIterator(void) {
 
   rb_define_method(cIterator, "initialize", Iterator_initialize, 2);
   rb_define_method(cIterator, "each", Iterator_each, 0);
+  rb_define_method(cIterator, "inspect", Iterator_inspect, 0);
   rb_define_method(cIterator, "next", Iterator_next, -1);
   rb_define_method(cIterator, "to_a", Iterator_to_a, 0);
 
   SYM_hash          = ID2SYM(rb_intern("hash"));
   SYM_ary           = ID2SYM(rb_intern("ary"));
   SYM_single_column = ID2SYM(rb_intern("single_column"));
+
+  rb_gc_register_mark_object(SYM_hash);
+  rb_gc_register_mark_object(SYM_ary);
+  rb_gc_register_mark_object(SYM_single_column);
 }

data/ext/extralite/query.c

@@ -11,6 +11,9 @@
 
 VALUE cQuery;
 
+ID ID_inspect;
+ID ID_slice;
+
 static size_t Query_size(const void *ptr) {
   return sizeof(Query_t);
 }
@@ -42,7 +45,7 @@ static VALUE Query_allocate(VALUE klass) {
   return TypedData_Wrap_Struct(klass, &Query_type, query);
 }
 
-static inline Query_t *value_to_query(VALUE obj) {
+static inline Query_t *self_to_query(VALUE obj) {
   Query_t *query;
   TypedData_Get_Struct((obj), Query_t, &Query_type, (query));
   return query;
@@ -58,14 +61,14 @@ static inline Query_t *value_to_query(VALUE obj) {
  * @return [void]
  */
 VALUE Query_initialize(VALUE self, VALUE db, VALUE sql) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
 
   sql = rb_funcall(sql, ID_strip, 0);
   if (!RSTRING_LEN(sql))
     rb_raise(cError, "Cannot prepare an empty SQL query");
 
   query->db = db;
-  query->db_struct = Database_struct(db);
+  query->db_struct = self_to_database(db);
   query->sqlite3_db = Database_sqlite3_db(db);
   query->sql = sql;
   query->stmt = NULL;
@@ -113,7 +116,7 @@ static inline void query_reset_and_bind(Query_t *query, int argc, VALUE * argv)
  * @return [Extralite::Query] self
  */
 VALUE Query_reset(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
 
   query_reset(query);
@@ -145,7 +148,7 @@ VALUE Query_reset(VALUE self) {
  * @return [Extralite::Query] self
  */
 VALUE Query_bind(int argc, VALUE *argv, VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
 
   query_reset_and_bind(query, argc, argv);
@@ -157,7 +160,7 @@ VALUE Query_bind(int argc, VALUE *argv, VALUE self) {
  * @return [boolean] true if iteration has reached the end of the result set
  */
 VALUE Query_eof_p(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
 
   return query->eof ? Qtrue : Qfalse;
@@ -166,7 +169,7 @@ VALUE Query_eof_p(VALUE self) {
 #define MAX_ROWS(max_rows) (max_rows == SINGLE_ROW ? 1 : max_rows)
 
 static inline VALUE Query_perform_next(VALUE self, int max_rows, VALUE (*call)(query_ctx *)) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
   
   if (!query->stmt) query_reset(query);
@@ -265,7 +268,7 @@ VALUE Query_next_single_column(int argc, VALUE *argv, VALUE self) {
  *   @return [Array<Hash>] all rows
  */
 VALUE Query_to_a_hash(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_hash);
 }
@@ -275,7 +278,7 @@ VALUE Query_to_a_hash(VALUE self) {
  * @return [Array<Array>] all rows
  */
 VALUE Query_to_a_ary(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_ary);
 }
@@ -286,7 +289,7 @@ VALUE Query_to_a_ary(VALUE self) {
  * @return [Array<Object>] all rows
  */
 VALUE Query_to_a_single_column(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_single_column);
 }
@@ -300,7 +303,7 @@ VALUE Query_to_a_single_column(VALUE self) {
 VALUE Query_each_hash(VALUE self) {
   if (!rb_block_given_p()) return rb_funcall(cIterator, ID_new, 2, self, SYM_hash);
 
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_hash);
 }
@@ -314,7 +317,7 @@ VALUE Query_each_hash(VALUE self) {
 VALUE Query_each_ary(VALUE self) {
   if (!rb_block_given_p()) return rb_funcall(cIterator, ID_new, 2, self, SYM_ary);
 
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_ary);
 }
@@ -329,11 +332,40 @@ VALUE Query_each_ary(VALUE self) {
 VALUE Query_each_single_column(VALUE self) {
   if (!rb_block_given_p()) return rb_funcall(cIterator, ID_new, 2, self, SYM_single_column);
 
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_single_column);
 }
 
+/* call-seq:
+ *   query.execute(*parameters) -> changes
+ *
+ * Runs a query returning the total changes effected. This method should be used
+ * for data- or schema-manipulation queries.
+ *
+ * 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
+ * `?`:
+ *
+ *     query = db.prepare('update foo set x = ? where y = ?')
+ *     query.execute(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:
+ *
+ *     query = db.prepare('update foo set x = :bar')
+ *     query.execute(bar: 42)
+ *     query.execute('bar' => 42)
+ *     query.execute(':bar' => 42)
+ */
+VALUE Query_execute(int argc, VALUE *argv, VALUE self) {
+  Query_t *query = self_to_query(self);
+  query_reset_and_bind(query, argc, argv);
+  return Query_perform_next(self, ALL_ROWS, safe_query_changes);
+}
+
 /* Executes the query for each set of parameters in the given array. Parameters
  * can be specified as either an array (for unnamed parameters) or a hash (for
  * named parameters). Returns the number of changes effected. This method is
@@ -350,7 +382,7 @@ VALUE Query_each_single_column(VALUE self) {
  * @return [Integer] number of changes effected
  */
 VALUE Query_execute_multi(VALUE self, VALUE parameters) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
 
   if (!query->stmt)
@@ -368,7 +400,7 @@ VALUE Query_execute_multi(VALUE self, VALUE parameters) {
  *   @return [Extralite::Database] associated database
  */
 VALUE Query_database(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   return query->db;
 }
 
@@ -377,7 +409,7 @@ VALUE Query_database(VALUE self) {
  * @return [String] SQL string
  */
 VALUE Query_sql(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   return query->sql;
 }
 
@@ -386,7 +418,7 @@ VALUE Query_sql(VALUE self) {
  * @return [Array<Symbol>] column names
  */
 VALUE Query_columns(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   query_reset(query);
   return Query_perform_next(self, ALL_ROWS, safe_query_columns);
 }
@@ -396,7 +428,7 @@ VALUE Query_columns(VALUE self) {
  * @return [Extralite::Query] self
  */
 VALUE Query_close(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->stmt) {
     sqlite3_finalize(query->stmt);
     query->stmt = NULL;
@@ -410,7 +442,7 @@ VALUE Query_close(VALUE self) {
  * @return [boolean] true if query is closed
  */
 VALUE Query_closed_p(VALUE self) {
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   return query->closed ? Qtrue : Qfalse;
 }
 
@@ -431,7 +463,7 @@ VALUE Query_status(int argc, VALUE* argv, VALUE self) {
 
   rb_scan_args(argc, argv, "11", &op, &reset);
 
-  Query_t *query = value_to_query(self);
+  Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
 
   if (!query->stmt)
@@ -441,6 +473,24 @@ VALUE Query_status(int argc, VALUE* argv, VALUE self) {
   return INT2NUM(value);
 }
 
+/* Returns a short string representation of the query instance, including the
+ * SQL string.
+ *
+ * @return [String] string representation
+ */
+VALUE Query_inspect(VALUE self) {
+  VALUE cname = rb_class_name(CLASS_OF(self));
+  VALUE sql = self_to_query(self)->sql;
+  if (RSTRING_LEN(sql) > 48) {
+    sql = rb_funcall(sql, ID_slice, 2, INT2FIX(0), INT2FIX(45));
+    rb_str_cat2(sql, "...");
+  }
+  sql = rb_funcall(sql, ID_inspect, 0);
+    
+  RB_GC_GUARD(sql);
+  return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, sql);
+}
+
 void Init_ExtraliteQuery(void) {
   VALUE mExtralite = rb_define_module("Extralite");
 
@@ -460,8 +510,10 @@ void Init_ExtraliteQuery(void) {
   rb_define_method(cQuery, "each_single_column", Query_each_single_column, 0);
 
   rb_define_method(cQuery, "eof?", Query_eof_p, 0);
+  rb_define_method(cQuery, "execute", Query_execute, -1);
   rb_define_method(cQuery, "execute_multi", Query_execute_multi, 1);
   rb_define_method(cQuery, "initialize", Query_initialize, 2);
+  rb_define_method(cQuery, "inspect", Query_inspect, 0);
 
   rb_define_method(cQuery, "next", Query_next_hash, -1);
   rb_define_method(cQuery, "next_ary", Query_next_ary, -1);
@@ -476,4 +528,7 @@ void Init_ExtraliteQuery(void) {
   rb_define_method(cQuery, "to_a_ary", Query_to_a_ary, 0);
   rb_define_method(cQuery, "to_a_hash", Query_to_a_hash, 0);
   rb_define_method(cQuery, "to_a_single_column", Query_to_a_single_column, 0);
+
+  ID_inspect  = rb_intern("inspect");
+  ID_slice    = rb_intern("slice");
 }

data/lib/extralite/version.rb

@@ -1,4 +1,4 @@
 module Extralite
   # Extralite version
-  VERSION = '2.0'
+  VERSION = '2.1'
 end

data/lib/extralite.rb

@@ -27,8 +27,6 @@ module Extralite
 
   # An SQLite database
   class Database
-    alias_method :execute, :query
-
     # @!visibility private
     TABLES_SQL = <<~SQL
       SELECT name FROM sqlite_master

data/test/test_database.rb

@@ -206,6 +206,17 @@ end
     assert_equal [{recursive_triggers: 1}], @db.pragma(:recursive_triggers)
   end
 
+  def test_execute
+    changes = @db.execute('update t set x = 42')
+    assert_equal 2, changes
+  end
+
+  def test_execute_with_params
+    changes = @db.execute('update t set x = ? where z = ?', 42, 6)
+    assert_equal 1, changes
+    assert_equal [[1, 2, 3], [42, 5, 6]], @db.query_ary('select * from t order by x')
+  end
+
   def test_execute_multi
     @db.query('create table foo (a, b, c)')
     assert_equal [], @db.query('select * from foo')
@@ -361,6 +372,21 @@ end
     query.next
     @db.close
   end
+
+  def test_read_only_database
+    db = Extralite::Database.new(':memory:')
+    db.query('create table foo (bar)')
+    assert_equal false, db.read_only?
+
+    db = Extralite::Database.new(':memory:', read_only: true)
+    assert_raises(Extralite::Error) { db.query('create table foo (bar)') }
+    assert_equal true, db.read_only?
+  end
+
+  def test_database_inspect
+    db = Extralite::Database.new(':memory:')
+    assert_match /^\#\<Extralite::Database:0x[0-9a-f]+ :memory:\>$/, db.inspect
+  end
 end
 
 class ScenarioTest < MiniTest::Test

data/test/test_iterator.rb

@@ -96,4 +96,9 @@ class IteratorTest < MiniTest::Test
     mapped = query.each_single_column.map { |v| v * 10 }
     assert_equal [30, 60, 90], mapped
   end
+
+  def test_iterator_inspect
+    i = @query.each_ary
+    assert_match /^\#\<Extralite::Iterator:0x[0-9a-f]+ ary\>$/, i.inspect
+  end
 end

data/test/test_query.rb

@@ -430,6 +430,18 @@ class QueryTest < MiniTest::Test
     assert_raises(Extralite::Error) { p.next }
   end
 
+  def test_query_execute
+    q = @db.prepare('update t set x = 42')
+    assert_equal 3, q.execute
+    assert_equal [[42, 2, 3], [42, 5, 6], [42, 8, 9]], @db.query_ary('select * from t order by z')
+  end
+
+  def test_query_execute_with_params
+    q = @db.prepare('update t set x = ? where z = ?')
+    assert_equal 1, q.execute(42, 9)
+    assert_equal [[1, 2, 3], [4, 5, 6], [42, 8, 9]], @db.query_ary('select * from t order by z')
+  end
+
   def test_query_execute_multi
     @db.query('create table foo (a, b, c)')
     assert_equal [], @db.query('select * from foo')
@@ -499,4 +511,9 @@ class QueryTest < MiniTest::Test
     assert_equal [1, 4, 7], query.to_a_single_column
     assert_equal true, query.eof?
   end
+
+  def test_query_inspect
+    q = @db.prepare('select x from t')
+    assert_match /^\#\<Extralite::Query:0x[0-9a-f]+ #{q.sql.inspect}\>$/, q.inspect
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extralite
 version: !ruby/object:Gem::Version
-  version: '2.0'
+  version: '2.1'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-08 00:00:00.000000000 Z
+date: 2023-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler