activerecord-turso 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04f8ecc726fa450fadcf8b819a04663b3035bed1c1b5f592d362ec07664d2f14
-  data.tar.gz: 4ce85117e6f562ead6d2defeaaa5c70fccc2c62492d9916c798e56bcf32acfca
+  metadata.gz: cfdd23462f8313c9a19d64bab33314e3d5a4b7532249695f01811ebcf3fcccbd
+  data.tar.gz: 74e33f479629655b50621e300dc7a1d38b2d94d95edd2da9b57b3d18c5799dbe
 SHA512:
-  metadata.gz: 6d18e249a927642d705959341439129523cb3f2763ab699a8c2dfbc1f38d8f52b3b831a96f140a95518f3e932a9da348184af605525d354a54893419f332c0aa
-  data.tar.gz: 8b1cec4617634414e11928453aeed21e2c382fe4a36357ca435b601f337f8b9ca3fb732f035db02ebd8a0fe8f7dfc35db961c384faffd2cf8937ea612ec6363e
+  metadata.gz: 9dee234b1fa1abd37883de7c10b876cad339858a41643000eee969348ae0ad1da8458a8b546145aa1c7e38648e5e7da3734d35fa484b08c0d87260dc170f3fe5
+  data.tar.gz: 314bda7c65ccc415af50204690e098859517419f8f7ba035852a6230c0654c40f94a82ba3bd22ba54a829920cfb7f9159fbf1acc0de8e04816641669b6789938

data/README.md

