sqlite3 1.3.13-x64-mingw32 → 1.5.0-x64-mingw32

data/README.md

@@ -0,0 +1,233 @@
+# Ruby Interface for SQLite3
+
+* Source code: https://github.com/sparklemotion/sqlite3-ruby
+* Mailing list: http://groups.google.com/group/sqlite3-ruby
+* Download: http://rubygems.org/gems/sqlite3
+* Documentation: http://www.rubydoc.info/gems/sqlite3
+
+[![Unit tests](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml)
+[![Native packages](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml)
+
+
+## Description
+
+This library allows Ruby programs to use the SQLite3 database engine (http://www.sqlite.org).
+
+Note that this module is only compatible with SQLite 3.6.16 or newer.
+
+
+## Synopsis
+
+``` ruby
+require "sqlite3"
+
+# Open a database
+db = SQLite3::Database.new "test.db"
+
+# Create a table
+rows = db.execute <<-SQL
+  create table numbers (
+    name varchar(30),
+    val int
+  );
+SQL
+
+# Execute a few inserts
+{
+  "one" => 1,
+  "two" => 2,
+}.each do |pair|
+  db.execute "insert into numbers values ( ?, ? )", pair
+end
+
+# Find a few rows
+db.execute( "select * from numbers" ) do |row|
+  p row
+end
+# => ["one", 1]
+#    ["two", 2]
+
+# Create another table with multiple columns
+db.execute <<-SQL
+  create table students (
+    name varchar(50),
+    email varchar(50),
+    grade varchar(5),
+    blog varchar(50)
+  );
+SQL
+
+# Execute inserts with parameter markers
+db.execute("INSERT INTO students (name, email, grade, blog)
+            VALUES (?, ?, ?, ?)", ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"])
+
+db.execute( "select * from students" ) do |row|
+  p row
+end
+# => ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"]
+```
+
+## Installation
+
+### Native Gems (recommended)
+
+As of v1.5.0 of this library, native (precompiled) gems are available for Ruby 2.6, 2.7, 3.0, and 3.1 on all these platforms:
+
+- `aarch64-linux`
+- `arm-linux`
+- `arm64-darwin`
+- `x64-mingw32` / `x64-mingw-ucrt`
+- `x86-linux`
+- `x86_64-darwin`
+- `x86_64-linux`
+
+If you are using one of these Ruby versions on one of these platforms, the native gem is the recommended way to install sqlite3-ruby.
+
+For example, on a linux system running Ruby 3.1:
+
+``` text
+$ ruby -v
+ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux]
+
+$ time gem install sqlite3
+Fetching sqlite3-1.5.0-x86_64-linux.gem
+Successfully installed sqlite3-1.5.0-x86_64-linux
+1 gem installed
+
+real    0m4.274s
+user    0m0.734s
+sys     0m0.165s
+```
+
+#### Avoiding the precompiled native gem
+
+The maintainers strongly urge you to use a native gem if at all possible. It will be a better experience for you and allow us to focus our efforts on improving functionality rather than diagnosing installation issues.
+
+If you're on a platform that supports a native gem but you want to avoid using it in your project, do one of the following:
+
+- If you're not using Bundler, then run `gem install sqlite3 --platform=ruby`
+- If you are using Bundler
+  - version 2.1 or later, then you'll need to run `bundle config set force_ruby_platform true`,
+  - version 2.0 or earlier, then you'll need to run `bundle config force_ruby_platform true`
+
+
+### Compiling the source gem
+
+If you are on a platform or version of Ruby that is not covered by the Native Gems, then the vanilla "ruby platform" (non-native) gem will be installed by the `gem install` or `bundle` commands.
+
+
+#### Packaged libsqlite3
+
+By default, as of v1.5.0 of this library, the latest available version of libsqlite3 is packaged with the gem and will be compiled and used automatically. This takes a bit longer than the native gem, but will provide a modern, well-supported version of libsqlite3.
+
+For example, on a linux system running Ruby 2.5:
+
+``` text
+$ ruby -v
+ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
+
+$ time gem install sqlite3
+Building native extensions. This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m20.620s
+user    0m23.361s
+sys     0m5.839s
+```
+
+
+#### System libsqlite3
+
+If you would prefer to build the sqlite3-ruby gem against your system libsqlite3, which requires that you install libsqlite3 and its development files yourself, you may do so by using the `--enable-system-libraries` flag at gem install time.
+
+PLEASE NOTE:
+
+- only versions of libsqlite3 `>= 3.5.0` are supported,
+- and some library features may depend on how your libsqlite3 was compiled.
+
+For example, on a linux system running Ruby 2.5:
+
+``` text
+$ time gem install sqlite3 -- --enable-system-libraries
+Building native extensions with: '--enable-system-libraries'
+This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m4.234s
+user    0m3.809s
+sys     0m0.912s
+```
+
+If you're using bundler, you can opt into system libraries like this:
+
+``` sh
+bundle config build.sqlite3 --enable-system-libraries
+```
+
+If you have sqlite3 installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
+
+``` sh
+gem install sqlite3 -- \
+  --enable-system-libraries \
+  --with-sqlite3-include=/opt/local/include \
+  --with-sqlite3-lib=/opt/local/lib
+```
+
+
+#### System libsqlcipher
+
+If you'd like to link against a system-installed libsqlcipher, you may do so by using the `--with-sqlcipher` flag:
+
+``` text
+$ time gem install sqlite3 -- --with-sqlcipher
+Building native extensions with: '--with-sqlcipher'
+This could take a while...
+Successfully installed sqlite3-1.5.0
+1 gem installed
+
+real    0m4.772s
+user    0m3.906s
+sys     0m0.896s
+```
+
+If you have sqlcipher installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
+
+
+## Support
+
+### Something has gone wrong! Where do I get help?
+
+You can ask for help or support from the
+[sqlite3-ruby mailing list](http://groups.google.com/group/sqlite3-ruby) which
+can be found here:
+
+> http://groups.google.com/group/sqlite3-ruby
+
+
+### I've found a bug! How do I report it?
+
+After contacting the mailing list, you've found that you've uncovered a bug. You can file the bug at the [github issues page](https://github.com/sparklemotion/sqlite3-ruby/issues) which can be found here:
+
+> https://github.com/sparklemotion/sqlite3-ruby/issues
+
+
+## Usage
+
+For help figuring out the SQLite3/Ruby interface, check out the SYNOPSIS as well as the RDoc. It includes examples of usage. If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby).
+
+
+## Contributing
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+
+## License
+
+This library is licensed under `BSD-3-Clause`, see [`LICENSE`](./LICENSE).
+
+
+### Dependencies
+
+The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain, see [`LICENSE-DEPENDENCIES`](./LICENSE-DEPENDENCIES) for details.

data/ext/sqlite3/aggregator.c

@@ -0,0 +1,274 @@
+#include <aggregator.h>
+#include <database.h>
+
+/* wraps a factory "handler" class. The "-aggregators" instance variable of
+ * the SQLite3::Database holds an array of all AggrogatorWrappers.
+ *
+ * An AggregatorWrapper holds the following instance variables:
+ * -handler_klass: the handler that creates the instances.
+ * -instances:     array of all the cAggregatorInstance objects currently
+ *                 in-flight for this aggregator. */
+static VALUE cAggregatorWrapper;
+
+/* wraps a instance of the "handler" class. Loses its reference at the end of
+ * the xFinal callback.
+ *
+ * An AggregatorInstance holds the following instance variables:
+ * -handler_instance: the instance to call `step` and `finalize` on.
+ * -exc_status:       status returned by rb_protect.
+ *                    != 0 if an exception occurred. If an exception occurred
+ *                    `step` and `finalize` won't be called any more. */
+static VALUE cAggregatorInstance;
+
+typedef struct rb_sqlite3_protected_funcall_args {
+    VALUE self;
+    ID method;
+    int argc;
+    VALUE *params;
+} protected_funcall_args_t;
+
+/* why isn't there something like this in the ruby API? */
+static VALUE
+rb_sqlite3_protected_funcall_body(VALUE protected_funcall_args_ptr)
+{
+  protected_funcall_args_t *args =
+    (protected_funcall_args_t*)protected_funcall_args_ptr;
+
+  return rb_funcall2(args->self, args->method, args->argc, args->params);
+}
+
+static VALUE
+rb_sqlite3_protected_funcall(VALUE self, ID method, int argc, VALUE *params,
+                             int* exc_status)
+{
+  protected_funcall_args_t args = {
+    .self = self, .method = method, .argc = argc, .params = params
+  };
+  return rb_protect(rb_sqlite3_protected_funcall_body, (VALUE)(&args), exc_status);
+}
+
+/* called in rb_sqlite3_aggregator_step and rb_sqlite3_aggregator_final. It
+ * checks if the execution context already has an associated instance. If it
+ * has one, it returns it. If there is no instance yet, it creates one and
+ * associates it with the context. */
+static VALUE
+rb_sqlite3_aggregate_instance(sqlite3_context *ctx)
+{
+  VALUE aw = (VALUE) sqlite3_user_data(ctx);
+  VALUE handler_klass = rb_iv_get(aw, "-handler_klass");
+  VALUE inst;
+  VALUE *inst_ptr = sqlite3_aggregate_context(ctx, (int)sizeof(VALUE));
+
+  if (!inst_ptr) {
+    rb_fatal("SQLite is out-of-merory");
+  }
+
+  inst = *inst_ptr;
+
+  if (inst == Qfalse) { /* Qfalse == 0 */
+    VALUE instances = rb_iv_get(aw, "-instances");
+    int exc_status;
+
+    inst = rb_class_new_instance(0, NULL, cAggregatorInstance);
+    rb_iv_set(inst, "-handler_instance", rb_sqlite3_protected_funcall(
+      handler_klass, rb_intern("new"), 0, NULL, &exc_status));
+    rb_iv_set(inst, "-exc_status", INT2NUM(exc_status));
+
+    rb_ary_push(instances, inst);
+
+    *inst_ptr = inst;
+  }
+
+  if (inst == Qnil) {
+    rb_fatal("SQLite called us back on an already destroyed aggregate instance");
+  }
+
+  return inst;
+}
+
+/* called by rb_sqlite3_aggregator_final. Unlinks and frees the
+ * aggregator_instance_t, so the handler_instance won't be marked any more
+ * and Ruby's GC may free it. */
+static void
+rb_sqlite3_aggregate_instance_destroy(sqlite3_context *ctx)
+{
+  VALUE aw = (VALUE) sqlite3_user_data(ctx);
+  VALUE instances = rb_iv_get(aw, "-instances");
+  VALUE *inst_ptr = sqlite3_aggregate_context(ctx, 0);
+  VALUE inst;
+
+  if (!inst_ptr || (inst = *inst_ptr)) {
+    return;
+  }
+
+  if (inst == Qnil) {
+    rb_fatal("attempt to destroy aggregate instance twice");
+  }
+
+  rb_iv_set(inst, "-handler_instance", Qnil); // may catch use-after-free
+  if (rb_ary_delete(instances, inst) == Qnil) {
+    rb_fatal("must be in instances at that point");
+  }
+
+  *inst_ptr = Qnil;
+}
+
+static void
+rb_sqlite3_aggregator_step(sqlite3_context * ctx, int argc, sqlite3_value **argv)
+{
+  VALUE inst = rb_sqlite3_aggregate_instance(ctx);
+  VALUE handler_instance = rb_iv_get(inst, "-handler_instance");
+  VALUE * params = NULL;
+  VALUE one_param;
+  int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
+  int i;
+
+  if (exc_status) {
+    return;
+  }
+
+  if (argc == 1) {
+    one_param = sqlite3val2rb(argv[0]);
+    params = &one_param;
+  }
+  if (argc > 1) {
+    params = xcalloc((size_t)argc, sizeof(VALUE));
+    for(i = 0; i < argc; i++) {
+      params[i] = sqlite3val2rb(argv[i]);
+    }
+  }
+  rb_sqlite3_protected_funcall(
+    handler_instance, rb_intern("step"), argc, params, &exc_status);
+  if (argc > 1) {
+    xfree(params);
+  }
+
+  rb_iv_set(inst, "-exc_status", INT2NUM(exc_status));
+}
+
+/* we assume that this function is only called once per execution context */
+static void
+rb_sqlite3_aggregator_final(sqlite3_context * ctx)
+{
+  VALUE inst = rb_sqlite3_aggregate_instance(ctx);
+  VALUE handler_instance = rb_iv_get(inst, "-handler_instance");
+  int exc_status = NUM2INT(rb_iv_get(inst, "-exc_status"));
+
+  if (!exc_status) {
+    VALUE result = rb_sqlite3_protected_funcall(
+      handler_instance, rb_intern("finalize"), 0, NULL, &exc_status);
+    if (!exc_status) {
+      set_sqlite3_func_result(ctx, result);
+    }
+  }
+
+  if (exc_status) {
+    /* the user should never see this, as Statement.step() will pick up the
+     * outstanding exception and raise it instead of generating a new one
+     * for SQLITE_ERROR with message "Ruby Exception occurred" */
+    sqlite3_result_error(ctx, "Ruby Exception occurred", -1);
+  }
+
+  rb_sqlite3_aggregate_instance_destroy(ctx);
+}
+
+/* call-seq: define_aggregator2(aggregator)
+ *
+ * Define an aggregrate function according to a factory object (the "handler")
+ * that knows how to obtain to all the information. The handler must provide
+ * the following class methods:
+ *
+ * +arity+:: corresponds to the +arity+ parameter of #create_aggregate. This
+ *           message is optional, and if the handler does not respond to it,
+ *           the function will have an arity of -1.
+ * +name+:: this is the name of the function. The handler _must_ implement
+ *          this message.
+ * +new+:: this must be implemented by the handler. It should return a new
+ *         instance of the object that will handle a specific invocation of
+ *         the function.
+ *
+ * The handler instance (the object returned by the +new+ message, described
+ * above), must respond to the following messages:
+ *
+ * +step+:: this is the method that will be called for each step of the
+ *          aggregate function's evaluation. It should take parameters according
+ *          to the *arity* definition.
+ * +finalize+:: this is the method that will be called to finalize the
+ *              aggregate function's evaluation. It should not take arguments.
+ *
+ * Note the difference between this function and #create_aggregate_handler
+ * is that no FunctionProxy ("ctx") object is involved. This manifests in two
+ * ways: The return value of the aggregate function is the return value of
+ * +finalize+ and neither +step+ nor +finalize+ take an additional "ctx"
+ * parameter.
+ */
+VALUE
+rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_name)
+{
+  /* define_aggregator is added as a method to SQLite3::Database in database.c */
+  sqlite3RubyPtr ctx;
+  int arity, status;
+  VALUE aw;
+  VALUE aggregators;
+
+  Data_Get_Struct(self, sqlite3Ruby, ctx);
+  if (!ctx->db) {
+    rb_raise(rb_path2class("SQLite3::Exception"), "cannot use a closed database");
+  }
+
+  if (rb_respond_to(aggregator, rb_intern("arity"))) {
+    VALUE ruby_arity = rb_funcall(aggregator, rb_intern("arity"), 0);
+    arity = NUM2INT(ruby_arity);
+  } else {
+    arity = -1;
+  }
+
+  if (arity < -1 || arity > 127) {
+#ifdef PRIsVALUE
+    rb_raise(rb_eArgError, "%"PRIsVALUE" arity=%d out of range -1..127",
+            self, arity);
+#else
+    rb_raise(rb_eArgError, "Aggregator arity=%d out of range -1..127", arity);
+#endif
+  }
+
+  if (!rb_ivar_defined(self, rb_intern("-aggregators"))) {
+    rb_iv_set(self, "-aggregators", rb_ary_new());
+  }
+  aggregators = rb_iv_get(self, "-aggregators");
+
+  aw = rb_class_new_instance(0, NULL, cAggregatorWrapper);
+  rb_iv_set(aw, "-handler_klass", aggregator);
+  rb_iv_set(aw, "-instances", rb_ary_new());
+
+  status = sqlite3_create_function(
+    ctx->db,
+    StringValueCStr(ruby_name),
+    arity,
+    SQLITE_UTF8,
+    (void*)aw,
+    NULL,
+    rb_sqlite3_aggregator_step,
+    rb_sqlite3_aggregator_final
+  );
+
+  if (status != SQLITE_OK) {
+    rb_sqlite3_raise(ctx->db, status);
+    return self; // just in case rb_sqlite3_raise returns.
+  }
+
+  rb_ary_push(aggregators, aw);
+
+  return self;
+}
+
+void
+rb_sqlite3_aggregator_init(void)
+{
+  /* rb_class_new generatos class with undefined allocator in ruby 1.9 */
+  cAggregatorWrapper = rb_funcall(rb_cClass, rb_intern("new"), 0);
+  rb_gc_register_mark_object(cAggregatorWrapper);
+
+  cAggregatorInstance = rb_funcall(rb_cClass, rb_intern("new"), 0);
+  rb_gc_register_mark_object(cAggregatorInstance);
+}

data/ext/sqlite3/aggregator.h

@@ -0,0 +1,12 @@
+#ifndef SQLITE3_AGGREGATOR_RUBY
+#define SQLITE3_AGGREGATOR_RUBY
+
+#include <sqlite3_ruby.h>
+
+VALUE
+rb_sqlite3_define_aggregator2(VALUE self, VALUE aggregator, VALUE ruby_name);
+
+void
+rb_sqlite3_aggregator_init(void);
+
+#endif