activerecord-turso 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69e6be67a21fd809792bf867f81f6205bb06a6cc457aa05c2b80080cf272fd9b
-  data.tar.gz: d1a18f2e763cb6b5781521f1e8bd12f8a7159d3350c2fe5e91fe02ee00a50f1f
+  metadata.gz: b8e00bcf26be0b39f02a05bd0f4850db41d277f7d72bdb15013c218f032d93eb
+  data.tar.gz: 9e9ccad1e346648fef21eb2d0a3aceafa7afada0bc67348a0ed912b723e6cca5
 SHA512:
-  metadata.gz: defa80378418aabb5b0b619392e180102f633ce7f8f6a13d6778f34a47c47f14c2739dc5248aaf0011e8f40788002ae42fea373789e3fc8b5e6e1ea5ebac8b35
-  data.tar.gz: 573a7f4f59c98621b9c4f95af1daa2a8fe133b3e487ef83c7d73af51c8c65655cbff080ef2d3813d7e64868273b186f121d69653499bee67f1180463fc946f9a
+  metadata.gz: c16dce07f7dbcf2bd60d07e58b10d6960c7d4a2945f88deda0082c532b0e1e42cc58213582acd2548c0c19d72a13ef30e5688503ba8ab9a00b7fa99f882048e8
+  data.tar.gz: 22f295b0eda449f11b5f31c63b16718e5f609452904b0c9c5b534117fe4145324460d3ed56f7ac7365f38345ac165eb8969a3e01bb5c21d59c2e9f3bef2f4f4d

data/README.md

@@ -4,14 +4,18 @@ 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 ActiveRecord 8.1 applications. The underlying `turso` gem releases the GVL during blocking operations, supports fiber-aware connection ownership, and uses native batch execution.
 
 ## Requirements
 
-- Ruby >= 3.0
-- ActiveRecord >= 8.0, < 8.2
+- Ruby >= 3.2
+- ActiveRecord ~> 8.1.0
 - The `turso` Ruby gem
 
+## Runtime dependencies
+
+This adapter uses the `turso` gem and does **not** require the `sqlite3` Ruby gem at runtime.
+
 ## Installation
 
 Add to your Gemfile:
@@ -47,7 +51,42 @@ end
 Post.create!(title: "Hello", body: "World", published: true)
 ```
 
-### MVCC / BEGIN CONCURRENT
+## Configuration
+
+### Recommended production configuration
+
+```yaml
+production:
+  adapter: turso
+  database: db/production.sqlite3
+  journal_mode: wal
+  pool: 5
+  timeout: 5000
+  busy_timeout: 5000
+  query_timeout: 30000
+  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)`.
 
 Turso supports `BEGIN CONCURRENT` for optimistic, multi-writer transactions. To opt in, pass `concurrent: true` to `transaction`:
 
@@ -124,8 +163,6 @@ development:
   journal_mode: mvcc
   busy_timeout: 5000
 
-  # Enable experimental Turso features when needed (e.g., custom index methods for FTS).
-  # Pass a comma-separated string or an array of feature names.
   experimental_features: "index_method"
 ```
 
@@ -133,7 +170,6 @@ Use `concurrent: true` inside the same pinned connection:
 
 ```ruby
 ActiveRecord::Base.connection.transaction(concurrent: true) do
-  # read-modify-write using raw SQL or bulk operations
 end
 ```
 
@@ -143,20 +179,6 @@ Caveats:
 - 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.
 - FTS custom index modules are not supported in MVCC mode.
 
-## Recommended production configuration
-
-```yaml
-production:
-  adapter: turso
-  database: db/production.sqlite3
-  journal_mode: wal            # Use mvcc only if you need concurrent writers and understand the caveats above
-  pool: 5
-  timeout: 5000                # busy_timeout default in milliseconds
-  query_timeout: 30000           # maximum time a single query may run
-  busy_timeout: 5000           # explicit busy timeout (falls back to timeout)
-  experimental_features: "index_method"
-```
-
 ## Limitations and Risks
 
 The following limitations apply to the current implementation. Read this section carefully before deploying to production.
