activerecord-beagle-turso 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a1a95bf62c876f996098db6a065aa9157af882b13d5038c7a86226ea6514b8b
-  data.tar.gz: 36d1eb3bdaf31d214ca80a1ab3754323cec795172bf00e2bcfd78d6812a7b3d7
+  metadata.gz: 51cf88616ac49583385f9d993560cc4f5fb53169707dec16c68b3c37f6d60884
+  data.tar.gz: 21732cc614964877aeca0da6e34d066cfcfb2061747ac68f9eb2803abff60d1a
 SHA512:
-  metadata.gz: ab8346581f6054cec006ab218b12e03db82b4dde79f5afe3093fee8ccfc8e3116f5dc82b4152cccaac0415c449a19a4fbe4343cf6bfc34c11992eb3a7ee6b925
-  data.tar.gz: 83ba09effe58a3c3598034db2982ab7f6a0037da1b4beeefea01db6b57c1ffc94de39b8ebf6b9bd09af87da48d94a2cbffdbe2445e911270c7e293f416f8eade
+  metadata.gz: fe0832ec4ae1acc466934cb0ed1a0c47f2de5e5d5f86b47091ffbe1c5e8f77c86ee50534808d2cf7dbef318aa526cd0026146ac367d1c3f56275723d8630ccc3
+  data.tar.gz: bf86e7af654df142cd722228c9245bd5456b6cfd9b2de5a43ae9067e018fee5491e17005896eec7f693ef0fc9e8d9bd9ac1d5791033bfff579879562fd69d1b9

data/README.md

@@ -125,6 +125,18 @@ A recurring `SyncJob` against a local-only connection will fail every run
 with `NotSyncedError` — only add the recurring entry for environments whose
 `database.yml` connection actually carries `remote_url:`/`auth_token:`.
 
