sequel-beagle-turso 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 306f254c2d0518ae7d6a078c338d81caa68a96fe2bed3864af6f69fe7fdf1918
+  data.tar.gz: 60f7e413c5d21e7bbff28b09d99239029248104d98aef821ae7d5cb6c07267f4
+SHA512:
+  metadata.gz: b890a9ad4fb5741b545e116f1a74af5a105526c1abcce1977924a7099abad3557e4277713473b6bef8eb0f6a6cb71a55447352ab7f7676408b9c572f324cdb72
+  data.tar.gz: d864638062b76ed2d885f1fdbef74ad3f76eb4c258c0cca0a6156c5181825f398949123bb7866d351e216b53c1e7791b764c51a13097c5745a6d702c0b31f2eb

data/README.md

@@ -0,0 +1,222 @@
+# sequel-beagle-turso
+
+A [Sequel](https://sequel.jeremyevans.net) adapter for the
+[`beagle-turso`](../beagle-turso) driver, so Sequel, [ROM](https://rom-rb.org)
+and [Hanami](https://hanamirb.org) can run on [Turso](https://turso.tech)'s new
+engine: a local SQLite-compatible replica that syncs to Turso Cloud.
+
+SQL generation, schema parsing and transactions come from Sequel's shared
+SQLite support. The adapter replaces the plumbing (connections, execution,
+value conversion) and works around the engine's differences from SQLite.
+
+## Install
+
+```ruby
+# Gemfile
+gem "sequel-beagle-turso", "~> 0.1"
+```
+
+Sequel loads the adapter lazily the first time you connect to a
+`beagle-turso://` URL or pass `adapter: :beagle_turso`. To load it yourself,
+`require "sequel-beagle-turso"`.
+
+## Connect
+
+```ruby
+require "sequel"
+
+DB = Sequel.connect("beagle-turso:///abs/path/app.db")  # absolute path
+DB = Sequel.connect("beagle-turso://./app.db")          # relative path
+DB = Sequel.connect("beagle-turso:/")                   # in memory
+DB = Sequel.connect(adapter: :beagle_turso, database: "app.db")
+```
+
+**A synced replica.** Pass `remote_url:` and `auth_token:` as options, never in
+the URL. A URL carrying `auth_token` raises, because URLs end up in logs:
+
+```ruby
+DB = Sequel.connect(
+  "beagle-turso:///abs/path/app.db",
+  remote_url: ENV.fetch("TURSO_DATABASE_URL"),
+  auth_token: ENV.fetch("TURSO_AUTH_TOKEN")
+)
+```
+
+The adapter removes `auth_token` from the `Database`'s options once the replica
+is open. Push and pull go through the replica: `DB.turso_database.push` and
+`DB.turso_database.pull`. See the
+[driver README](../beagle-turso#readme) for the durability model, and for which
+Turso database to use.
+
+**Sharing a replica.** If you already have an open `Beagle::Turso::Database`,
+pass it as `turso_database:` and the `Database` uses it instead of opening one.
+The adapter never closes a replica it was handed.
+
+**Closing.** `DB.disconnect` closes the pooled connections and leaves the
+replica open. `DB.close_replica` disconnects, then closes the replica that this
+`Database` opened. A synced replica is held by one OS process at a time, so
+close it before something else needs the file.
+
+Other options: `timeout:` (ms, default 5000, see Writes), `transaction_mode:`,
+and `bootstrap_if_empty:` (passed to the driver).
+
+## Hanami and ROM
+
+```ruby
+Hanami.app.configure_provider :db do
+  config.gateway(:default) do |gw|
+    gw.database_url = "beagle-turso://#{Hanami.app.root.join("db/app.db")}"
+    gw.connection_options(remote_url: ENV["TURSO_DATABASE_URL"], auth_token: ENV["TURSO_AUTH_TOKEN"])
+  end
+end
+```
+
+- ROM's gateway keeps its own copy of the connection options. The adapter
+  scrubs the token from the `Database` it builds, but not from that copy, so
+  don't log the gateway's options.
+- The `hanami db` commands don't support the `beagle-turso` scheme. Run
+  migrations through `ROM::SQL::Migration::Migrator` on the app's gateway, with
+  the server stopped (a synced replica is held by one process).
+
+## Writes
+
+The engine allows one writer at a time and reports contention immediately.
+
+- Outside a transaction, and at `BEGIN`, the adapter waits in Ruby (with
+  backoff) for up to `timeout:` ms (default 5000), then raises
+  `Sequel::DatabaseLockTimeout`.
+- Explicit transactions use `BEGIN IMMEDIATE`, so a transaction waits for the
+  write lock at its start instead of failing partway. `transaction_mode:`
+  (`:deferred`, `:immediate`, `:exclusive`) changes the default, and
+  `db.transaction(mode: ...)` overrides it per transaction.
+- Inside a transaction, contention surfaces as an error (and the transaction
+  rolls back) instead of being retried.
+- Don't set `PRAGMA busy_timeout`. Its wait holds the GVL, so the writer that
+  holds the lock can't commit.
+- Because of `BEGIN IMMEDIATE`, read-only `db.transaction { }` blocks and
+  `Dataset#paged_each` take the write lock and queue behind writers. Pass
+  `mode: :deferred` for read-only transactions.
+- Statements run inside a manual `db.run("BEGIN")` aren't seen as a transaction
+  by Sequel, so they get the autocommit busy retry. Use `db.transaction`.
+- A `db.run` with several statements (`"INSERT ...; INSERT ..."`) is never
+  retried, since a retry could re-run a statement that already committed. If
+  the write lock is taken it raises `Sequel::DatabaseLockTimeout` at once, and
+  statements before the failing one may already be committed. Run statements
+  one at a time, or in a `db.transaction`. (A `;` inside a string literal also
+  counts as a second statement.)
+
+**Pool size.** The engine allows many connections (32 and more) to one
+replica, but only one writer at a time. `max_connections` defaults to 4. Under
+write-heavy load a smaller pool makes writers queue in Sequel's pool rather
+than busy-retry against each other. An in-memory database defaults to one
+connection.
+
+## Fork (Puma, Unicorn, forking job runners)
+
+A replica belongs to the process that opened it. After `fork`, the child's
+inherited pooled connections raise `Sequel::DatabaseDisconnectError` and are
+dropped, and opening new ones raises `Sequel::DatabaseConnectionError`
+(`Beagle::Turso::ForkedError`). `DB.disconnect` before forking is not enough,
+because the replica itself can't cross the fork. Create the `Sequel::Database`
+in each process after it forks (for Puma, in `on_worker_boot`), and don't open
+it in the parent. A replica file is locked by one process at a time, so give
+each process its own replica file.
+
+## Falcon and fibers
+
+Call `Sequel.extension :fiber_concurrency` before connecting, so the pool hands
+out connections per fiber rather than per thread. The driver README's
+[Threads, fibers and fork](../beagle-turso#threads-fibers-and-fork) section
+covers the GVL and Falcon notes, including what runs on Ruby 3.3 and 4.0.
+
+## Limitations
+
+- The sync engine's own tables (`turso_cdc`, `turso_cdc_version`,
+  `turso_sync_last_change_id`) are hidden from `tables` and `views`, so cleaners
+  and schema dumpers can't truncate the change log.
+- The engine doesn't support generated columns, `WITHOUT ROWID` tables, fts5 or
+  `ATTACH`.
+- Declared-type arguments (`varchar(255)`, `numeric(12,0)`) aren't reported by
+  the engine, so `schema` has no `:max_length` for string columns.
+- `LIKE` is always case-insensitive: the engine ignores
+  `PRAGMA case_sensitive_like`.
+- `alter_table` operations that rebuild the table fail, and roll back cleanly,
+  if another table's trigger references the rebuilt table.
+- Dropping a self-referencing table that has rows works outside a transaction
+  only (the adapter retries with foreign keys off). Inside a transaction it
+  raises.
+- **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`, `UPDATE` or `DROP` 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.
+
+- **Known engine issue: insert ids on MVCC replicas.** On a replica in MVCC
+  journal mode with change data capture on (every synced replica of a
+  `--tursodb` remote), `last_insert_rowid` returns the change-log id, not the
+  inserted row's rowid
+  ([tursodatabase/turso#9551](https://github.com/tursodatabase/turso/issues/9551)).
+  The adapter doesn't use it: `Dataset#insert` appends `RETURNING rowid` to the
+  statement and returns the last row's rowid (`nil` if nothing was inserted,
+  such as `insert_ignore` hitting a duplicate), so ids are correct everywhere.
+  Code that calls the driver's `last_insert_rowid` itself is still affected.
+- **`rename_table` is refused on synced replicas.** The sync engine doesn't
+  capture `ALTER TABLE ... RENAME TO` or `RENAME COLUMN` for sync, so the remote
+  never sees the rename and later writes to the table are lost on push. When
+  `turso_database.synced?`, `rename_table` raises `Sequel::Error`. Local-only
+  replicas are unaffected. Workaround: create the new table, copy the rows and
+  drop the old one, or run the rename against the remote database directly.
+- **Table rebuilds avoid `RENAME`.** Operations that rebuild a table
+  (`set_column_type`, `set_column_allow_null`, `set_column_default`, constraint
+  changes, adding a unique column) copy the rows to a backup table, drop and
+  recreate the table, copy back and drop the backup, so nothing is renamed. On
+  a synced replica `drop_column` and `rename_column` go through the same
+  rebuild too (the native `DROP COLUMN` loses unpushed rows, and
+  `RENAME COLUMN` isn't synced). Rebuilds therefore copy the data twice, and
+  **the first push after a rebuild on a synced replica raises a `SyncError`
+  once; push again and the data converges** (`Syncer` logs it once and
+  retries). Rebuilds (Sequel's stock ones too) have these limits:
+  - triggers on the table are lost;
+  - the `AUTOINCREMENT` counter restarts from the current max id, so a deleted
+    top id can be reused;
+  - partial indexes are not recreated;
+  - a column's `COLLATE` is dropped;
+  - a foreign key's `DEFERRABLE` is dropped (the engine doesn't report it).
+
+  On a synced replica, `rename_column` also keeps the table's own foreign keys
+  (re-added with the new column name, self-references included), but it is
+  refused when another table's foreign key references the column: the rebuild
+  can't update that reference, and both tables would become unwritable. Rebuild
+  the referencing table as well, or apply the rename on the remote and pull.
+  `drop_column` of a foreign key column drops that foreign key with it.
+- **Insert return values.** `Dataset#insert` returns the last inserted row's
+  rowid. An `ON CONFLICT DO UPDATE` upsert returns the updated row's rowid, and
+  an insert that is ignored (`insert_ignore`, `ON CONFLICT DO NOTHING`) returns
+  `nil`; SQLite's `last_insert_rowid` would return a stale value there.
+
+The full list of Sequel integration tests excluded for engine gaps, with a
+reason for each, is in
+[`spec/integration_known_failures.txt`](spec/integration_known_failures.txt).
+
+## Testing
+
+```bash
+bundle exec rspec            # the adapter's own specs, including a ROM smoke test
+script/sequel-integration    # Sequel's own integration suite
+```
+
+`script/sequel-integration` clones the Sequel release matching the installed
+version, runs its `spec/integration` suite against this adapter and excludes the
+tests in `spec/integration_known_failures.txt` by exact name. The remote specs
+need `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` for a dedicated test database,
+and skip cleanly without them.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT).

data/lib/sequel/adapters/beagle-turso.rb

@@ -0,0 +1,4 @@
+# Sequel loads an adapter by requiring "sequel/adapters/<url scheme>". URI
+# schemes cannot contain "_", so the URL form is beagle-turso:// and this file
+# exists only so that lookup finds the adapter.
+require_relative "beagle_turso"

data/lib/sequel/adapters/beagle_turso.rb

@@ -0,0 +1,628 @@
+require "beagle/turso"
+require "bigdecimal"
+require "sequel/adapters/shared/sqlite"
+
+module Sequel
+  # Sequel adapter for the beagle-turso driver. SQL generation, schema parsing
+  # and transactions come from Sequel's shared SQLite support; this file only
+  # replaces the plumbing (connections, execution, value conversion) and
+  # papers over the engine's differences from SQLite.
+  module BeagleTurso
+    FALSE_VALUES = (%w[0 false f no n].each(&:freeze) + [0]).freeze
+
+    blob = Object.new
+    def blob.call(s)
+      Sequel::SQL::Blob.new(s.to_s)
+    end
+
+    boolean = Object.new
+    def boolean.call(s)
+      s = s.downcase if s.is_a?(String)
+      !FALSE_VALUES.include?(s)
+    end
+
+    date = Object.new
+    def date.call(s)
+      case s
+      when String then Sequel.string_to_date(s)
+      when Integer then Date.jd(s)
+      when Float then Date.jd(s.to_i)
+      else raise Sequel::Error, "unhandled type when converting to date: #{s.inspect} (#{s.class.inspect})"
+      end
+    end
+
+    integer = Object.new
+    def integer.call(s)
+      s.to_i
+    end
+
+    float = Object.new
+    def float.call(s)
+      s.to_f
+    end
+
+    numeric = Object.new
+    def numeric.call(s)
+      s = s.to_s unless s.is_a?(String)
+      BigDecimal(s)
+    rescue ArgumentError
+      s
+    end
+
+    time = Object.new
+    def time.call(s)
+      case s
+      when String then Sequel.string_to_time(s)
+      when Integer then Sequel::SQLTime.create(s / 3600, (s % 3600) / 60, s % 60)
+      when Float
+        secs, frac = s.divmod(1)
+        Sequel::SQLTime.create(secs / 3600, (secs % 3600) / 60, secs % 60, (frac * 1_000_000).round)
+      else raise Sequel::Error, "unhandled type when converting to time: #{s.inspect} (#{s.class.inspect})"
+      end
+    end
+
+    # Declared base type name (lowercase) -> converter. datetime/timestamp are
+    # added per Database so Sequel's timezone settings apply.
+    SQLITE_TYPES = {}
+    {
+      %w[date] => date,
+      %w[time] => time,
+      %w[bit bool boolean] => boolean,
+      %w[integer smallint mediumint int bigint] => integer,
+      %w[numeric decimal money] => numeric,
+      %w[float double real dec fixed] + ["double precision"] => float,
+      %w[blob] => blob
+    }.each { |names, conv| names.each { |n| SQLITE_TYPES[n] = conv } }
+    SQLITE_TYPES.freeze
+
+    # Thread-safe retry count. Lives in an ivar of the Database, and a frozen
+    # Database must still be able to count, so it can't be a plain Integer.
+    class BusyCounter
+      def initialize
+        @mutex = Mutex.new
+        @value = 0
+      end
+
+      def increment
+        @mutex.synchronize { @value += 1 }
+      end
+
+      def value
+        @mutex.synchronize { @value }
+      end
+    end
+    private_constant :BusyCounter
+
+    class Database < Sequel::Database
+      include Sequel::SQLite::DatabaseMethods
+
+      # The driver prefixes engine messages ("query failed: ..."); Sequel's
+      # SQLite error regexps (some anchored at \A) expect the bare message.
+      ENGINE_PREFIX = /\A(?:open failed|connect failed|query failed|sync failed|database is busy): /
+
+      # Tables the Turso sync engine creates on a synced replica; never user tables.
+      SYNC_ENGINE_TABLES = %w[turso_cdc turso_cdc_version turso_sync_last_change_id].freeze
+
+      RETURNING_CLAUSE = /\bRETURNING\b/i
+
+      # String literals, quoted identifiers, and comments: where the word
+      # RETURNING is data, not syntax.
+      NON_CODE = %r{'(?:[^']|'')*'|"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]|--[^\n]*|/\*.*?\*/}m
+
+      set_adapter_scheme :beagle_turso
+      # The URL form: URI schemes can't contain "_" (see adapters/beagle-turso.rb).
+      Sequel::ADAPTER_MAP[:"beagle-turso"] = self
+
+      # Same path handling as Sequel's sqlite adapter: beagle-turso:///abs.db,
+      # beagle-turso://./rel.db, beagle-turso:/ (memory).
+      def self.uri_to_options(uri)
+        database = if uri.host.nil?
+          case uri.path
+          when "/" then nil
+          when nil then uri.opaque
+          else uri.path
+          end
+        else
+          "#{uri.host}#{uri.path}"
+        end
+        { database: database }
+      end
+      private_class_method :uri_to_options
+
+      attr_reader :conversion_procs, :turso_database
+
+      # One pooled connection. The replica itself is opened once, in
+      # adapter_initialize, and shared by every connection.
+      def connect(_server)
+        conn = @turso_database.connect
+        connection_pragmas.each { |s| log_connection_yield(s, conn) { conn.execute_batch(s) } }
+        conn
+      rescue Beagle::Turso::Error => e
+        raise Sequel.convert_exception_class(e, Sequel::DatabaseConnectionError)
+      end
+
+      def disconnect_connection(conn)
+        conn.close
+      end
+
+      # Closes pooled connections and the replica this Database opened. A
+      # replica passed in as turso_database: belongs to the caller and is left
+      # open. Idempotent.
+      def close_replica
+        disconnect
+        @turso_database.close if @owns_turso_database && !@turso_database.closed?
+        nil
+      end
+
+      # Row-returning SQL. Yields (and returns) [columns, decl_types, rows].
+      def execute(sql, opts = OPTS)
+        result = _execute(sql, opts) { |conn| conn.query_result_with_types(sql, []) }
+        yield result if defined?(yield)
+        result
+      end
+
+      def execute_dui(sql, opts = OPTS)
+        _execute(sql, opts) { |conn| conn.execute(sql, []) }
+      end
+
+      # execute_batch runs every statement in sql. Retrying a batch after a
+      # busy error could re-run a statement that already committed, so only a
+      # single statement gets the busy retry; a batch runs once.
+      def execute_ddl(sql, opts = OPTS)
+        _execute(sql, opts, busy_retry: single_statement?(sql)) { |conn| conn.execute_batch(sql) }
+        nil
+      end
+
+      # Returns the rowid of the last row inserted, or nil if none was.
+      #
+      # Not conn.last_insert_rowid: on a replica in MVCC journal mode with
+      # change data capture on (every synced replica of a --tursodb remote)
+      # the engine leaves the CDC change id there, so it is wrong
+      # (tursodatabase/turso#9551). INSERT ... RETURNING is correct, so the
+      # statement gets RETURNING rowid appended. rowid always exists: the
+      # engine has no WITHOUT ROWID tables. Several rows (INSERT ... SELECT,
+      # multi-row VALUES) return the last one, like SQLite's
+      # last_insert_rowid; an insert that changed nothing (OR IGNORE, ON
+      # CONFLICT DO NOTHING) returns nil. The logged SQL is the original. RETURNING
+      # goes on its own line so a trailing -- comment (sql_comments) can't swallow it.
+      #
+      # An insert that already has RETURNING is run as is, and its first
+      # column in the last row is the result. (Dataset#insert sends those
+      # through fetch, and insert_select too, not through here.)
+      #
+      # Note: insert(select_ds) / INSERT ... SELECT materialises every
+      # returned rowid just to take the last one.
+      def execute_insert(sql, opts = OPTS)
+        run_sql = with_returning_rowid(sql)
+        _execute(sql, opts) do |conn|
+          _, _, rows = conn.query_result_with_types(run_sql, [])
+          rows.last&.first
+        end
+      end
+
+      # SQLite stores timestamps as text, integers (unix time) or reals (julian day).
+      def to_application_timestamp(s)
+        case s
+        when String then super
+        when Integer then super(Time.at(s).to_s)
+        when Float then super(DateTime.jd(s).to_s)
+        else raise Sequel::Error, "unhandled type when converting to timestamp: #{s.inspect} (#{s.class.inspect})"
+        end
+      end
+
+      # The engine checks a table's self-references row by row when dropping
+      # it, so a self-referencing table with rows can't be dropped while
+      # foreign keys are on (SQLite drops it). When nothing else could be
+      # referencing the rows, drop it with foreign keys briefly off.
+      def drop_table(*names)
+        opts = names.last.is_a?(Hash) ? names.pop : OPTS
+        names.each do |name|
+          super(name, opts)
+        rescue ForeignKeyConstraintViolation
+          raise unless drop_self_referencing_table(name, opts)
+        end
+        nil
+      end
+
+      # Refused on a synced replica, see refuse_rename_when_synced.
+      def rename_table(name, new_name)
+        refuse_rename_when_synced("rename_table")
+        super
+      end
+
+      # Sequel's check sends SELECT NULL through connection_execute_method
+      # (execute_batch), which rejects any statement that returns a row.
+      def valid_connection?(conn)
+        sql = valid_connection_sql
+        log_connection_yield(sql, conn) { conn.query(sql, []) }
+        true
+      rescue Sequel::DatabaseError, *database_error_classes
+        false
+      end
+
+      def freeze
+        @conversion_procs.freeze
+        super
+      end
+
+      private
+
+      # True if it dropped the table. PRAGMA foreign_keys is per connection and
+      # ignored inside a transaction, so this needs to own the connection.
+      def drop_self_referencing_table(name, opts)
+        synchronize(opts[:server]) do |conn|
+          return false if _trans(conn) || !self_referencing_only?(name)
+
+          execute_ddl("PRAGMA foreign_keys = 0", opts)
+          begin
+            execute_ddl(drop_table_sql(name, opts), opts)
+          ensure
+            execute_ddl("PRAGMA foreign_keys = 1", opts)
+          end
+          remove_cached_schema(name)
+          true
+        end
+      end
+
+      # The table references itself, and no other table with rows references it.
+      def self_referencing_only?(name)
+        table = name.to_s
+        return false unless foreign_key_list(name).any? { |fk| fk[:table].to_s == table }
+
+        tables.reject { |t| t.to_s == table }.none? do |other|
+          foreign_key_list(other).any? { |fk| fk[:table].to_s == table } && !from(other).empty?
+        end
+      end
+
+      def adapter_initialize
+        @conversion_procs = SQLITE_TYPES.dup
+        @conversion_procs["datetime"] = @conversion_procs["timestamp"] = method(:to_application_timestamp)
+        set_integer_booleans
+        reject_url_credentials
+        # The engine allows one writer and reports contention immediately; we
+        # wait in Ruby (see retry_busy), never with PRAGMA busy_timeout, whose
+        # wait holds the GVL so the lock holder can't commit.
+        @busy_retries = BusyCounter.new
+        @busy_timeout = typecast_value_integer(@opts.fetch(:timeout, 5000)) / 1000.0
+        # Take the write lock at BEGIN, so a transaction that can't get it
+        # waits there instead of failing mid-way.
+        self.transaction_mode = (@opts[:transaction_mode] || :immediate).to_sym
+        @turso_database, @owns_turso_database = open_turso_database
+        scrub_credentials
+        sqlite_version # fail fast, and avoid a surprise first query later
+      end
+
+      # Runs before a replica is opened or adopted, so it covers both paths.
+      def reject_url_credentials
+        return unless url_has_auth_token?(@opts[:uri].to_s)
+        raise Error, "pass auth_token: as a connection option, not in the URL (URLs end up in logs)"
+      end
+
+      def url_has_auth_token?(url)
+        query = URI.parse(url).query
+        query && URI.decode_www_form(query).any? { |k, _| k.downcase == "auth_token" }
+      rescue ArgumentError, URI::Error
+        url.match?(/[?&]auth(_|%5f)token(=|&|\z)/i)
+      end
+
+      def open_turso_database
+        return [@opts[:turso_database], false] if @opts[:turso_database]
+        path = @opts[:database].to_s
+        path = ":memory:" if path.empty?
+        db = Beagle::Turso::Database.open(
+          local_path: path,
+          remote_url: @opts[:remote_url],
+          auth_token: @opts[:auth_token],
+          bootstrap_if_empty: typecast_value_boolean(@opts.fetch(:bootstrap_if_empty, true))
+        )
+        [db, true]
+      rescue Beagle::Turso::Error => e
+        raise Sequel.convert_exception_class(e, Sequel::DatabaseConnectionError)
+      end
+
+      # The replica holds the token natively; nothing on this side needs it
+      # again, so don't let it sit in opts (inspect, logging, error reports).
+      def scrub_credentials
+        @opts.delete(:auth_token)
+        if @opts[:orig_opts].is_a?(Hash)
+          @opts[:orig_opts] = @opts[:orig_opts].reject { |k, _| k.to_s == "auth_token" }
+        end
+      end
+
+      # Busy retries so far (for specs).
+      def busy_retry_count
+        @busy_retries.value
+      end
+
+      def _execute(sql, opts, busy_retry: true)
+        synchronize(opts[:server]) do |conn|
+          # The retry sits inside the logged block: one log line per statement,
+          # at error level only if it finally fails. Inside a transaction a
+          # BusyError means the transaction is dead; it must surface (and
+          # roll back), not be retried.
+          log_connection_yield(sql, conn) { !busy_retry || _trans(conn) ? yield(conn) : retry_busy { yield conn } }
+        end
+      rescue Beagle::Turso::Error => e
+        raise_error(e)
+      end
+
+      # Conservative: a ";" inside a string literal also counts as a second
+      # statement, which only costs that statement its busy retry.
+      def single_statement?(sql)
+        !sql.strip.sub(/;\s*\z/, "").include?(";")
+      end
+
+      # Same as the shared version, but the BEGIN is retried inside its log
+      # entry (one line, not one per attempt).
+      def begin_new_transaction(conn, opts)
+        mode = opts[:mode] || @transaction_mode
+        sql = Sequel::SQLite::DatabaseMethods::TRANSACTION_MODE[mode] or
+          raise Error, "transaction :mode must be one of: :deferred, :immediate, :exclusive, nil"
+        log_connection_yield(sql, conn) { retry_busy { conn.execute_batch(sql) } }
+        set_transaction_isolation(conn, opts)
+      end
+
+      # Retries a statement that lost the single-writer race, with capped
+      # exponential backoff, for up to timeout: ms. sleep releases the GVL and
+      # yields to a fiber scheduler, so the writer holding the lock can finish.
+      def retry_busy
+        deadline = nil
+        delay = 0.002
+        begin
+          yield
+        rescue Beagle::Turso::BusyError => e
+          raise if e.message.include?("snapshot is stale")
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          deadline ||= now + @busy_timeout
+          raise if now + delay > deadline
+
+          @busy_retries.increment
+          sleep delay
+          delay = [delay * 2, 0.1].min
+          retry
+        end
+      end
+
+      # Sequel runs BEGIN/COMMIT/SAVEPOINT with conn.public_send(method, sql):
+      # one argument. Connection#execute takes (sql, params); execute_batch(sql)
+      # takes one.
+      def connection_execute_method
+        :execute_batch
+      end
+
+      def database_error_classes
+        [Beagle::Turso::Error]
+      end
+
+      def database_specific_error_class(exception, opts)
+        return DatabaseDisconnectError if disconnect_error?(exception, opts)
+
+        if exception.is_a?(Beagle::Turso::BusyError)
+          return exception.message.include?("snapshot is stale") ? SerializationFailure : DatabaseLockTimeout
+        end
+
+        message = exception.message.sub(ENGINE_PREFIX, "")
+        database_error_regexps.each { |regexp, klass| return klass if regexp.match?(message) }
+        nil
+      end
+
+      # A closed or fork-inherited connection is dead: let the pool drop it.
+      def disconnect_error?(exception, opts)
+        exception.is_a?(Beagle::Turso::ClosedError) || exception.is_a?(Beagle::Turso::ForkedError) || super
+      end
+
+      # Only reads @opts: Sequel calls this before adapter_initialize.
+      def connection_pool_default_options
+        o = super
+        memory = @opts[:database].to_s.empty? || @opts[:database] == ":memory:"
+        memory && !@opts[:turso_database] ? o.merge(max_connections: 1) : o
+      end
+
+      def dataset_class_default
+        Dataset
+      end
+
+      # The engine reports `to` as "" (SQLite: NULL) for a foreign key that
+      # references the parent's primary key implicitly. Sequel would turn that
+      # into a bogus column and break table rebuilds in alter_table.
+      def _foreign_key_list_ds(table)
+        super.with_row_proc(lambda do |row|
+          row[:to] = nil if row[:to] == ""
+          row
+        end)
+      end
+
+      # For DEFAULT (expr) SQLite reports dflt_value as expr; the engine keeps
+      # the parentheses. A default that isn't parenthesised is a literal, and
+      # no literal starts with "(", so dropping one outer pair is exact. The
+      # engine also writes a negative number as "- 1" (SQLite: "-1"), which
+      # Sequel can't parse into a Ruby default.
+      def _parse_pragma_ds(table_name, opts)
+        super.with_row_proc(lambda do |row|
+          d = row[:dflt_value]
+          if d.is_a?(String)
+            d = d[1...-1] if d.start_with?("(") && d.end_with?(")")
+            row[:dflt_value] = d.sub(/\A-\s+(?=\d)/, "-")
+          end
+          row
+        end)
+      end
+
+      # Sequel's version turns foreign keys off, rebuilds in a transaction and
+      # turns them back on, each through its own pool checkout. PRAGMA
+      # foreign_keys is per connection, so on a warm pool those can land on
+      # different connections: the rebuild runs with foreign keys on, and a
+      # connection is left with them off. Hold one connection throughout.
+      def apply_alter_table(table, ops)
+        synchronize { super }
+      end
+
+      # Sequel rebuilds a table by renaming it to a backup, creating the new
+      # table, copying and dropping the backup. The engine ignores
+      # legacy_alter_table and rewrites other tables' foreign keys (and views)
+      # to the backup name, and on a synced replica a RENAME never reaches the
+      # remote at all. So rebuild without any RENAME: copy the rows to a backup
+      # table made from the new definition, drop the original, recreate it,
+      # copy back, drop the backup. Nothing refers to the backup name. (Used
+      # for every rebuild, local or synced, so there is one code path.)
+      def duplicate_table(table, opts = OPTS)
+        rename, create, insert, drop, *rest = super
+        qt = quote_schema_table(table)
+        bt = drop.to_s.delete_prefix("DROP TABLE ")
+        create_prefix = "CREATE TABLE #{qt}("
+        insert_prefix = "INSERT INTO #{qt}("
+        unless rename == "ALTER TABLE #{qt} RENAME TO #{bt}" && create.start_with?(create_prefix) &&
+            insert.start_with?(insert_prefix) && insert.end_with?(" FROM #{bt}")
+          raise Error, "unexpected table rebuild SQL from Sequel #{Sequel::VERSION}; cannot rebuild #{qt}"
+        end
+
+        columns = insert.delete_prefix(insert_prefix).delete_suffix(" FROM #{bt}")
+        new_cols = columns.split(") SELECT ", 2).first
+        [
+          "CREATE TABLE #{bt}(#{create.delete_prefix(create_prefix)}",
+          "INSERT INTO #{bt}(#{columns} FROM #{qt}",
+          "DROP TABLE #{qt}",
+          create,
+          "INSERT INTO #{qt}(#{new_cols}) SELECT #{new_cols} FROM #{bt}",
+          "DROP TABLE #{bt}",
+          *rest
+        ]
+      end
+
+      # AUTOINCREMENT tables get engine bookkeeping tables in sqlite_master.
+      def tables_and_views(filter, opts)
+        super.reject do |name|
+          name = name.to_s
+          name.start_with?("__turso_internal_") || SYNC_ENGINE_TABLES.include?(name)
+        end
+      end
+
+      # sql with RETURNING rowid added, unless it has a RETURNING clause. The
+      # clause goes at the end of the statement: before a trailing ";" and any
+      # trailing comment (a "--" comment would otherwise swallow it). Literals,
+      # quoted identifiers and comments are masked first, so "RETURNING"
+      # inside data doesn't count as a clause.
+      def with_returning_rowid(sql)
+        # Comments become spaces (they aren't part of the statement), literals
+        # and identifiers become "x" (they are).
+        masked = sql.gsub(NON_CODE) { |m| (m.start_with?("--", "/*") ? " " : "x") * m.length }
+        return sql if RETURNING_CLAUSE.match?(masked)
+
+        at = masked.sub(/;\s*\z/, "").rstrip.length
+        "#{sql[0, at]} RETURNING rowid#{sql[at..]}"
+      end
+
+      # The engine doesn't capture ALTER TABLE ... RENAME TO / RENAME COLUMN
+      # for sync (turso_core translate/alter.rs emits no CDC for them), so on
+      # a synced replica the remote never sees the rename and every later
+      # write to the table is lost on push.
+      def refuse_rename_when_synced(what)
+        return unless @turso_database.synced?
+
+        raise Error, "#{what} is refused on a synced replica: the Turso sync engine does not replicate " \
+          "ALTER TABLE ... RENAME TO / RENAME COLUMN to the remote, so later writes to the table would be " \
+          "lost on push (no upstream fix yet). Create the new table, copy the rows and drop the old one, " \
+          "or run the rename against the remote database directly."
+      end
+
+      def alter_table_sql(table, op)
+        # On a synced replica, native DROP COLUMN loses unpushed rows and
+        # RENAME COLUMN never reaches the remote (the engine doesn't capture
+        # them), so both go through the RENAME-free rebuild.
+        if @turso_database.synced?
+          case op[:op]
+          when :drop_column
+            ocp = lambda { |oc| oc.delete_if { |c| c.to_s == op[:name].to_s } }
+            return duplicate_table(table, old_columns_proc: ocp) { |cols| cols.delete_if { |s| s[:name].to_s == op[:name].to_s } }
+          when :rename_column
+            return rebuild_renaming_column(table, op)
+          end
+        end
+        super
+      end
+
+      # Column rename as a rebuild. Sequel's fallback renames the column first
+      # and then looks up UNIQUE constraints and indexes by the old name, so it
+      # loses them. Take them before the rebuild and replay them with the new
+      # name: inline/composite UNIQUE (autoindexes) become column or table
+      # constraints, every other index mentioning the column is recreated.
+      def rebuild_renaming_column(table, op)
+        old = op[:name].to_s
+        new = op[:new_name]
+        rn = ->(cols) { cols.map { |c| c.to_s == old ? new : c } }
+        pks = schema(table).select { |_, c| c[:primary_key] }.map { |n, _| n.to_s }
+        auto_all = indexes(table, only_autocreated: true)
+        auto = auto_all.values.select { |h| h[:unique] && h[:columns].map(&:to_s) != pks }
+        single = auto.select { |h| h[:columns].length == 1 }.map { |h| rn.(h[:columns]).first.to_s }
+        constraints = auto.select { |h| h[:columns].length > 1 }.map { |h| { type: :unique, columns: rn.(h[:columns]) } }
+        refuse_rename_of_referenced_column(table, old, pks)
+        # Sequel would copy the foreign keys under the old column names; copy
+        # them ourselves with the renamed column. Self-references rename the
+        # referenced column (key) too. (The engine doesn't report DEFERRABLE.)
+        fks = foreign_key_list(table).map do |fk|
+          self_ref = fk[:table].to_s == table.to_s
+          fk.merge(type: :foreign_key, columns: rn.(fk[:columns]), key: (self_ref && fk[:key] ? rn.(fk[:key]) : fk[:key]))
+        end
+        constraints.concat(fks)
+        named = indexes(table).select { |n, h| !auto_all.key?(n) && h[:columns].map(&:to_s).include?(old) }
+
+        ncp = ->(nc) { nc.map! { |c| c.to_s == old ? new : c } }
+        sqls = duplicate_table(table, new_columns_proc: ncp, no_unique: true, no_foreign_keys: true, constraints: constraints) do |cols|
+          cols.each do |c|
+            c[:name] = new if c[:name].to_s == old
+            c[:unique] = true if single.include?(c[:name].to_s) && !c[:primary_key]
+          end
+        end
+        sqls + named.map { |name, h| alter_table_sql(table, h.merge(op: :add_index, name: name, columns: rn.(h[:columns]))) }
+      end
+
+      # A rebuild of this table can't update another table's foreign key that
+      # names the column, and the stale reference makes both tables unwritable.
+      def refuse_rename_of_referenced_column(table, old, pks)
+        referencing = tables.reject { |t| t.to_s == table.to_s }.select do |other|
+          foreign_key_list(other).any? do |fk|
+            fk[:table].to_s == table.to_s && (fk[:key] || pks).map(&:to_s).include?(old)
+          end
+        end
+        return if referencing.empty?
+
+        raise Error, "rename_column of #{table}.#{old} is refused on a synced replica: " \
+          "#{referencing.join(', ')} reference(s) it with a foreign key, and rebuilding #{table} cannot " \
+          "update that reference. Rebuild the referencing table(s) as well, or apply the rename on the " \
+          "remote database and pull."
+      end
+
+      def support_without_rowid?
+        false
+      end
+    end
+
+    class Dataset < Sequel::Dataset
+      include Sequel::SQLite::DatasetMethods
+
+      def fetch_rows(sql)
+        execute(sql) do |columns, decl_types, rows|
+          cps = db.conversion_procs
+          cols = columns.each_with_index.map { |c, i| [output_identifier(c), cps[base_type_name(decl_types[i])]] }
+          self.columns = cols.map(&:first)
+          rows.each do |values|
+            row = {}
+            cols.each_with_index do |(name, conv), i|
+              v = values[i]
+              row[name] = conv && !v.nil? ? conv.call(v) : v
+            end
+            yield row
+          end
+        end
+      end
+
+      private
+
+      # "decimal(10,2)" -> "decimal"; nil (expression columns) stays nil.
+      def base_type_name(t)
+        (t =~ /\A(.*?)\(/ ? Regexp.last_match(1) : t).downcase if t
+      end
+    end
+  end
+end

data/lib/sequel/beagle_turso/version.rb

@@ -0,0 +1,5 @@
+module Sequel
+  module BeagleTurso
+    VERSION = "0.1.0"
+  end
+end

data/lib/sequel-beagle-turso.rb

@@ -0,0 +1,3 @@
+require "sequel"
+require "sequel/beagle_turso/version"
+require "sequel/adapters/beagle_turso"

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: sequel-beagle-turso
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- BeagleSoftwareUK
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.100'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.100'
+- !ruby/object:Gem::Dependency
+  name: beagle-turso
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: |
+  A Sequel adapter (URL scheme beagle-turso://) that runs Sequel -- and ROM /
+  Hanami repositories on top of it -- on a beagle-turso database: a local
+  SQLite-compatible replica that syncs to Turso Cloud. SQL generation, schema
+  parsing and transactions come from Sequel's shared SQLite support.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sequel-beagle-turso.rb
+- lib/sequel/adapters/beagle-turso.rb
+- lib/sequel/adapters/beagle_turso.rb
+- lib/sequel/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: Sequel adapter for Turso's local-first engine, backed by the beagle-turso
+  driver.
+test_files: []