@@ -165,9 +187,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
 
@@ -176,7 +198,7 @@ The adapter's batch execution path splits multi-statement SQL on semicolons. Thi
 - ActiveRecord expects transactions to commit unless the database returns an error. With `BEGIN CONCURRENT`, the commit can fail with a snapshot conflict and must be retried.
 - The retry loop must run on the same connection. Rails' connection pool is not MVCC-aware and may return the connection to the pool between retries.
 - Do not combine concurrent transactions with pessimistic locking (`lock!`, `with_lock`, `lock_version`).
-- Normal model persistence (`create!`, `save!`, `update!`, `touch`) is unsupported inside a concurrent transaction because ActiveRecord opens an internal transaction for each model change. The error is retried a few times, then raised as `ActiveRecord::StatementInvalid`.
+- Normal model persistence (`create!`, `save!`, `update!`, `touch`) is unsupported inside a concurrent transaction because ActiveRecord opens an internal transaction for each model change.
 
 Only use `transaction(concurrent: true)` after testing it under your app's concurrency patterns, and prefer raw SQL or bulk operations inside the block.
 
@@ -184,19 +206,22 @@ 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
+
+The adapter is pinned to ActiveRecord `~> 8.1.0`.
+
+### 6. INSERT RETURNING is disabled (not supported by Turso)
 
-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 underlying Turso SQLite build does not support `INSERT ... RETURNING` syntax. The adapter reports `supports_insert_returning?` as `false`, so ActiveRecord falls back to `last_insert_rowid()` for retrieving inserted IDs.
 
-### 6. Some SQLite-specific features are unsupported or conservatively flagged
+### 7. Some SQLite-specific features are unsupported or conservatively flagged
 
 - 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_returning` is enabled only when the reported SQLite version is `>= 3.35.0`.
 - `insert_on_conflict` is enabled only when the reported SQLite version is `>= 3.24.0`.
 
-### 7. `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

@@ -54,6 +54,9 @@ module ActiveRecord
             execute("PRAGMA journal_mode = #{mode}")
             if @config[:journal_mode].to_s.downcase == "mvcc"
               @mvcc_enabled = true
+              ActiveRecord::Base.logger&.warn(
+                "Turso journal_mode: mvcc is experimental. Concurrent transactions require careful connection handling."
+              )
             end
           end
 
@@ -62,8 +65,7 @@ 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/database_statements.rb

@@ -6,7 +6,7 @@ module ActiveRecord
       module DatabaseStatements
         def execute(sql, name = nil)
           materialize_transactions
-          raw_execute(sql, name)
+          raw_execute(sql, name)&.to_a
         end
 
         def last_inserted_id(sql)
@@ -25,22 +25,13 @@ module ActiveRecord
           binds
         end
 
-        def select_rows(arel, name = nil)
+        def select_rows(arel, name = nil, binds = [], _options = {})
           arel = arel_from_relation(arel)
-          sql, binds = to_sql_and_binds(arel)
+          sql, binds = to_sql_and_binds(arel, binds)
           type_casted_binds = type_casted_binds(binds)
 
           log(sql, name, binds, type_casted_binds) do
-            with_raw_connection do |conn|
-              stmt = conn.prepare(sql)
-              stmt.bind_positional(type_casted_binds) unless type_casted_binds.empty?
-              rows = []
-              while stmt.step == 1
-                rows << stmt.row.to_a
-              end
-              stmt.finalize
-              rows
-            end
+            exec_query(sql, name, binds, prepare: false).rows
           end
         end
 
@@ -57,21 +48,20 @@ module ActiveRecord
           end
 
           stmt.reset if prepare
-          stmt.bind_positional(type_casted_binds) unless type_casted_binds.empty?
+          stmt.bind(*type_casted_binds) unless type_casted_binds.empty?
 
           begin
-            if write_query?(sql)
-              affected_rows = stmt.execute
+            if write_query?(sql) && !sql.match?(/\bRETURNING\b/i)
+              result = stmt.run
+              affected_rows = result[:changes]
               verified!
               notification_payload[:affected_rows] = affected_rows
               notification_payload[:row_count] = 0
               ActiveRecord::Result.empty(affected_rows: affected_rows)
             else
