activerecord-beagle-turso 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63f87bcbfe56cbc279209bb29456d62bd757f1d4ea32d69ffc8c922891121c4e
+  data.tar.gz: 94028b900a3aa33ac4bbfb5e975101dad3289016f601021085aa15445fe22d6a
+SHA512:
+  metadata.gz: a407e3b271141a740dcc6c5996165ce17dd3ab4aedb0605a769ef4586e65af19825001958e42c60a4e544e5af3c4528af013312936f214dd00d36b9c9ee5b12d
+  data.tar.gz: d22efba814f090b6a114aa72e29e3e882c3acb87d542279f72eab16bf2ec7f48a6c381c38b4cb9d3e8a0b87bd3d79c0d187cefe0de9b604c92b1c1b55dba1624

data/README.md

@@ -0,0 +1,231 @@
+# activerecord-beagle-turso
+
+An ActiveRecord connection adapter for [Turso](https://turso.tech)'s libsql
+engine, backed by the [`beagle-turso`](../beagle-turso) driver. It subclasses
+Rails' stock `SQLite3Adapter` and reroutes only the raw-execution seam onto
+`beagle-turso`, so SQL generation, quoting, schema introspection, and
+transaction handling are all inherited unchanged — you get a normal
+ActiveRecord experience, running against a local, in-memory, or
+remote-synced Turso database.
+
+## Install
+
+Add both gems to your `Gemfile` (`activerecord-beagle-turso` depends on
+`beagle-turso`, but Bundler needs it listed explicitly if you're installing
+from a path/git source rather than RubyGems):
+
+```ruby
+gem "activerecord-beagle-turso"
+gem "beagle-turso"
+```
+
+or install directly:
+
+```sh
+gem install activerecord-beagle-turso
+```
+
+`beagle-turso` has a native (Rust) extension, so installing it requires a
+Rust toolchain unless a precompiled binary gem is available for your
+platform — see [`beagle-turso`'s README](../beagle-turso/README.md#install)
+for details. **There is currently no precompiled/cross-compiled gem release
+job for either gem** — installing means building the extension locally
+(or, as in this repo, from a path dependency built once already).
+
+## `config/database.yml`
+
+Set `adapter: beagle_turso`. A **local** connection (no sync) needs only
+`database:`:
+
+```yaml
+development:
+  adapter: beagle_turso
+  database: storage/development.sqlite3
+```
+
+A **synced** connection additionally sets `remote_url:` and `auth_token:` —
+both are required together to enable sync (see
+[`Beagle::Turso::Database.open`](../beagle-turso/README.md#synced-example)):
+
+```yaml
+production:
+  adapter: beagle_turso
+  database: storage/production.sqlite3
+  remote_url: <%= Rails.application.credentials.dig(:turso, :prod_url) %>
+  auth_token: <%= Rails.application.credentials.dig(:turso, :prod_token) %>
+  # Informational only (see "Recurring sync" below) -- not read by this
+  # adapter or by SyncManager. Keep it in sync with recurring.yml by hand.
+  sync_interval: 30 # seconds
+```
+
+Never log `remote_url`/`auth_token` — Rails masks `password`-ish keys in
+some diagnostics, but these are custom `database.yml` keys, so that masking
+does not cover them automatically. Source them from encrypted credentials or
+`ENV`, as above, and avoid logging/inspecting the raw connection config.
+
+An optional `bootstrap_if_empty:` (default `true`) controls whether a brand
+new/empty local file is populated from the remote on first open — see
+`Beagle::Turso::Database.open`.
+
+### Durability note: writes commit on-sync, not synchronously
+
+Writes go to the **local** file immediately, as part of the normal
+ActiveRecord write path (`INSERT`/`UPDATE`/`DELETE` all commit locally,
+synchronously, like any SQLite-backed adapter). They are only propagated to
+the remote Turso database **on sync** — i.e. whenever something calls
+`push!` (see below) — not automatically after every write or transaction
+commit. Until a sync succeeds, a write that is fully durable on this
+replica's local disk is not yet visible to any other replica of the same
+remote database. Plan your sync cadence (and any read-after-write
+expectations across replicas) around that gap.
+
+## Sync: `Beagle::Turso::SyncManager` + Solid Queue recurring job
+
+`Beagle::Turso::SyncManager` drives push/pull from the ActiveRecord layer,
+given a connection using `adapter: beagle_turso`:
+
+```ruby
+Beagle::Turso::SyncManager.push!(ActiveRecord::Base.connection) # local writes -> remote
+Beagle::Turso::SyncManager.pull!(ActiveRecord::Base.connection) # remote writes -> local
+Beagle::Turso::SyncManager.sync!(ActiveRecord::Base.connection) # push!, then pull!
+```
+
+All three default their `connection` argument to `ActiveRecord::Base.connection`,
+so `Beagle::Turso::SyncManager.sync!` alone is the usual call. Calling any of
+them against a **local-only** connection (no `remote_url:`/`auth_token:` in
+`database.yml`) raises `Beagle::Turso::SyncManager::NotSyncedError` — a
+distinct, rescuable type — rather than the driver's bare `RuntimeError`.
+
+To sync on a timer, wire
+`ActiveRecord::ConnectionAdapters::BeagleTurso::SyncJob` (a thin delegator to
+`SyncManager.sync!`) into [Solid Queue's recurring
+jobs](https://github.com/rails/solid_queue?tab=readme-ov-file#recurring-tasks).
+This gem does not generate or load `config/recurring.yml` itself — copy the
+relevant block from
+[`config/recurring.yml.example`](config/recurring.yml.example) into your
+host app's own `config/recurring.yml`, for whichever environment(s) actually
+use a synced connection:
+
+```yaml
+production:
+  beagle_turso_sync:
+    class: ActiveRecord::ConnectionAdapters::BeagleTurso::SyncJob
+    queue: default
+    schedule: every 30 seconds # match database.yml's sync_interval: for this env
+```
+
+`SyncJob` subclasses `ActiveJob::Base` when ActiveJob is loaded (the normal
+case in a Rails app running Solid Queue) and falls back to a plain class
+with the same `#perform` otherwise, so requiring this gem never raises a
+`LoadError` on its own in a non-Rails context.
+
+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:`.
+
+## Test coverage
+
+This gem's own spec suite (`spec/`, run via `bundle exec rspec`) is 35
+examples covering, against the real `beagle-turso` driver (nothing mocked):
+CRUD through a model, foreign-key enforcement, data-modifying CTEs,
+transactions (commit/rollback/nested `requires_new`), DDL
+(`add_column`/`remove_column`/`change_column`/`add_index`), every AR column
+type round-tripping through a model, `pluck`/`where`/`update_all`/`delete_all`,
+and (with real Turso credentials — otherwise a clean `PENDING` skip, no
+silent pass) a genuine push/pull sync round trip between two replicas.
+
+### Real-Rails-boot integration test
+
+`spec/dummy_app_integration_spec.rb` boots `test/dummy` — a small but
+**genuine** `Rails::Application` (not a mock or a stand-in) — through Rails'
+own `config/environment.rb` → `Rails.application.initialize!` sequence, the
+same path a real app's `bin/rails server`/`bin/rails console`/`bin/rails db:migrate`
+takes. It proves the adapter survives that boot rather than only the
+hand-called `ActiveRecord::Base.establish_connection(adapter: "beagle_turso", ...)`
+the rest of the suite uses:
+
+- `adapter: beagle_turso` is resolved from a real `config/database.yml` by
+  `ActiveRecord::Railtie`'s own `active_record.initialize_database`
+  initializer, not passed as a literal hash.
+- A real `ActiveRecord::Migration` file is run via `ActiveRecord::MigrationContext`
+  (not `ActiveRecord::Schema.define`, which the rest of the suite uses) —
+  this exercises `schema_migrations`/`ar_internal_metadata` bookkeeping,
+  which no other spec in this gem touches.
+- The model under test (`DummyWidget`) is never `require`d by hand — it's
+  resolved through Rails' normal Zeitwerk `app/models` autoloading.
+
+`test/dummy` intentionally boots only the frameworks
+`ActiveRecord::Railtie` itself pulls in (it hard-requires
+`action_controller/railtie`, and transitively `action_view/railtie`, for
+long-standing middleware-configuration reasons — see the comment at the top
+of Rails' `active_record/railtie.rb`) — no Active Job, Action Mailer, Active
+Storage, Action Cable, etc. See `test/dummy/config/application.rb` for the
+exact boot list.
+
+### What's deferred: ActiveRecord's own internal adapter test suite
+
+ActiveRecord ships an extensive internal adapter conformance suite
+(`activerecord/test/cases/*_test.rb` in the [Rails source
+tree](https://github.com/rails/rails/tree/v8.1.3.1/activerecord/test/cases))
+that official adapters (`mysql2`, `pg`, `trilogy`) are exercised against.
+**This gem does not vendor or run that suite, and that is a deliberate,
+documented decision, not a silent gap:**
+
+- That suite is not shipped in the released `activerecord` gem — only in
+  the Rails monorepo's source tree. It is not designed for consumption by
+  external adapter gems.
+- We confirmed this concretely: even a single, relatively adapter-agnostic
+  file from it (`test/cases/adapter_test.rb`) `require`s `cases/helper`,
+  `support/connection_helper`, and several `models/*` fixture classes,
+  which in turn depend on ActiveRecord's internal `ARTest` test harness and
+  its ~1,500-line `test/schema/schema.rb` (dozens of interlocking fixture
+  tables — authors, books, posts, comments, and more) plus a `test/config.yml`
+  whose format/location has itself shifted between Rails versions. None of
+  this is a stable, public interface; vendoring even one file means
+  vendoring most of that infrastructure and keeping it hand-synced with
+  whatever Rails version this gem targets.
+- This is precisely why official third-party adapters handle it by
+  checking out the **entire** Rails source at a pinned commit/tag (often as
+  a CI-only step, sometimes a git submodule) and running AR's suite
+  in-tree against their adapter — a substantial, ongoing-maintenance
+  commitment, not something addable as a "focused subset" inside a single
+  gem release.
+- What that suite covers beyond this gem's own 35 examples: exhaustive
+  per-type edge cases (encoding, precision/scale boundaries, reserved-word
+  quoting across dozens of identifiers), schema-dumping round-trips
+  (`db/schema.rb` load-and-compare), the full fixture-based association
+  graph, and adapter-independent behavior that has nothing to do with the
+  raw-execution seam this adapter actually changes. None of that is
+  exercised here.
+
+If this adapter needs that level of assurance in the future (e.g. before a
+1.0 release, or before proposing it for inclusion upstream), the right next
+step is a separately-scoped effort to vendor the full Rails source at a
+pinned tag and run its adapter suite in CI — not a partial port bolted onto
+this gem.
+
+## Limitations (v1)
+
+1. **Uncast raw/computed SELECT values.** Reads go through `ActiveRecord::Result`
+   without result column types, so ordinary model attributes and `pluck(:column)`
+   cast correctly, but a raw/computed SELECT expression with no backing attribute
+   (e.g. `select_all("SELECT some_datetime_expr ...")`, `pluck(Arel.sql("..."))`)
+   may come back uncast (string / 0/1 instead of Time / boolean). Cast such values
+   yourself.
+
+2. **Data-modifying CTEs and read-replica write-guards.** A hand-written
+   `WITH ... UPDATE/INSERT/DELETE` executes correctly, but is classified as a read
+   by ActiveRecord's write-guard layer — so under `connected_to(role: :reading)` it
+   won't trip the read-only guard, and it won't mark the transaction dirty. Use
+   plain `UPDATE`/`DELETE` (or `Model.update_all`/`delete_all`) if you rely on
+   read/write splitting.
+
+3. **Sync holds the GVL.** `SyncManager.push!`/`pull!` block Ruby's GVL for the
+   full network round-trip. Under `SOLID_QUEUE_IN_PUMA=true` (jobs in the Puma
+   process), a recurring `SyncJob` stalls all Puma threads for the duration of
+   each sync — pick a sync cadence accordingly, or run Solid Queue in a separate
+   process.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT).

data/config/recurring.yml.example

@@ -0,0 +1,22 @@
+# Example Solid Queue recurring-job entry for ActiveRecord::ConnectionAdapters::BeagleTurso::SyncJob.
+#
+# This is NOT loaded by this gem -- copy the relevant environment block(s)
+# into your host Rails app's own config/recurring.yml (Solid Queue reads
+# that file; see the solid_queue README for the full recurring.yml format).
+# Only add this for environments whose database.yml connection is actually
+# synced (has both remote_url: and auth_token: -- see
+# lib/active_record/connection_adapters/beagle_turso/sync_manager.rb). A
+# recurring SyncJob against a local-only connection will fail every run with
+# Beagle::Turso::SyncManager::NotSyncedError.
+#
+# Keep the `schedule:` cadence here in sync (by hand) with whatever
+# `sync_interval:` you documented in database.yml for the same environment --
+# Solid Queue does not read database.yml, so there is no single source of
+# truth to enforce this automatically.
+
+production:
+  beagle_turso_sync:
+    class: ActiveRecord::ConnectionAdapters::BeagleTurso::SyncJob
+    queue: default
+    # Match database.yml's production `sync_interval:` for this connection.
+    schedule: every 30 seconds

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/beagle_turso/sync_manager"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module BeagleTurso
+      # Thin Solid Queue recurring job: on each run, it just delegates to
+      # Beagle::Turso::SyncManager.sync! (push local writes, then pull remote
+      # ones) against the app's default AR connection. No retry/backoff logic
+      # here -- Solid Queue's own job-failure handling covers that, and
+      # SyncManager itself carries no state between runs.
+      #
+      # Wire it up via config/recurring.yml (see
+      # config/recurring.yml.example alongside this file), scheduled at
+      # whatever cadence database.yml's +sync_interval:+ documents for the
+      # target environment. This gem does not read recurring.yml or generate
+      # it -- add the entry to the host app's own file.
+      #
+      # This gem does not declare a hard dependency on `activejob` (a Rails
+      # app using Solid Queue already has it loaded by the time this file is
+      # required). When ActiveJob is present, SyncJob subclasses
+      # ActiveJob::Base as Solid Queue expects; otherwise it falls back to a
+      # plain class with the same #perform, so requiring this file never
+      # raises a LoadError on its own.
+      sync_job_superclass = defined?(::ActiveJob::Base) ? ::ActiveJob::Base : Object
+
+      class SyncJob < sync_job_superclass
+        def perform
+          ::Beagle::Turso::SyncManager.sync!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Beagle
+  module Turso
+    # Drives a synced beagle-turso database's `push`/`pull` from the
+    # ActiveRecord layer, given an AR connection using +adapter: beagle_turso+
+    # (see BeagleTursoAdapter). It is a thin delegator: all the real sync work
+    # -- WAL-frame push/pull against the remote Turso database -- happens in
+    # Beagle::Turso::Database#push/#pull (native, via beagle_turso_core). This
+    # module only reaches +connection.raw_connection+ (the adapter's +Client+,
+    # see BeagleTursoAdapter::Client) and calls through.
+    #
+    # Intended as the callback a Solid Queue recurring job invokes on a timer
+    # (see ActiveRecord::ConnectionAdapters::BeagleTurso::SyncJob) -- not a
+    # sync engine in its own right. It does not schedule itself, retry, queue
+    # writes, or track sync state; scheduling is Solid Queue's job (see
+    # config/recurring.yml.example alongside this file).
+    #
+    # == database.yml keys this depends on
+    #
+    # A connection is "synced" -- i.e. what +push!+/+pull!+ operate on --
+    # only when its +database.yml+ entry carries BOTH of:
+    #
+    #   remote_url:  # the Turso database's libsql:// URL
+    #   auth_token:  # its auth token
+    #
+    # (See BeagleTursoAdapter.new_client.) A third key, +sync_interval:+, is
+    # NOT read by this adapter or by SyncManager -- it exists purely as a
+    # documented convention for how often a host app's config/recurring.yml
+    # should invoke SyncJob; keep the two in sync by hand (or via ERB) since
+    # Solid Queue's recurring.yml is not sourced from database.yml. Example:
+    #
+    #   # config/database.yml
+    #   production:
+    #     adapter: beagle_turso
+    #     database: storage/production.sqlite3
+    #     remote_url: <%= Rails.application.credentials.dig(:turso, :prod_url) %>
+    #     auth_token: <%= Rails.application.credentials.dig(:turso, :prod_token) %>
+    #     sync_interval: 30 # seconds -- informational; wire it into recurring.yml yourself
+    #
+    # Never log +remote_url+/+auth_token+ -- Rails masks +password+-ish keys
+    # in some diagnostics, but these are custom keys, so it doesn't cover them
+    # automatically. Source them from encrypted credentials or ENV (as
+    # BeagleTursoAdapter's callers already do) and don't pass them through
+    # anything that inspects/logs config (e.g. don't log +connection_config+).
+    module SyncManager
+      # Raised by +push!+/+pull!+/+sync!+ when the given connection is
+      # local-only (its database.yml entry has no +remote_url+/+auth_token+,
+      # so BeagleTursoAdapter opened it via +Database.open_local+). The
+      # underlying Client#push/#pull already raise a bare RuntimeError for
+      # this (see Beagle::Turso::Database#push/#pull); SyncManager re-raises
+      # it as this distinct, documented type so callers can rescue it
+      # specifically instead of matching on the driver's message text. A
+      # genuine sync failure against a real remote (network error, auth
+      # failure, etc.) is NOT reclassified -- it propagates as whatever error
+      # the driver raised, unchanged.
+      class NotSyncedError < StandardError; end
+
+      # Matches only the driver's local-only wording (see
+      # beagle_turso_core's `Error::Sync` in `Database::push`/`Database::pull`)
+      # so a real sync failure -- which also surfaces as a RuntimeError, just
+      # with different text -- is never misreported as "not synced".
+      LOCAL_ONLY_MESSAGE_REGEX = /on a local-only database/i
+      private_constant :LOCAL_ONLY_MESSAGE_REGEX
+
+      module_function
+
+      # Push this connection's local writes to its remote Turso database.
+      def push!(connection = ActiveRecord::Base.connection)
+        reraise_local_only { connection.raw_connection.push }
+      end
+
+      # Pull remote writes down into this connection's local replica.
+      # Returns the driver's own true/false (whether anything changed).
+      def pull!(connection = ActiveRecord::Base.connection)
+        reraise_local_only { connection.raw_connection.pull }
+      end
+
+      # Push, then pull. Pushing first means this replica's own writes reach
+      # the remote before it re-syncs down, so afterwards this connection is
+      # caught up with both its own writes (now durable remotely) and
+      # whatever else landed on the remote from other replicas. Call push!
+      # or pull! directly when only one direction is wanted.
+      def sync!(connection = ActiveRecord::Base.connection)
+        push!(connection)
+        pull!(connection)
+      end
+
+      def reraise_local_only
+        yield
+      rescue RuntimeError => e
+        raise e unless LOCAL_ONLY_MESSAGE_REGEX.match?(e.message)
+
+        raise NotSyncedError,
+          "#{e.message} -- this connection is local-only; configure remote_url: " \
+          "and auth_token: in database.yml to enable sync"
+      end
+      private_class_method :reraise_local_only
+    end
+  end
+end

data/lib/active_record/connection_adapters/beagle_turso_adapter.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_record/connection_adapters/sqlite3_adapter"
+require "beagle/turso"
+
+module ActiveRecord
+  module ConnectionAdapters
+    # = ActiveRecord Beagle Turso Adapter
+    #
+    # Subclasses the stock SQLite3Adapter and reroutes only its raw-execution
+    # seam (+perform_query+) onto a beagle-turso Connection. beagle-turso is a
+    # libsql/Turso driver: it speaks a SQLite-compatible dialect but has its own
+    # native handle rather than the +sqlite3+ gem's +::SQLite3::Database+.
+    #
+    # Everything ActiveRecord relies on above the raw connection -- SQL
+    # generation, quoting, schema introspection (PRAGMA table_xinfo,
+    # sqlite_master), type mapping, transactions -- is inherited unchanged from
+    # SQLite3Adapter. We swap out:
+    #
+    #   * +new_client+ / +connect+   : open a Beagle::Turso::Database instead of a
+    #     ::SQLite3::Database, wrapped in a Client that answers the handful of
+    #     lifecycle/pragma messages the SQLite3Adapter sends a raw connection.
+    #   * +configure_connection+     : re-assert `PRAGMA foreign_keys = ON` through
+    #     the real exec path, because the stock DEFAULT_PRAGMA setter is a no-op on
+    #     our Client (SQLite defaults FKs OFF per-connection).
+    #   * +perform_query+            : the single method every query flows through
+    #     (see AbstractAdapter#raw_execute). Reads/RETURNING -> ActiveRecord::Result
+    #     with columns+rows; writes (incl. data-modifying CTEs) -> affected-row
+    #     count + last_insert_rowid.
+    #   * +last_inserted_id+         : fall back to last_insert_rowid when a plain
+    #     INSERT (no RETURNING) was used.
+    class BeagleTursoAdapter < SQLite3Adapter
+      ADAPTER_NAME = "BeagleTurso"
+
+      # A RETURNING clause makes any write yield rows, so it routes to the read
+      # (query_result) branch.
+      RETURNING_REGEX = /\bRETURNING\b/i
+      private_constant :RETURNING_REGEX
+
+      # A data-modifying CTE: a leading WITH whose *main* statement -- the token
+      # right after the CTE definition list's closing paren -- is INSERT / UPDATE
+      # / DELETE. AR's write_query? classifies any leading WITH as a READ, so
+      # without this such writes would be routed to query_result: the change still
+      # persists, but the affected-row count comes back nil and a CTE-INSERT's
+      # rowid is lost. The `\)\s*` anchor is deliberate -- it keeps `WITH ... SELECT`
+      # reads (and DML keywords that appear inside string literals or identifiers)
+      # from being misclassified as writes.
+      #
+      # Residual limitation: this is a heuristic, not a full SQL parse. A
+      # data-modifying CTE whose main verb is not immediately preceded by the CTE
+      # list's closing `)` (extremely unusual) could be missed, and a read CTE
+      # containing the literal text `) UPDATE`/`) INSERT`/`) DELETE` could be
+      # mis-routed. The read branch also re-captures last_insert_rowid whenever the
+      # SQL mentions INSERT, so an inserted id is never silently lost even on a miss.
+      DATA_MODIFYING_CTE_REGEX = /\A\s*WITH\b[\s\S]*\)\s*(?:INSERT|UPDATE|DELETE)\b/i
+      private_constant :DATA_MODIFYING_CTE_REGEX
+
+      INSERT_REGEX = /\bINSERT\b/i
+      private_constant :INSERT_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
+        # can drive it as a raw connection.
+        def new_client(config)
+          database =
+            if config[:remote_url]
+              Beagle::Turso::Database.open(
+                local_path: config[:database].to_s,
+                remote_url: config[:remote_url],
+                auth_token: config[:auth_token],
+                bootstrap_if_empty: config.fetch(:bootstrap_if_empty, true)
+              )
+            else
+              Beagle::Turso::Database.open_local(config[:database].to_s)
+            end
+          Client.new(database)
+        end
+      end
+
+      # Adapts a Beagle::Turso::Database + its connected Connection to the subset
+      # of the +sqlite3+ gem's Database surface that SQLite3Adapter pokes at.
+      #
+      # The execution methods (+query_result+, +execute+, +execute_batch+,
+      # +last_insert_rowid+) are the real work. The rest are shims: the adapter's
+      # +configure_connection+ sets PRAGMAs via +raw_connection.foo = value+ and
+      # calls a couple of sqlite3-specific lifecycle methods that libsql neither
+      # needs nor supports; we accept and no-op those so connect/configure runs
+      # cleanly.
+      class Client
+        attr_reader :database, :connection
+
+        def initialize(database)
+          @database   = database
+          @connection = database.connect
+          @closed     = false
+        end
+
+        # A bare read of exactly +defer_foreign_keys+ or +read_uncommitted+
+        # (no `=`) -- how SQLite3Adapter's DDL and transaction-isolation code
+        # reads their state back (e.g. +disable_referential_integrity+'s
+        # `query_value("PRAGMA defer_foreign_keys")`, used by every
+        # alter_table-based schema change: add_column/remove_column/
+        # change_column/etc). libsql/turso does not track queryable state for
+        # either of these two specific pragmas -- reading them back yields an
+        # empty result set instead of a value, even right after being set.
+        # An empty result makes `query_value` return nil, which the caller
+        # then interpolates into a follow-up statement
+        # (`"PRAGMA defer_foreign_keys = #{nil}"`) -> invalid SQL ("incomplete
+        # input"). Both default to OFF/0 per SQLite's docs, and this driver
+        # has no way to report a truer answer, so synthesize that default --
+        # exactly analogous to the FK-enforcement bridge in
+        # +configure_connection+.
+        #
+        # Deliberately NOT a generic `PRAGMA \w+` allowlist: `PRAGMA
+        # foreign_key_check` is also a bare, argument-less pragma read (via
+        # SQLite3Adapter#check_all_foreign_keys_valid!), but for it an EMPTY
+        # result is the *correct*, meaningful answer ("no FK violations") --
+        # synthesizing a fake row for it would make check_all_foreign_keys_valid!
+        # (called by ActiveRecord::FixtureSet when
+        # verify_foreign_keys_for_fixtures is on -- the Rails 7.1+ app-generator
+        # default) raise a false-positive "Foreign key violations found:" on
+        # perfectly clean data. Scoping the match to only the two pragmas
+        # actually root-caused here means any other bare pragma (including
+        # foreign_key_check) falls through to the real driver result instead
+        # of a synthesized one -- failing loudly on a genuine future gap
+        # rather than silently lying.
+        BARE_PRAGMA_READ_REGEX = /\A\s*PRAGMA\s+(defer_foreign_keys|read_uncommitted)\s*\z/i
+        private_constant :BARE_PRAGMA_READ_REGEX
+
+        # --- execution surface used by BeagleTursoAdapter#perform_query ---
+        def query_result(sql, params)
+          columns, rows = connection.query_result(sql, params)
+          if columns.empty? && rows.empty? && (match = BARE_PRAGMA_READ_REGEX.match(sql))
+            [[match[1]], [[0]]]
+          else
+            [columns, rows]
+          end
+        end
+
+        def execute(sql, params)      = connection.execute(sql, params)
+        def execute_batch(sql)        = connection.execute_batch(sql)
+        def last_insert_rowid         = connection.last_insert_rowid
+
+        # --- sync passthrough (Database-level) ---
+        def push = database.push
+        def pull = database.pull
+
+        # --- sqlite3-gem lifecycle shims the SQLite3Adapter drives ---
+        # configure_connection only touches this when config[:timeout] is set.
+        def busy_handler_timeout=(_)
+          nil
+        end
+        # connected? => !(@raw_connection.nil? || @raw_connection.closed?)
+        def closed? = @closed
+        # Release the beagle-turso session eagerly rather than waiting for GC.
+        # A *synced* Database holds a server-side sync session open; without an
+        # explicit close each ActiveRecord disconnect/reconnect (e.g.
+        # verify!/db:prepare) leaked one, accumulating on the remote until it
+        # reported "database is busy". Close the connection first, then the
+        # database (which ends the sync session). Idempotent.
+        #
+        # @closed is only flipped true AFTER both closes have run: if
+        # @connection.close raised and we had set @closed up front, the ensure'd
+        # @database.close would be skipped yet closed? would already report true
+        # -- the session would leak silently (SQLite3Adapter#disconnect! swallows
+        # the exception). The ensure guarantees the database (session) close runs
+        # even if the connection close raises, and @closed reflects reality.
+        def close
+          return if @closed
+          begin
+            @connection.close
+          ensure
+            @database.close
+            @closed = true
+          end
+        end
+        # SQLite3Adapter#reconnect calls this when reusing a live connection.
+        def rollback = execute("ROLLBACK", [])
+
+        # configure_connection applies DEFAULT_PRAGMAS via `raw_connection.foo = v`.
+        # libsql manages journalling/locking itself, so accept and ignore them.
+        def method_missing(name, *args)
+          name.to_s.end_with?("=") ? nil : super
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          name.to_s.end_with?("=") || super
+        end
+      end
+
+      private
+        # The single seam. AbstractAdapter#raw_execute funnels every statement
+        # here and expects an ActiveRecord::Result back, with the notification
+        # payload's affected_rows/row_count filled in. cast_result (inherited)
+        # returns the Result untouched and affected_rows (inherited) reads
+        # 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 || []
+
+          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)
+            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)
+              ::ActiveRecord::Result.new(columns, rows)
+            end
+
+          verified!
+          notification_payload[:affected_rows] = result.affected_rows
+          notification_payload[:row_count]     = result.length
+          result
+        end
+
+        # Route to the WRITE branch (execute -> affected count + last_insert_rowid)
+        # rather than the read branch. A statement is a write when SQLite3's own
+        # read/write classifier says so, OR when it is a data-modifying CTE that
+        # the classifier misreads as a read (see DATA_MODIFYING_CTE_REGEX). A
+        # RETURNING clause always yields rows, so it goes to the read branch even
+        # 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)
+          write_query?(sql) || data_modifying_cte?(sql)
+        end
+
+        def data_modifying_cte?(sql)
+          DATA_MODIFYING_CTE_REGEX.match?(sql)
+        end
+
+        # For INSERT ... RETURNING "id" the id arrives in the result rows (super).
+        # For a plain INSERT (RETURNING unsupported) the result is empty, so fall
+        # back to the rowid captured in perform_query's write branch.
+        def last_inserted_id(result)
+          super || @last_inserted_rowid
+        end
+
+        # Open the beagle-turso connection. Mirrors SQLite3Adapter#connect but
+        # without its ::SQLite3-specific ConnectionNotEstablished rescue.
+        def connect
+          @raw_connection = self.class.new_client(@connection_parameters)
+        end
+
+        # SQLite disables foreign keys per-connection by default; stock
+        # SQLite3Adapter turns them on via `raw_connection.foreign_keys = true`
+        # (a DEFAULT_PRAGMA setter). On our Client that setter is a swallowed
+        # no-op, so FK enforcement would silently be OFF -- a regression vs the
+        # stock adapter. Re-assert it here through the real exec path.
+        #
+        # `super` still runs (check_version + the other DEFAULT_PRAGMA setters);
+        # journal_mode/synchronous/mmap_size are moot for in-memory and remote
+        # libsql, so leaving those as no-ops is fine.
+        def configure_connection
+          super
+          @raw_connection.execute("PRAGMA foreign_keys = ON", [])
+        end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters.register(
+  "beagle_turso",
+  "ActiveRecord::ConnectionAdapters::BeagleTursoAdapter",
+  "active_record/connection_adapters/beagle_turso_adapter"
+)

data/lib/activerecord/beagle_turso/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module BeagleTurso
+    VERSION = "0.1.0"
+  end
+end

data/lib/activerecord-beagle-turso.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+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"

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-beagle-turso
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- BeagleSoftwareUK
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: beagle-turso
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: |
+  An ActiveRecord connection adapter for Turso's libsql engine. It subclasses
+  the stock SQLite3Adapter and reroutes only the raw-execution seam onto the
+  beagle-turso native driver, so schema migrations and model CRUD run against
+  a local, in-memory, or synced remote Turso database while inheriting
+  SQLite3Adapter's SQL generation, quoting, and schema introspection.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- config/recurring.yml.example
+- 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
+- lib/activerecord-beagle-turso.rb
+- lib/activerecord/beagle_turso/version.rb
+homepage: https://github.com/BeagleSoftwareUK/beagle-turso
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/BeagleSoftwareUK/beagle-turso
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: ActiveRecord adapter for Turso, backed by the beagle-turso driver.
+test_files: []