activerecord-turso 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69e6be67a21fd809792bf867f81f6205bb06a6cc457aa05c2b80080cf272fd9b
-  data.tar.gz: d1a18f2e763cb6b5781521f1e8bd12f8a7159d3350c2fe5e91fe02ee00a50f1f
+  metadata.gz: 04f8ecc726fa450fadcf8b819a04663b3035bed1c1b5f592d362ec07664d2f14
+  data.tar.gz: 4ce85117e6f562ead6d2defeaaa5c70fccc2c62492d9916c798e56bcf32acfca
 SHA512:
-  metadata.gz: defa80378418aabb5b0b619392e180102f633ce7f8f6a13d6778f34a47c47f14c2739dc5248aaf0011e8f40788002ae42fea373789e3fc8b5e6e1ea5ebac8b35
-  data.tar.gz: 573a7f4f59c98621b9c4f95af1daa2a8fe133b3e487ef83c7d73af51c8c65655cbff080ef2d3813d7e64868273b186f121d69653499bee67f1180463fc946f9a
+  metadata.gz: 6d18e249a927642d705959341439129523cb3f2763ab699a8c2dfbc1f38d8f52b3b831a96f140a95518f3e932a9da348184af605525d354a54893419f332c0aa
+  data.tar.gz: 8b1cec4617634414e11928453aeed21e2c382fe4a36357ca435b601f337f8b9ca3fb732f035db02ebd8a0fe8f7dfc35db961c384faffd2cf8937ea612ec6363e

data/README.md

@@ -8,10 +8,14 @@ This adapter is under **active** development. It can run basic ActiveRecord oper
 
 ## Requirements
 
-- Ruby >= 3.0
+- Ruby >= 3.2
 - ActiveRecord >= 8.0, < 8.2
 - 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,23 @@ end
 Post.create!(title: "Hello", body: "World", published: true)
 ```
 
-### MVCC / BEGIN CONCURRENT
+## 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"
+```
+
+### 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 +144,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 +151,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 +160,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.
@@ -176,7 +179,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.
 
@@ -188,13 +191,16 @@ The adapter uses a bounded statement pool with a default limit inherited from Ra
 
 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.
 
-### 6. Some SQLite-specific features are unsupported or conservatively flagged
+### 6. INSERT RETURNING is disabled (not supported by Turso)
+
+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.
+
+### 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` in the underlying bindings is a Ruby-side fallback
 
 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.
 

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
+          when ::Turso::BusyException
             ActiveRecord::Deadlocked.new(message, sql: sql, binds: binds)
-          when ::Turso::ReadonlyError
+          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,7 +34,7 @@ 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)

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/version.rb

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

data/lib/turso/ar/connection.rb

@@ -19,11 +19,11 @@ 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)
+        @db = ::Turso::Database.new(config[:database].to_s, **db_opts)
       end
 
       def last_insert_rowid
-        query("SELECT last_insert_rowid()").first&.values&.first.to_i
+        query("SELECT last_insert_rowid()").first&.to_a&.first.to_i
       end
 
       def raw_connection
@@ -39,12 +39,12 @@ 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)
@@ -61,10 +61,6 @@ module Turso
         @db.busy_timeout = ms.to_i
       end
 
-      def query_timeout=(ms)
-        @db.query_timeout = ms.to_i
-      end
-
       def interrupt
         @db.interrupt
       end
@@ -127,6 +123,10 @@ module Turso
               next
             end
             current << char
+          when "#"
+            in_line_comment = true
+            i += 1
+            next
           when "/"
             if next_char == "*"
               in_block_comment = true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-turso
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ben D'Angelo