-              columns = (0...stmt.column_count).map { |i| stmt.column_name(i) }
-              rows = []
-              while stmt.step == 1
-                rows << stmt.row.to_a
-              end
+              columns_info = stmt.columns
+              columns = columns_info.map { |c| c[:name] }
+              rows = stmt.all.map(&:to_a)
               affected_rows = raw_connection.changes
               verified!
               notification_payload[:affected_rows] = affected_rows
@@ -80,7 +70,7 @@ module ActiveRecord
               ActiveRecord::Result.new(columns, rows, type_map, affected_rows: affected_rows)
             end
           ensure
-            stmt.finalize unless prepare
+            stmt.close unless prepare
           end
         end
 
@@ -89,11 +79,11 @@ module ActiveRecord
           old_defer_foreign_keys = query_value("PRAGMA defer_foreign_keys")
 
           begin
-            execute("PRAGMA defer_foreign_keys = ON")
+            execute("PRAGMA defer_foreign_keys = ON") unless old_defer_foreign_keys.nil?
             execute("PRAGMA foreign_keys = OFF")
             yield
           ensure
-            if old_defer_foreign_keys
+            unless old_defer_foreign_keys.nil?
               execute("PRAGMA defer_foreign_keys = #{old_defer_foreign_keys}")
             end
             execute("PRAGMA foreign_keys = #{old_foreign_keys}")
@@ -104,9 +94,8 @@ module ActiveRecord
 
         def build_type_map(stmt)
           type_map = {}
-          count = stmt.column_count
-          count.times do |i|
-            decltype = stmt.respond_to?(:column_decltype) ? stmt.column_decltype(i) : nil
+          stmt.columns.each_with_index do |col, i|
+            decltype = col[:type]
             next unless decltype
             type_map[i] = decltype_to_type(decltype)
           end

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

@@ -7,23 +7,23 @@ module ActiveRecord
         def translate_exception(exception, message:, sql:, binds:)
           cause = exception.cause
           case cause
-          when ::Turso::ConstraintError
+          when ::Turso::ConstraintException
             translate_constraint_error(message, sql, binds)
-          when ::Turso::NotADatabaseError
+          when ::Turso::NotADatabaseException
             ActiveRecord::NoDatabaseError.new(message, sql: sql, binds: binds)
-          when ::Turso::BusySnapshotError
+          when ::Turso::BusySnapshotException
             ActiveRecord::SerializationFailure.new(message, sql: sql, binds: binds)
-          when ::Turso::BusyError
-            ActiveRecord::Deadlocked.new(message, sql: sql, binds: binds)
-          when ::Turso::ReadonlyError
+          when ::Turso::BusyException
+            ActiveRecordTurso::BusyError.new(message, sql: sql, binds: binds)
+          when ::Turso::ReadonlyException
             ActiveRecord::ReadOnlyRecord.new(message, sql: sql, binds: binds)
-          when ::Turso::IoError, ::Turso::CorruptError
+          when ::Turso::IoException, ::Turso::CorruptException
             ActiveRecord::StatementInvalid.new(message, sql: sql, binds: binds)
-          when ::Turso::DatabaseFullError
+          when ::Turso::DatabaseFullException
             ActiveRecord::StatementInvalid.new(message, sql: sql, binds: binds)
-          when ::Turso::InterruptError
+          when ::Turso::InterruptException
             ActiveRecord::QueryCanceled.new(message, sql: sql, binds: binds)
-          when ::Turso::MisuseError
+          when ::Turso::MisuseException
             ActiveRecord::StatementInvalid.new(message, sql: sql, binds: binds)
           else
             super
@@ -34,10 +34,12 @@ module ActiveRecord
 
         def translate_constraint_error(message, sql, binds)
           case message
-          when /foreign key constraint/i
+          when /foreign key constraint|foreign key mismatch/i
             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/connection_adapters/turso_adapter/schema_statements.rb