@@ -4,12 +4,12 @@ ActiveRecord adapter for [Turso](https://turso.tech) (SQLite compatible db).
 
 ## Status
 
-This adapter is under **active** development. It can run basic ActiveRecord operations against Turso today, but several production features are still being hardened. See [Limitations and Risks](#limitations-and-risks) before using it in production.
+Production ready for **embedded/local** ActiveRecord 8.1 applications using the Turso SQLite-compatible database engine. This adapter does **not** support remote `libsql://` URLs or Turso cloud authentication. The underlying `turso` gem releases the GVL during blocking operations, supports fiber-aware connection ownership, and uses native batch execution.
 
 ## Requirements
 
 - Ruby >= 3.2
-- ActiveRecord >= 8.0, < 8.2
+- ActiveRecord ~> 8.1.0
 - The `turso` Ruby gem
 
 ## Runtime dependencies
@@ -51,7 +51,9 @@ end
 Post.create!(title: "Hello", body: "World", published: true)
 ```
 
-## Recommended production configuration
+## Configuration
+
+### Recommended production configuration
 
 ```yaml
 production:
@@ -65,6 +67,23 @@ production:
   experimental_features: "index_method"
 ```
 
+### Connection options
+
+| Option | Description | Default |
+|---|---|---|
+| `database` | Path to the SQLite database file | Required |
+| `journal_mode` | Journal mode (`wal`, `mvcc`, `delete`, etc.) | WAL |
+| `pool` | Connection pool size | 5 |
+| `timeout` | Busy timeout in milliseconds | 5000 |
+| `busy_timeout` | Busy timeout in milliseconds (overrides `timeout`) | 5000 |
+| `query_timeout` | Query timeout in milliseconds | 30000 |
+| `experimental_features` | Comma-separated experimental features (`index_method`, `generated_columns`) | None |
+| `statement_limit` | Maximum number of cached prepared statements | 1000 |
+
+### `query_timeout` and `interrupt`
+
+The adapter exposes `query_timeout=` to set a maximum execution time for queries. When a query exceeds this timeout, the Turso engine interrupts the operation and raises `ActiveRecord::QueryCanceled`. Use `interrupt` to cancel a running query from another thread.
+
 ### MVCC / BEGIN CONCURRENT (experimental)
 
 ⚠️ **Experimental.** Do not use in production unless you understand the caveats below. Normal ActiveRecord model persistence (`create!`, `save!`, `update!`, `touch`) is **not supported** inside `transaction(concurrent: true)`.
@@ -95,6 +114,7 @@ development:
 - `transaction(concurrent: true)` requires the same database connection to be held for the entire retry loop. Rails' connection pool may reap the connection between retries, which can silently break MVCC semantics. Use this only when you understand the pooling behavior of your app.
 - `lock!`, `with_lock`, and `lock_version` are not meaningful under MVCC. Do not use them inside concurrent transactions.
 - If the retry limit is exhausted, the conflict is raised as `ActiveRecord::StatementInvalid`. You must handle it in application code.
+- Normal ActiveRecord model persistence (`create!`, `save!`, `update!`, `touch`) is **not supported** inside a concurrent transaction because ActiveRecord opens its own internal transaction for each model change. Use raw SQL (`execute`, `exec_query`) or bulk operations (`insert_all`, `update_all`, `update_columns`) instead.
 
 ### Full-text search (Tantivy)
 
@@ -168,9 +188,9 @@ The following limitations apply to the current implementation. Read this section
 
 The adapter builds column type maps from `column_decltype` metadata. This works for most column definitions but may not capture type information for computed expressions or subquery columns.
 
-### 2. Batch SQL execution uses a simple string splitter
+### 2. Batch SQL execution uses the Turso native batch API
 
-The adapter's batch execution path splits multi-statement SQL on semicolons. This means SQL containing semicolons inside string literals, triggers, or stored expressions may be split incorrectly. Avoid relying on multi-statement strings other than simple schema dumps.
+The adapter's batch execution path uses the Turso native batch API (`execute_batch`), which correctly handles semicolons inside string literals, triggers, and stored expressions.
 
 ### 3. MVCC requires opt-in and has ActiveRecord compatibility caveats
 
@@ -187,9 +207,9 @@ Only use `transaction(concurrent: true)` after testing it under your app's concu
 
 The adapter uses a bounded statement pool with a default limit inherited from Rails (typically `1000`). Statements are evicted with an LRU policy and finalized against the underlying Turso connection. Set `statement_limit` in `database.yml` to tune the pool size.
 
-### 5. ActiveRecord 8.0 support is CI-tested, not locally tested
+### 5. Only ActiveRecord 8.1 is supported
 
-Only ActiveRecord 8.1 is installed in the primary development environment. ActiveRecord 8.0 compatibility is validated through CI. If you run into 8.0-specific issues, please report them.
+The adapter is pinned to ActiveRecord `~> 8.1.0`.
 
 ### 6. INSERT RETURNING is disabled (not supported by Turso)
 
@@ -200,9 +220,9 @@ The underlying Turso SQLite build does not support `INSERT ... RETURNING` syntax
 - Transaction isolation levels other than the default are reported as unsupported (`supports_transaction_isolation?` returns `false`) because Turso remote connections do not provide shared-cache read-uncommitted semantics.
 - `insert_on_conflict` is enabled only when the reported SQLite version is `>= 3.24.0`.
 
-### 8. `execute_batch` in the underlying bindings is a Ruby-side fallback
+### 8. `execute_batch` uses the Turso native batch API
 
-The `turso` gem provides `DB#execute_batch` as a convenience that splits and executes statements one by one. It does not use a native batch API, so it carries the same semicolon-splitting risk as item 2 above.
+The `turso` gem's `execute_batch` uses the Turso native batch API (`prepare_first`/`execute` loop), correctly handling edge cases like semicolons in string literals and triggers.
 
 ## Development
 

data/lib/active_record/connection_adapters/turso_adapter/connection_management.rb

@@ -65,7 +65,8 @@ module ActiveRecord
           timeout = @config[:busy_timeout] || @config[:timeout] || 5000
           @raw_connection.busy_timeout = timeout
 
-
+          query_timeout = @config[:query_timeout] || 30_000
+          @raw_connection.query_timeout = query_timeout
         end
       end
     end

data/lib/active_record/connection_adapters/turso_adapter/error_translation.rb

@@ -5,7 +5,7 @@ module ActiveRecord
     class TursoAdapter < SQLite3Adapter
       module ErrorTranslation
         def translate_exception(exception, message:, sql:, binds:)
-          cause = exception.cause
+          cause = exception.cause || exception
           case cause
           when ::Turso::ConstraintException
             translate_constraint_error(message, sql, binds)
@@ -14,7 +14,7 @@ module ActiveRecord
           when ::Turso::BusySnapshotException
             ActiveRecord::SerializationFailure.new(message, sql: sql, binds: binds)
           when ::Turso::BusyException
-            ActiveRecord::Deadlocked.new(message, sql: sql, binds: binds)
+            ActiveRecordTurso::BusyError.new(message, sql: sql, binds: binds)
           when ::Turso::ReadonlyException
             ActiveRecord::ReadOnlyRecord.new(message, sql: sql, binds: binds)
           when ::Turso::IoException, ::Turso::CorruptException
@@ -38,6 +38,8 @@ module ActiveRecord
             ActiveRecord::InvalidForeignKey.new(message, sql: sql, binds: binds)
           when /unique constraint|primary key/i
             ActiveRecord::RecordNotUnique.new(message, sql: sql, binds: binds)
+          when /NOT NULL|cannot be NULL/i
+            ActiveRecord::NotNullViolation.new(message, sql: sql, binds: binds)
           else
             ActiveRecord::StatementInvalid.new(message, sql: sql, binds: binds)
           end

data/lib/active_record/tasks/turso_database_tasks.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "active_record/tasks/database_tasks"
+
+module ActiveRecord
+  module Tasks
+    class TursoDatabaseTasks < SQLiteDatabaseTasks
+      def initialize(db_config, root = nil)
+        @configuration = db_config
+      end
+
+      def create
+        path = configuration.database
+        return if path == ":memory:"
+
+        FileUtils.mkdir_p(File.dirname(path))
+        establish_connection(configuration)
+        connection.execute("SELECT 1")
+      end
+
+      def drop
+        path = configuration.database
+        return if path == ":memory:"
+
+        disconnect!
+        FileUtils.rm_f(path)
+        FileUtils.rm_f("#{path}-wal")
+        FileUtils.rm_f("#{path}-shm")
+      end
+
+      def purge
+        drop
+        create
+      end
+
+      def charset
+        "UTF-8"
+      end
+
+      def charset_collation
+        nil
+      end
+
+      def structure_dump(filename, extra_flags)
+        establish_connection(configuration)
+        io = File.open(filename, "w")
+        io.puts("PRAGMA foreign_keys = OFF;")
+
+        tables = connection.query_values(<<~SQL, "SCHEMA")
+          SELECT name FROM sqlite_master
+          WHERE type = 'table'
+            AND name NOT LIKE 'sqlite_%'
+            AND name NOT LIKE '__turso_internal_%'
+          ORDER BY name
+        SQL
+
+        tables.each do |table|
+          sql = connection.query_value(<<~SQL, "SCHEMA")
+            SELECT sql FROM sqlite_master WHERE name = #{connection.quote(table)}
+          SQL
+          io.puts("#{sql};") if sql
+        end
+
+        indexes = connection.query_values(<<~SQL, "SCHEMA")
+          SELECT name FROM sqlite_master
+          WHERE type = 'index'
+            AND name NOT LIKE 'sqlite_%'
+            AND sql IS NOT NULL
+          ORDER BY name
+        SQL
+
+        indexes.each do |index|
+          sql = connection.query_value(<<~SQL, "SCHEMA")
+            SELECT sql FROM sqlite_master WHERE name = #{connection.quote(index)}
+          SQL
+          io.puts("#{sql};") if sql
+        end
+
+        views = connection.query_values(<<~SQL, "SCHEMA")
+          SELECT name FROM sqlite_master
+          WHERE type = 'view'
+            AND name NOT LIKE 'sqlite_%'
+          ORDER BY name
+        SQL
+
+        views.each do |view|
+          sql = connection.query_value(<<~SQL, "SCHEMA")
+            SELECT sql FROM sqlite_master WHERE name = #{connection.quote(view)}
+          SQL
+          io.puts("#{sql};") if sql
+        end
+
+        io.puts("PRAGMA foreign_keys = ON;")
+        io.close
+      end
+
+      def structure_load(filename, extra_flags)
+        establish_connection(configuration)
+        sql = File.read(filename)
+        ActiveRecord::Base.connection.raw_connection.execute_batch(sql)
+      end
+
+      private
+
+      def configuration
+        @configuration
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      def establish_connection(config)
+        @configuration = config
+        ActiveRecord::Base.establish_connection(config)
+        ActiveRecord::Base.connection.connect!
+      end
+
+      def disconnect!
+        ActiveRecord::Base.connection_pool.disconnect!
+      end
+    end
+  end
+end

data/lib/activerecord-turso/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ActiveRecordTurso
+  class Error < ActiveRecord::StatementInvalid; end
+  class BusyError < Error; end
+end

data/lib/activerecord-turso/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordTurso
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/activerecord-turso.rb

@@ -3,6 +3,7 @@
 require "active_record"
 require "turso"
 
+require_relative "activerecord-turso/error"
 require_relative "turso/ar/connection"
 require_relative "active_record/connection_adapters/turso_adapter"
 
@@ -11,3 +12,8 @@ ActiveRecord::ConnectionAdapters.register(
   "ActiveRecord::ConnectionAdapters::TursoAdapter",
   "active_record/connection_adapters/turso_adapter"
 )
+
+require "active_record/tasks/database_tasks"
+require_relative "active_record/tasks/turso_database_tasks"
+
+ActiveRecord::Tasks::DatabaseTasks.register_task(/turso/, "ActiveRecord::Tasks::TursoDatabaseTasks")

data/lib/turso/ar/connection.rb

@@ -7,7 +7,9 @@ module Turso
     class Connection
       extend Forwardable
 
-      def_delegators :@db, :close, :closed?, :changes, :total_changes
+      def_delegators :@db, :close, :closed?, :changes, :total_changes,
+                     :last_insert_rowid, :prepare, :interrupt, :busy_timeout=,
+                     :query_timeout, :query_timeout=
 
       DEFAULT_BUSY_TIMEOUT_MS = 5000
       DEFAULT_QUERY_TIMEOUT_MS = 30_000
@@ -18,12 +20,14 @@ module Turso
           busy_timeout: config[:busy_timeout] || config[:timeout] || DEFAULT_BUSY_TIMEOUT_MS,
           query_timeout: config[:query_timeout] || DEFAULT_QUERY_TIMEOUT_MS
         }
-        db_opts[:experimental_features] = config[:experimental_features] if config[:experimental_features]
-        @db = ::Turso::Database.new(config[:database].to_s, **db_opts)
-      end
-
-      def last_insert_rowid
-        query("SELECT last_insert_rowid()").first&.to_a&.first.to_i
+        if config[:experimental_features]
+          features = Array(config[:experimental_features]).map(&:to_s).reject(&:empty?)
+          db_opts[:experimental_features] = features.join(",") unless features.empty?
+        end
+        database = ::Turso::Database.new(config[:database].to_s, **db_opts)
+        @db = database.connection
+        @db.busy_timeout = db_opts[:busy_timeout]
+        @db.query_timeout = db_opts[:query_timeout]
       end
 
       def raw_connection
@@ -48,107 +52,11 @@ module Turso
       end
 
       def execute_batch(sql)
-        split_batch(sql).each do |stmt|
-          @db.execute(stmt)
-        end
-      end
-
-      def prepare(sql)
-        @db.prepare(sql)
-      end
-
-      def busy_timeout=(ms)
-        @db.busy_timeout = ms.to_i
-      end
-
-      def interrupt
-        @db.interrupt
+        @db.execute_batch(sql)
       end
 
       private
 
-      def split_batch(sql)
-        statements = []
-        current = +""
-        in_string = false
-        in_line_comment = false
-        in_block_comment = false
-        i = 0
-        while i < sql.length
-          char = sql[i]
-          next_char = sql[i + 1]
-
-          if in_line_comment
-            if char == "\n"
-              in_line_comment = false
-            end
-            i += 1
-            next
-          end
-
-          if in_block_comment
-            if char == "*" && next_char == "/"
-              in_block_comment = false
-              i += 2
-            else
-              i += 1
-            end
-            next
-          end
-
-          if in_string
-            if char == "'" && next_char == "'"
-              current << char << next_char
-              i += 2
-              next
-            elsif char == "'"
-              in_string = false
-              current << char
-              i += 1
-              next
-            end
-            current << char
-            i += 1
-            next
-          end
-
-          case char
-          when "'"
-            in_string = true
-            current << char
-          when "-"
-            if next_char == "-"
-              in_line_comment = true
-              i += 2
-              next
-            end
-            current << char
-          when "#"
-            in_line_comment = true
-            i += 1
-            next
-          when "/"
-            if next_char == "*"
-              in_block_comment = true
-              i += 2
-              next
-            end
-            current << char
-          when ";"
-            stmt = current.strip
-            statements << stmt unless stmt.empty?
-            current = +""
-          else
-            current << char
-          end
-          i += 1
-        end
-
-        stmt = current.strip
-        statements << stmt unless stmt.empty?
-        statements
-      end
-
       def normalize_binds(binds)
         binds.map do |value|
           case value

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-turso
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ben D'Angelo
@@ -13,22 +13,16 @@ dependencies:
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '8.0'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.2'
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '8.0'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '8.2'
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: turso
   requirement: !ruby/object:Gem::Requirement
@@ -69,7 +63,9 @@ files:
 - lib/active_record/connection_adapters/turso_adapter/schema_statements.rb
 - lib/active_record/connection_adapters/turso_adapter/statement_pool.rb
 - lib/active_record/connection_adapters/turso_adapter/transaction_management.rb
+- lib/active_record/tasks/turso_database_tasks.rb
 - lib/activerecord-turso.rb
+- lib/activerecord-turso/error.rb
 - lib/activerecord-turso/version.rb
 - lib/turso/ar/connection.rb
 licenses:
@@ -91,5 +87,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.15
 specification_version: 4
-summary: ActiveRecord adapter for Turso
+summary: Embedded ActiveRecord adapter for Turso (SQLite-compatible)
 test_files: []