+## Synced replicas: what's guarded
+
+Three bugs in the Turso 0.8.3 sync engine affect a synced replica (`remote_url:` + `auth_token:`). Bug B is [tursodatabase/turso#9551](https://github.com/tursodatabase/turso/issues/9551); bugs A and C are being reported upstream. This adapter guards against each. Local-only connections are unchanged.
+
+- **`rename_table` is refused (bug C).** The engine does not capture `ALTER TABLE ... RENAME TO` or `RENAME COLUMN` for sync, so the remote keeps the old name and every later write to the table is lost on push. `rename_table`, and raw `execute("ALTER TABLE ... RENAME ...")`, raise `ActiveRecord::ConnectionAdapters::BeagleTurso::UnsupportedOnSyncedReplica`. Instead, create a new table, copy the data, and drop the old one; or apply the rename directly on the remote and pull, with writes to that table paused. `rename_column` is allowed: Rails 8.1's SQLite adapter implements it as a table copy, not a native `RENAME COLUMN`.
+- **Insert ids come from `RETURNING` (bug B).** On an MVCC replica with change capture (every synced replica of a `--tursodb` remote) the engine's `last_insert_rowid` returns an internal change id. Model creates already use `INSERT ... RETURNING "id"`. Plain `INSERT`s (including `WITH ... INSERT`, and `connection.insert` / `exec_insert` on a table without a named primary key) now run as `INSERT ... RETURNING rowid` and the id is read from the result. Override with `insert_returning_rowid: true|false` in `database.yml`.
+- **Migrations push first and last (bug A).** Unpushed row writes to a table that is altered or dropped before the next push are skipped by the remote and then lost on pull. When a migration is pending (or the database is new), `db:migrate`, `db:prepare` and their `:<primary>`-namespaced forms push before and after. `db:migrate:up/down/redo`, `db:rollback` and `db:forward` (also with the `:<primary>` suffix) always push, since they always run a migration. With nothing pending, `db:prepare` (which Rails 8 runs on every container boot) does no push and no network I/O.
+  - If the push before fails, the task aborts without migrating.
+  - A migration that copies a table (`change_column*`, `remove_column`, `add_foreign_key`, `add_timestamps`, ...) makes the first push after it fail once, although the remote ends up with everything. The push after is therefore retried once: if the retry works you only get a warning. If it fails twice the task fails, telling you the schema change exists locally and the push failed.
+  - Set `BEAGLE_TURSO_SKIP_MIGRATION_PUSH=1` to skip both pushes, with a warning (unpushed writes to altered tables may be lost).
+  - Only the primary database is guarded. `db:schema:load`, `db:setup` and `db:reset` do not work with this adapter (Rails raises `DatabaseNotSupported`); use migrations.
+
 ## Test coverage
 
 This gem's own spec suite (`spec/`, run via `bundle exec rspec`) is 35
@@ -228,6 +240,20 @@ this gem.
    each sync — pick a sync cadence accordingly, or run Solid Queue in a separate
    process.
 
+## Known engine issue: self-referencing foreign keys
+
+Turso's engine has open bugs with foreign keys that reference their own table
+(such as `parent_id`): a multi-row `delete_all`, `update_all` or `DROP TABLE` that SQLite accepts can fail with
+`FOREIGN KEY constraint failed`, and `ON DELETE SET NULL` / `CASCADE` can leave
+rows behind or orphaned
+([tursodatabase/turso#8713](https://github.com/tursodatabase/turso/issues/8713),
+[#9279](https://github.com/tursodatabase/turso/issues/9279),
+[#9293](https://github.com/tursodatabase/turso/issues/9293),
+[#9294](https://github.com/tursodatabase/turso/issues/9294)). Foreign keys
+between two different tables are unaffected. Workaround: avoid `ON DELETE`
+actions on self-referencing foreign keys, and delete children before parents,
+one level at a time.
+
 ## License
 
 [MIT](https://opensource.org/licenses/MIT).

data/lib/active_record/connection_adapters/beagle_turso/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module BeagleTurso
+      # Raised instead of running a schema change that the Turso sync engine
+      # cannot replicate. On a synced replica, `ALTER TABLE ... RENAME TO` and
+      # `RENAME COLUMN` are not captured for sync (engine 0.8.3), so the remote
+      # never sees them and every later write to the renamed table or column is
+      # lost on push.
+      class UnsupportedOnSyncedReplica < ::ActiveRecord::ActiveRecordError; end
+
+      # Raised by the db:migrate family of rake tasks when pending writes could
+      # not be pushed to Turso before (or after) a migration.
+      class MigrationPushError < ::ActiveRecord::ActiveRecordError; end
+    end
+  end
+end

data/lib/active_record/connection_adapters/beagle_turso/migration_push.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/beagle_turso/errors"
+require "active_record/connection_adapters/beagle_turso/sync_manager"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module BeagleTurso
+      # Pushes a synced replica to Turso before and after schema-changing rake
+      # tasks, when (and only when) a migration is actually going to run.
+      #
+      # Why: the sync engine replays each unpushed row change against the
+      # CURRENT local schema when it pushes. If the table was dropped, or lost
+      # columns, since the write, the remote skips the statement, commits the
+      # rest of the batch anyway, and the next pull resets the replica to the
+      # remote -- the write is gone on both sides. Pushing immediately before
+      # the migration leaves nothing pending to be mis-replayed; pushing again
+      # afterwards publishes the new schema. (A copy-table migration on a table
+      # with rows makes that second push fail once, spuriously, for the same
+      # reason; the data is all on the remote and a retry succeeds.)
+      #
+      # Local-only connections are never touched.
+      module MigrationPush
+        SKIP_ENV = "BEAGLE_TURSO_SKIP_MIGRATION_PUSH"
+
+        # Pushes only when a migration is pending (or the database is not
+        # initialised): db:prepare runs on every container boot in Rails 8 and
+        # must not need the network when there is nothing to do.
+        CHECKED_TASKS = %w[db:migrate db:prepare].freeze
+
+        # Tasks that always run a specific migration, so always push.
+        ALWAYS_TASKS = %w[
+          db:migrate:up db:migrate:down db:migrate:redo db:rollback db:forward
+        ].freeze
+
+        # db:schema:load has no effect with this adapter (Rails raises
+        # DatabaseNotSupported for it) but is listed so that it is guarded if
+        # that ever changes.
+        SCHEMA_TASKS = %w[db:schema:load].freeze
+
+        # Prepended onto Rake::Task so it works whatever order the Railtie and
+        # ActiveRecord's own rake tasks load in.
+        module TaskHook
+          def execute(args = nil)
+            if name.start_with?("db:") && MigrationPush.guarded?(name)
+              MigrationPush.around(name) { super }
+            else
+              super
+            end
+          end
+        end
+
+        class << self
+          def install!
+            return if ::Rake::Task.ancestors.include?(TaskHook)
+            ::Rake::Task.prepend(TaskHook)
+          end
+
+          # "db:migrate", "db:migrate:primary", "db:rollback:primary", ...
+          # The suffix is the PRIMARY config's own name, never hard-coded.
+          def guarded?(task_name)
+            base = base_task(task_name)
+            base && (CHECKED_TASKS + ALWAYS_TASKS + SCHEMA_TASKS).include?(base)
+          end
+
+          def base_task(task_name)
+            all = CHECKED_TASKS + ALWAYS_TASKS + SCHEMA_TASKS
+            return task_name if all.include?(task_name)
+
+            name = primary_config&.name
+            return unless name && task_name.end_with?(":#{name}")
+
+            base = task_name.delete_suffix(":#{name}")
+            base if all.include?(base)
+          end
+
+          def around(task_name)
+            return yield if depth.positive? # nested task: the outermost one guards
+
+            config = primary_config
+            return yield unless config && synced_config?(config.configuration_hash)
+
+            if skip?
+              warn "beagle_turso: WARNING: #{SKIP_ENV}=1 -- NOT pushing pending writes to Turso around " \
+                   "#{task_name}. Unpushed writes to tables altered by this task may be lost."
+              return yield
+            end
+
+            existing = local_database_exists?(config.configuration_hash)
+            if CHECKED_TASKS.include?(base_task(task_name)) && existing
+              return yield unless migration_pending?
+            end
+
+            # A replica that does not exist yet has nothing local to push.
+            push_before! if existing
+            self.depth = 1
+            begin
+              result = yield
+            ensure
+              self.depth = 0
+            end
+            push_after!
+            result
+          end
+
+          def primary_config
+            ::ActiveRecord::Base.configurations.find_db_config(rails_env)
+          rescue StandardError
+            nil
+          end
+
+          def synced_config?(hash)
+            hash[:adapter].to_s == "beagle_turso" && !hash[:remote_url].to_s.empty? && !hash[:auth_token].to_s.empty?
+          end
+
+          def skip?
+            ENV[SKIP_ENV] == "1"
+          end
+
+          private
+
+          def rails_env
+            defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : (ENV["RAILS_ENV"] || "development")
+          end
+
+          def local_database_exists?(hash)
+            path = hash[:database].to_s
+            return false if path.empty? || path == ":memory:"
+
+            root = defined?(::Rails) && ::Rails.respond_to?(:root) ? ::Rails.root : nil
+            File.exist?(root ? File.expand_path(path, root.to_s) : path)
+          end
+
+          # True when a migration is pending, or the schema is not initialised
+          # (no schema_migrations table reads as everything pending). Any
+          # trouble answering counts as pending: the guard then runs.
+          def migration_pending?
+            connection.pool.migration_context.needs_migration?
+          rescue StandardError
+            true
+          end
+
+          # Re-resolved on every use: multi-database tasks swap connection pools
+          # (with_temporary_pool), so a connection held across the task could
+          # belong to a pool that is gone. lease_connection does not raise under
+          # permanent_connection_checkout = :disallowed, as .connection does.
+          def connection
+            ::ActiveRecord::Base.lease_connection
+          end
+
+          def push_before!
+            ::Beagle::Turso::SyncManager.push!(connection)
+          rescue StandardError => e
+            raise MigrationPushError.new(
+              "beagle_turso: could not push pending writes to Turso before migrating (#{describe(e)}). " \
+              "Fix sync first, or set #{SKIP_ENV}=1 to migrate anyway (unpushed writes to altered tables " \
+              "may be lost)."
+            ), cause: nil
+          end
+
+          # A copy-table migration on a table with rows (change_column*,
+          # remove_column, add_foreign_key, add_timestamps, ...) makes the first
+          # push after it fail with a parse error even though the remote ends up
+          # with everything (sync engine bug A); the second push succeeds. So
+          # retry once before reporting a failure.
+          def push_after!
+            ::Beagle::Turso::SyncManager.push!(connection)
+          rescue StandardError => first
+            begin
+              ::Beagle::Turso::SyncManager.push!(connection)
+              warn "beagle_turso: WARNING: the push after the migration failed once (#{describe(first)}) and " \
+                   "succeeded on retry. This is expected after a migration that copies a table (sync engine " \
+                   "quirk); no data was lost."
+            rescue StandardError => second
+              raise MigrationPushError.new(
+                "beagle_turso: the schema change was applied to the local replica, but pushing it to Turso " \
+                "failed twice (#{describe(first)}; then #{describe(second)}). The remote may not have the " \
+                "new schema yet: check sync, then run Beagle::Turso::SyncManager.push!."
+              ), cause: nil
+            end
+          end
+
+          def describe(error)
+            message = error.message
+            message = ::Beagle::Turso::Redaction.message(message) if defined?(::Beagle::Turso::Redaction)
+            prefix = error.class.name.to_s.end_with?("OpenError") ? "could not open the synced replica: " : ""
+            "#{error.class}: #{prefix}#{message}"
+          end
+
+          def depth = Thread.current[:beagle_turso_migration_push_depth].to_i
+          def depth=(value)
+            Thread.current[:beagle_turso_migration_push_depth] = value
+          end
+        end
+      end
+
+      if defined?(::Rails::Railtie)
+        class Railtie < ::Rails::Railtie
+          rake_tasks do
+            require "rake"
+            MigrationPush.install!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/beagle_turso_adapter.rb

@@ -3,6 +3,7 @@
 require "active_record"
 require "active_record/connection_adapters/sqlite3_adapter"
 require "beagle/turso"
+require "active_record/connection_adapters/beagle_turso/errors"
 
 module ActiveRecord
   module ConnectionAdapters
@@ -59,6 +60,20 @@ module ActiveRecord
       INSERT_REGEX = /\bINSERT\b/i
       private_constant :INSERT_REGEX
 
+      # String literals, quoted identifiers and comments: where words like
+      # RETURNING or RENAME are data, not syntax. Masked before any keyword
+      # matching (same approach as sequel-beagle-turso).
+      NON_CODE = %r{'(?:[^']|'')*'|"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]|--[^\n]*|/\*.*?\*/}m
+      private_constant :NON_CODE
+
+      # `ALTER TABLE <t> RENAME ...`, tested on masked SQL.
+      RENAME_REGEX = /\A\s*ALTER\s+TABLE\s+\S+\s+RENAME\b/i
+      private_constant :RENAME_REGEX
+
+      # INSERT / REPLACE, optionally behind a WITH clause, tested on masked SQL.
+      INSERT_STATEMENT_REGEX = /\A\s*(?:(?:INSERT|REPLACE)\b|WITH\b[\s\S]*\)\s*(?:INSERT|REPLACE)\b)/i
+      private_constant :INSERT_STATEMENT_REGEX
+
       class << self
         # Open a beagle-turso Database (synced remote when +remote_url+ is
         # present, otherwise local/in-memory) and wrap it so the SQLite3Adapter
@@ -77,6 +92,10 @@ module ActiveRecord
             end
           Client.new(database)
         end
+
+        def synced_config?(config)
+          !config[:remote_url].to_s.empty? && !config[:auth_token].to_s.empty?
+        end
       end
 
       # Adapts a Beagle::Turso::Database + its connected Connection to the subset
@@ -205,7 +224,36 @@ module ActiveRecord
         end
       end
 
+      # Refused on a synced replica: the sync engine (turso 0.8.3) does not
+      # capture `ALTER TABLE ... RENAME TO`, so the remote never gets the new
+      # name and every later write to the table is lost on push.
+      # (rename_column is allowed: Rails' SQLite adapter implements it as a
+      # copy-table, not a native RENAME COLUMN.)
+      def rename_table(table_name, new_name, **options)
+        refuse_rename!("rename_table(#{table_name.inspect}, #{new_name.inspect})")
+        super
+      end
+
+      # True when this connection is a synced replica, decided from the config
+      # exactly as new_client decides it. Deliberately does NOT touch
+      # raw_connection: the public accessor disables lazy transactions and marks
+      # the connection dirty, which would make every local-only app pay for it.
+      def synced_replica?
+        self.class.synced_config?(@config)
+      end
+
       private
+        def refuse_rename!(what)
+          return unless synced_replica?
+
+          raise BeagleTurso::UnsupportedOnSyncedReplica,
+            "beagle_turso: #{what} is not supported on a synced replica. The Turso sync engine does not " \
+            "replicate ALTER TABLE ... RENAME, so the remote would keep the old name and every later " \
+            "write to it would be lost on push. Instead: create a new table, copy the data across, then " \
+            "drop the old one; or apply the rename directly on the remote database, then pull (with " \
+            "writes to that table paused)."
+        end
+
         # Every table-listing question Rails asks (`tables`, `views`,
         # `data_sources`, `table_exists?`, and through them the schema cache and
         # the schema dumper) is built from this one string in
@@ -302,22 +350,31 @@ module ActiveRecord
         # Result#affected_rows, so building the Result correctly is all we need.
         def perform_query(raw_connection, sql, binds, type_casted_binds, prepare:, notification_payload:, batch: false)
           params = type_casted_binds || []
+          refuse_rename!(sql.strip[0, 60]) if synced_replica? && RENAME_REGEX.match?(mask_non_code(sql))
 
           result =
             if batch
               raw_connection.execute_batch(sql)
               ::ActiveRecord::Result.empty
             elsif write_statement?(sql)
-              affected = raw_connection.execute(sql, params)
-              @last_inserted_rowid = raw_connection.last_insert_rowid
-              ::ActiveRecord::Result.empty(affected_rows: affected)
+              if (rewritten = sql_with_returning_rowid(sql))
+                insert_returning_rowid(raw_connection, rewritten, params)
+              else
+                affected = raw_connection.execute(sql, params)
+                @last_inserted_rowid = raw_connection.last_insert_rowid
+                ::ActiveRecord::Result.empty(affected_rows: affected)
+              end
             else
               columns, rows = raw_connection.query_result(sql, params)
               # Belt-and-suspenders: a RETURNING insert lands here (id read from
               # rows by last_inserted_id), and a data-modifying CTE that slips past
               # write_statement? would too -- keep the rowid so an inserted id is
               # never silently lost even on a heuristic miss.
-              @last_inserted_rowid = raw_connection.last_insert_rowid if INSERT_REGEX.match?(sql)
+              if INSERT_REGEX.match?(sql)
+                # On a replica where last_insert_rowid is untrustworthy, never
+                # offer it as a fallback id (a RETURNING insert's id is in rows).
+                @last_inserted_rowid = insert_returning_rowid? ? nil : raw_connection.last_insert_rowid
+              end
               ::ActiveRecord::Result.new(columns, rows)
             end
 
@@ -335,10 +392,55 @@ module ActiveRecord
         # though it mutates. write_query? is a pure predicate here, so calling it a
         # second time is side-effect free.
         def write_statement?(sql)
-          return false if RETURNING_REGEX.match?(sql)
+          return false if returning_clause?(sql)
           write_query?(sql) || data_modifying_cte?(sql)
         end
 
+        # On an MVCC replica with change capture (every synced replica of a
+        # `--tursodb` remote) the engine's last_insert_rowid returns the CDC
+        # change id, not the inserted row's id (tursodatabase/turso#9551).
+        # INSERT ... RETURNING is unaffected, so plain INSERTs are run as
+        # `INSERT ... RETURNING rowid` and the id is read from the result.
+        # Default: on for synced replicas; `insert_returning_rowid: true|false`
+        # in database.yml overrides (e.g. a local MVCC+CDC file).
+        def insert_returning_rowid?
+          setting = @config[:insert_returning_rowid]
+          cast = setting.nil? || setting == "" ? nil : ::ActiveModel::Type::Boolean.new.cast(setting)
+          cast.nil? ? synced_replica? : cast
+        end
+
+        # Comments become spaces (they are not part of the statement); literals
+        # and quoted identifiers become "x" (they are).
+        def mask_non_code(sql)
+          sql.gsub(NON_CODE) { |m| (m.start_with?("--", "/*") ? " " : "x") * m.length }
+        end
+
+        # A real RETURNING clause, not the word inside a literal, identifier or
+        # comment.
+        def returning_clause?(sql)
+          RETURNING_REGEX.match?(sql) && RETURNING_REGEX.match?(mask_non_code(sql))
+        end
+
+        # [rewritten_sql] when this plain INSERT should run as RETURNING rowid.
+        def sql_with_returning_rowid(sql)
+          return unless insert_returning_rowid?
+
+          masked = mask_non_code(sql)
+          return unless INSERT_STATEMENT_REGEX.match?(masked)
+          return if RETURNING_REGEX.match?(masked)
+
+          # Before any trailing ";" and trailing comment (a "--" comment would
+          # otherwise swallow the clause).
+          at = masked.sub(/;\s*\z/, "").rstrip.length
+          "#{sql[0, at]}\nRETURNING rowid#{sql[at..]}"
+        end
+
+        def insert_returning_rowid(raw_connection, rewritten, params)
+          _columns, rows = raw_connection.query_result(rewritten, params)
+          @last_inserted_rowid = rows.last&.first
+          ::ActiveRecord::Result.empty(affected_rows: rows.length)
+        end
+
         def data_modifying_cte?(sql)
           DATA_MODIFYING_CTE_REGEX.match?(sql)
         end

data/lib/activerecord/beagle_turso/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module BeagleTurso
-    VERSION = "0.1.6"
+    VERSION = "0.1.7"
   end
 end

data/lib/activerecord-beagle-turso.rb

@@ -4,3 +4,5 @@ require "activerecord/beagle_turso/version"
 require "active_record/connection_adapters/beagle_turso_adapter"
 require "active_record/connection_adapters/beagle_turso/sync_manager"
 require "active_record/connection_adapters/beagle_turso/sync_job"
+require "active_record/connection_adapters/beagle_turso/errors"
+require "active_record/connection_adapters/beagle_turso/migration_push"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-beagle-turso
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - BeagleSoftwareUK
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -93,6 +93,8 @@ extra_rdoc_files: []
 files:
 - README.md
 - config/recurring.yml.example
+- lib/active_record/connection_adapters/beagle_turso/errors.rb
+- lib/active_record/connection_adapters/beagle_turso/migration_push.rb
 - lib/active_record/connection_adapters/beagle_turso/sync_job.rb
 - lib/active_record/connection_adapters/beagle_turso/sync_manager.rb
 - lib/active_record/connection_adapters/beagle_turso_adapter.rb