@@ -11,6 +11,7 @@ module ActiveRecord
               AND name NOT LIKE 'sqlite_%'
               AND name NOT LIKE 'fts_dir_%'
               AND name NOT LIKE 'sqlite_fts_%'
+              AND name NOT LIKE '__turso_internal_%'
           SQL
         end
 

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

@@ -9,7 +9,7 @@ module ActiveRecord
         private
 
         def dealloc(stmt)
-          stmt.finalize
+          stmt.close
         rescue ::Turso::Error
         end
       end

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

@@ -34,6 +34,10 @@ module ActiveRecord
 
         def transaction(requires_new: nil, isolation: nil, joinable: true, **options, &block)
           if options.delete(:concurrent)
+            ActiveRecord::Base.logger&.warn(
+              "transaction(concurrent: true) is experimental and may break ActiveRecord model persistence. " \
+              "See adapter documentation."
+            )
             transaction_with_mvcc(options, &block)
           else
             super
@@ -85,8 +89,7 @@ module ActiveRecord
 
         def concurrent_conflict?(exception)
           cause = exception.cause
-          conflict_classes = [::Turso::BusySnapshotError, ::Turso::BusyError]
-          conflict_classes << ::Turso::WriteWriteConflict if defined?(::Turso::WriteWriteConflict)
+          conflict_classes = [::Turso::BusySnapshotException, ::Turso::BusyException]
 
           conflict_classes.any? { |klass| cause.is_a?(klass) } ||
             /snapshot conflict|busy snapshot|database is locked|cannot start a transaction within a transaction/i.match?(exception.message)

data/lib/active_record/connection_adapters/turso_adapter.rb

@@ -25,6 +25,10 @@ module ActiveRecord
         false
       end
 
+      def sqlite_version
+        @sqlite_version ||= Gem::Version.new(query_value("SELECT sqlite_version()"))
+      end
+
       def supports_transaction_isolation?
         false
       end
@@ -37,10 +41,16 @@ module ActiveRecord
         true
       end
 
+      def quote_string(s)
+        s.gsub("'", "''")
+      end
+
       def explain(arel, binds = [], _options = [])
         sql = "EXPLAIN QUERY PLAN " + to_sql(arel, binds)
         result = exec_query(sql, "EXPLAIN", binds)
-        SQLite3::ExplainPrettyPrinter.new.pp(result)
+        result.rows.map do |row|
+          row.join(" | ")
+        end.join("\n")
       end
 
       def build_statement_pool

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.0"
+  VERSION = "0.2.2"
 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"
 

data/lib/turso/ar/connection.rb

@@ -7,7 +7,8 @@ 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=
 
       DEFAULT_BUSY_TIMEOUT_MS = 5000
       DEFAULT_QUERY_TIMEOUT_MS = 30_000
@@ -19,11 +20,10 @@ module Turso
           query_timeout: config[:query_timeout] || DEFAULT_QUERY_TIMEOUT_MS
         }
         db_opts[:experimental_features] = config[:experimental_features] if config[:experimental_features]
-        @db = ::Turso::DB.new(config[:database].to_s, **db_opts)
-      end
-
-      def last_insert_rowid
-        query("SELECT last_insert_rowid()").first&.values&.first.to_i
+        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
@@ -39,116 +39,20 @@ module Turso
       end
 
       def execute(sql, binds = [])
-        @db.execute(sql, normalize_binds(binds))
+        @db.execute(sql, *normalize_binds(binds))
         nil
       end
 
       def query(sql, params = [])
-        @db.query(sql, normalize_binds(params))
+        @db.query(sql, *normalize_binds(params))
       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 query_timeout=(ms)
-        @db.query_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 "/"
-            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.0
+  version: 0.2.2
 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
@@ -70,6 +64,7 @@ files:
 - lib/active_record/connection_adapters/turso_adapter/statement_pool.rb
 - lib/active_record/connection_adapters/turso_adapter/transaction_management.rb
 - lib/activerecord-turso.rb
+- lib/activerecord-turso/error.rb
 - lib/activerecord-turso/version.rb
 - lib/turso/ar/connection.rb
 licenses: