libsql-activerecord2 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c9161b429a7ede7bc2e3786e30e97df71a47a939fa927ac322866b13f8ec3fe
+  data.tar.gz: 9261dfb43874b4b505cb01f601e6d953c352ac667e319bcad38fd74eab2e09a5
+SHA512:
+  metadata.gz: c24e01dcb01d607411d7bf87938585da1ee2e2294d48a4cf3368ccda337834684459c0acc1873c2fde2619620ec2bc9d0eb450d34a534f26e4d142f2989afd59
+  data.tar.gz: 6d8d747de0df0609763adb9e6e8af65a9ed34ef87259ef319a91b32188a763fd051f68e6b074d0fd3b06e8c826c3ae4a3d760b5f380bce8ab761fce6c550659d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Speria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# libsql-activerecord2
+
+ActiveRecord adapter for [libSQL](https://libsql.org/) / [Turso](https://turso.tech/), built on the [libsql2](https://github.com/speria-jp/libsql-ruby2) gem.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "libsql-activerecord2"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Configure the `libsql` adapter in `config/database.yml` (Rails) or via `ActiveRecord::Base.establish_connection`.
+
+### Local File
+
+```yaml
+development:
+  adapter: libsql
+  database: db/development.sqlite3
+```
+
+### In-Memory
+
+```yaml
+test:
+  adapter: libsql
+  database: ":memory:"
+```
+
+### Remote (Turso)
+
+```yaml
+production:
+  adapter: libsql
+  database: libsql://your-db.turso.io
+  token: <%= ENV["TURSO_AUTH_TOKEN"] %>
+```
+
+### Embedded Replica
+
+Keeps a local replica that syncs with the remote database — ideal for read-heavy workloads with low latency.
+
+```yaml
+production:
+  adapter: libsql
+  database: libsql://your-db.turso.io
+  token: <%= ENV["TURSO_AUTH_TOKEN"] %>
+  replica_path: db/local_replica.sqlite3
+  read_your_writes: true  # default: true
+```
+
+To manually trigger a sync:
+
+```ruby
+ActiveRecord::Base.connection.sync
+```
+
+## Usage
+
+Once configured, use ActiveRecord as usual:
+
+```ruby
+class User < ApplicationRecord
+end
+
+User.create!(name: "Alice", email: "alice@example.com")
+User.where(name: "Alice").first
+```
+
+### Without Rails
+
+```ruby
+require "libsql_activerecord"
+
+ActiveRecord::Base.establish_connection(
+  adapter: "libsql",
+  database: ":memory:"
+)
+```
+
+## Supported Features
+
+| Feature | Status |
+|---------|--------|
+| Migrations | Yes |
+| Primary keys | Yes |
+| Savepoints (nested transactions) | Yes |
+| Foreign keys | Yes |
+| JSON columns | Yes |
+| DDL transactions | No (planned) |
+| EXPLAIN | No (planned) |
+| Prepared statement cache | No (planned) |
+| INSERT RETURNING | No (planned) |
+
+### Connection Modes
+
+| Mode | Supported |
+|------|-----------|
+| Local file | Yes |
+| In-memory | Yes |
+| Remote (Turso) | Yes |
+| Embedded replica | Yes |
+
+### Type Mapping
+
+| ActiveRecord Type | SQL Type | SQLite Affinity |
+|-------------------|----------|-----------------|
+| `:primary_key` | `INTEGER PRIMARY KEY AUTOINCREMENT` | INTEGER |
+| `:string` / `:text` | `TEXT` | TEXT |
+| `:integer` | `INTEGER` | INTEGER |
+| `:float` / `:decimal` | `REAL` | REAL |
+| `:datetime` / `:timestamp` | `DATETIME` | NUMERIC |
+| `:date` | `DATE` | NUMERIC |
+| `:time` | `TIME` | NUMERIC |
+| `:binary` | `BLOB` | BLOB |
+| `:boolean` | `BOOLEAN` | NUMERIC |
+| `:json` | `TEXT` | TEXT |
+
+### Exception Mapping
+
+| libSQL Error | ActiveRecord Exception |
+|-------------|----------------------|
+| `NOT NULL constraint failed` | `ActiveRecord::NotNullViolation` |
+| `UNIQUE constraint failed` | `ActiveRecord::RecordNotUnique` |
+| `FOREIGN KEY constraint failed` | `ActiveRecord::InvalidForeignKey` |
+| Other `Libsql::Error` | `ActiveRecord::StatementInvalid` |
+
+## Fork Safety
+
+The adapter supports forking web servers (Puma, Unicorn). The `discard!` method cleans up the Rust runtime safely, and new connections are established in child processes automatically.
+
+## Requirements
+
+- Ruby >= 3.4
+- ActiveRecord >= 8.0
+- [libsql2](https://github.com/speria-jp/libsql-ruby2) >= 0.1.5
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec              # Unit tests
+
+# Integration tests (per AR version)
+cd integration_tests/8.0 && bundle install && bundle exec rspec
+cd integration_tests/8.1 && bundle install && bundle exec rspec
+```
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/active_record/connection_adapters/libsql_adapter.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_record/connection_adapters/abstract_adapter"
+require "libsql2"
+
+module ActiveRecord
+  module ConnectionAdapters
+    class LibsqlAdapter < AbstractAdapter
+      ADAPTER_NAME = "Libsql"
+
+      # --- Read query detection (PRAGMA treated as read) ---
+
+      READ_QUERY = AbstractAdapter.build_read_query_regexp(:pragma)
+      private_constant :READ_QUERY
+
+      # --- FOR UPDATE / FOR SHARE stripping ---
+
+      FOR_UPDATE_PATTERN = %r{\s+FOR\s+(?:UPDATE|SHARE)(?:\s+SKIP\s+LOCKED)?(?:\s+OF\s+\S+)?\s*(?=/\*|$)}i
+      private_constant :FOR_UPDATE_PATTERN
+
+      # --- Native database types ---
+
+      NATIVE_DATABASE_TYPES = {
+        primary_key: "INTEGER PRIMARY KEY AUTOINCREMENT",
+        string: { name: "TEXT" },
+        text: { name: "TEXT" },
+        integer: { name: "INTEGER" },
+        float: { name: "REAL" },
+        decimal: { name: "REAL" },
+        datetime: { name: "DATETIME" },
+        timestamp: { name: "DATETIME" },
+        time: { name: "TIME" },
+        date: { name: "DATE" },
+        binary: { name: "BLOB" },
+        boolean: { name: "BOOLEAN" },
+        json: { name: "TEXT" }
+      }.freeze
+
+      # --- Column.new branching for AR 8.0 / 8.1 ---
+
+      COLUMN_BUILDER =
+        if ActiveRecord::VERSION::MAJOR > 8 ||
+           (ActiveRecord::VERSION::MAJOR == 8 && ActiveRecord::VERSION::MINOR >= 1)
+          # AR 8.1+: Column.new(name, cast_type, default, sql_type_metadata, null, default_function, **kwargs)
+          lambda { |name, cast_type, default, sql_type_md, null, default_function, **kwargs|
+            Column.new(name, cast_type, default, sql_type_md, null, default_function, **kwargs)
+          }
+        else
+          # AR 8.0: Column.new(name, default, sql_type_metadata, null, default_function, **kwargs)
+          lambda { |name, _cast_type, default, sql_type_md, null, default_function, **kwargs|
+            Column.new(name, default, sql_type_md, null, default_function, **kwargs)
+          }
+        end
+      private_constant :COLUMN_BUILDER
+
+      # --- AR 8.1 detection ---
+
+      AR_8_1_OR_LATER = ActiveRecord::VERSION::MAJOR > 8 ||
+                        (ActiveRecord::VERSION::MAJOR == 8 && ActiveRecord::VERSION::MINOR >= 1)
+      private_constant :AR_8_1_OR_LATER
+
+      # --- Quoting (class methods required by AR 8.0+) ---
+
+      module Quoting
+        module ClassMethods
+          def quote_column_name(name)
+            @quoted_column_names ||= {}
+            @quoted_column_names[name] ||= %("#{name.to_s.gsub('"', '""')}").freeze
+          end
+        end
+      end
+
+      include Quoting
+      extend Quoting::ClassMethods
+
+      def self.quote_table_name(name)
+        @quoted_table_names ||= {}
+        @quoted_table_names[name] ||= %("#{name.to_s.gsub('"', '""').gsub('.', '"."')}").freeze
+      end
+
+      def quote_table_name(name)
+        self.class.quote_table_name(name)
+      end
+
+      def quoted_true = "1"
+      def quoted_false = "0"
+      def unquoted_true = 1
+      def unquoted_false = 0
+
+      # --- Feature flags ---
+
+      def supports_migrations? = true
+      def supports_primary_key? = true
+      def supports_savepoints? = true
+      def supports_foreign_keys? = true
+      def supports_json? = true
+      def supports_ddl_transactions? = false
+      def supports_explain? = false
+      def supports_lazy_transactions? = false
+      def supports_insert_returning? = false
+
+      def native_database_types
+        NATIVE_DATABASE_TYPES
+      end
+
+      # --- Connection lifecycle ---
+
+      def initialize(...)
+        super
+        @raw_database = nil
+      end
+
+      def connect
+        @raw_database, @raw_connection = build_libsql_connection
+      end
+
+      def active?
+        return false unless @raw_connection
+
+        @raw_connection.query("SELECT 1")
+        true
+      rescue ::Libsql::Error, ::Libsql::ClosedError
+        false
+      end
+
+      def connected?
+        !@raw_connection.nil?
+      end
+
+      def disconnect!
+        super
+        @raw_connection&.close
+        @raw_database&.close
+        @raw_connection = nil
+        @raw_database = nil
+      end
+
+      # Clean up Rust runtime after fork (Puma / Unicorn safety).
+      def discard!
+        @raw_database&.discard!
+        @raw_connection = nil
+        @raw_database = nil
+      end
+
+      # Sync embedded replica with remote.
+      def sync
+        @raw_database&.sync
+      end
+
+      # --- Query execution pipeline ---
+
+      def write_query?(sql)
+        !READ_QUERY.match?(sql)
+      rescue ArgumentError
+        !READ_QUERY.match?(sql.b)
+      end
+
+      def perform_query(raw_connection, sql, _binds, type_casted_binds,
+                        prepare:, notification_payload:, batch: false)
+        sanitized = sanitize_for_update(sql)
+        params = type_casted_binds || []
+
+        result =
+          if batch
+            raw_connection.execute_batch(sanitized)
+            build_empty_result(affected: 0)
+          elsif write_query?(sanitized)
+            affected = raw_connection.execute(sanitized, params)
+            @last_inserted_id = raw_connection.last_insert_rowid
+            build_empty_result(affected: affected)
+          else
+            rows_obj = raw_connection.query(sanitized, params)
+            build_read_result(rows_obj, raw_connection)
+          end
+
+        notification_payload[:row_count] = result&.length || 0
+        notification_payload[:affected_rows] = affected_rows(result) if AR_8_1_OR_LATER
+
+        result
+      end
+
+      def cast_result(result)
+        result
+      end
+
+      def affected_rows(result)
+        if result.respond_to?(:affected_rows)
+          result.affected_rows
+        else
+          @last_affected_rows
+        end
+      end
+
+      def last_inserted_id(_result)
+        @last_inserted_id
+      end
+
+      # --- Transactions ---
+
+      def begin_db_transaction
+        @raw_connection.execute("BEGIN")
+      end
+
+      def commit_db_transaction
+        @raw_connection.execute("COMMIT")
+      end
+
+      def exec_rollback_db_transaction
+        @raw_connection.execute("ROLLBACK")
+      end
+
+      def create_savepoint(name = current_savepoint_name)
+        @raw_connection.execute("SAVEPOINT #{quote_column_name(name)}")
+      end
+
+      def release_savepoint(name = current_savepoint_name)
+        @raw_connection.execute("RELEASE SAVEPOINT #{quote_column_name(name)}")
+      end
+
+      def exec_rollback_to_savepoint(name = current_savepoint_name)
+        @raw_connection.execute("ROLLBACK TO SAVEPOINT #{quote_column_name(name)}")
+      end
+
+      # --- Schema introspection ---
+
+      def tables
+        query = "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        result = @raw_connection.query(query)
+        result.to_a.map { |row| row["name"] }
+      end
+
+      def table_exists?(table_name)
+        tables.include?(table_name.to_s)
+      end
+
+      def views
+        query = "SELECT name FROM sqlite_master WHERE type='view' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        result = @raw_connection.query(query)
+        result.to_a.map { |row| row["name"] }
+      end
+
+      def column_definitions(table_name)
+        result = @raw_connection.query("PRAGMA table_info(#{quote_table_name(table_name)})")
+        result.to_a
+      end
+
+      def new_column_from_field(_table_name, field, _definitions)
+        default_value = field["dflt_value"]
+
+        # Unquote string defaults
+        default_value = default_value[1..-2] if default_value&.start_with?("'") && default_value.end_with?("'")
+
+        type = field["type"]
+        type_metadata = fetch_type_metadata(type)
+        cast_type = lookup_cast_type(type)
+        null = field["notnull"].to_i.zero?
+        default_function = nil
+
+        COLUMN_BUILDER.call(
+          field["name"], cast_type, default_value, type_metadata, null, default_function
+        )
+      end
+
+      def primary_keys(table_name)
+        result = @raw_connection.query("PRAGMA table_info(#{quote_table_name(table_name)})")
+        result.to_a
+              .select { |row| row["pk"].to_i.positive? }
+              .sort_by { |row| row["pk"].to_i }
+              .map { |row| row["name"] }
+      end
+
+      def indexes(table_name)
+        index_list = @raw_connection.query("PRAGMA index_list(#{quote_table_name(table_name)})").to_a
+
+        index_list.filter_map do |idx|
+          next if idx["name"].start_with?("sqlite_")
+
+          columns = @raw_connection.query("PRAGMA index_info(#{quote_table_name(idx['name'])})").to_a
+          column_names = columns.sort_by { |c| c["seqno"].to_i }.map { |c| c["name"] }
+
+          IndexDefinition.new(
+            table_name,
+            idx["name"],
+            idx["unique"].to_i != 0,
+            column_names
+          )
+        end
+      end
+
+      # --- Schema DDL ---
+
+      def rename_table(table_name, new_name, **)
+        execute("ALTER TABLE #{quote_table_name(table_name)} RENAME TO #{quote_table_name(new_name)}")
+      end
+
+      def rename_column(table_name, column_name, new_column_name, **)
+        execute(
+          "ALTER TABLE #{quote_table_name(table_name)} " \
+          "RENAME COLUMN #{quote_column_name(column_name)} TO #{quote_column_name(new_column_name)}"
+        )
+      end
+
+      # --- Exception translation ---
+
+      def translate_exception(exception, message:, sql:, binds:)
+        # Libsql::Error inherits from RuntimeError, so the default
+        # translate_exception would return it as-is. We must handle
+        # it explicitly to convert to AR exception classes.
+        msg = exception.message
+        if /NOT NULL constraint failed/i.match?(msg)
+          NotNullViolation.new(message, sql: sql, binds: binds, connection_pool: @pool)
+        elsif /UNIQUE constraint failed/i.match?(msg)
+          RecordNotUnique.new(message, sql: sql, binds: binds, connection_pool: @pool)
+        elsif /FOREIGN KEY constraint failed/i.match?(msg)
+          InvalidForeignKey.new(message, sql: sql, binds: binds, connection_pool: @pool)
+        elsif exception.is_a?(::Libsql::Error)
+          StatementInvalid.new(message, sql: sql, binds: binds, connection_pool: @pool)
+        else
+          super
+        end
+      end
+
+      # --- Type map (class method, required by AR 8.0+) ---
+
+      class << self
+        private
+
+        def initialize_type_map(m)
+          super
+          # SQLite INTEGER is always 64-bit signed; override AR default (limit: 4)
+          m.register_type(/^integer/i, Type::Integer.new(limit: 8))
+          # REAL is not registered by AbstractAdapter
+          m.register_type(/^real/i, Type::Float.new)
+        end
+      end
+
+      TYPE_MAP = Type::TypeMap.new.tap { |m| initialize_type_map(m) }
+      EXTENDED_TYPE_MAPS = Concurrent::Map.new
+
+      private
+
+      # --- Connection building ---
+
+      def build_libsql_connection
+        database_url = @config[:database] || raise(ArgumentError, "libsql adapter requires :database")
+        token = @config[:token] || ""
+        replica_path = @config[:replica_path]
+
+        db = if replica_path
+               ::Libsql::Database.open(
+                 database_url.to_s,
+                 auth_token: token.to_s,
+                 local_path: replica_path.to_s,
+                 read_your_writes: @config.fetch(:read_your_writes, true)
+               )
+             elsif database_url.to_s.start_with?("libsql://", "https://")
+               ::Libsql::Database.open(database_url.to_s, auth_token: token.to_s)
+             else
+               ::Libsql::Database.open(database_url.to_s)
+             end
+
+        [db, db.connect]
+      end
+
+      # Reconnect implementation called by AbstractAdapter#reconnect!
+      def reconnect
+        disconnect!
+        @raw_database, @raw_connection = build_libsql_connection
+      end
+
+      # --- Query helpers ---
+
+      def sanitize_for_update(sql)
+        sql.gsub(FOR_UPDATE_PATTERN, " ")
+      end
+
+      def build_read_result(rows_obj, raw_connection)
+        columns = rows_obj.columns
+        rows = rows_obj.to_a.map { |row| columns.map { |c| row[c] } }
+        affected = raw_connection.changes
+
+        if AR_8_1_OR_LATER
+          ActiveRecord::Result.new(columns, rows, affected_rows: affected)
+        else
+          @last_affected_rows = affected
+          ActiveRecord::Result.new(columns, rows)
+        end
+      end
+
+      def build_empty_result(affected:)
+        if AR_8_1_OR_LATER
+          ActiveRecord::Result.empty(affected_rows: affected)
+        else
+          @last_affected_rows = affected
+          ActiveRecord::Result.empty
+        end
+      end
+    end
+  end
+end
+
+# Register adapter directly (works with and without Rails).
+# When loaded via Railtie the duplicate register is harmless.
+ActiveRecord::ConnectionAdapters.register(
+  "libsql",
+  "ActiveRecord::ConnectionAdapters::LibsqlAdapter",
+  "active_record/connection_adapters/libsql_adapter"
+)

data/lib/libsql_activerecord/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module LibsqlActiverecord
+  class Railtie < Rails::Railtie
+    initializer "libsql_activerecord.register_adapter" do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::ConnectionAdapters.register(
+          "libsql",
+          "ActiveRecord::ConnectionAdapters::LibsqlAdapter",
+          "active_record/connection_adapters/libsql_adapter"
+        )
+      end
+    end
+  end
+end

data/lib/libsql_activerecord/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LibsqlActiverecord
+  VERSION = "0.1.0"
+end

data/lib/libsql_activerecord.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "libsql_activerecord/version"
+require_relative "libsql_activerecord/railtie" if defined?(Rails::Railtie)
+
+require "active_record/connection_adapters/libsql_adapter"

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: libsql-activerecord2
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Speria
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: libsql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.5
+description: ActiveRecord connection adapter for libSQL databases (local, remote,
+  and embedded replica modes), built on the libsql2 gem.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/active_record/connection_adapters/libsql_adapter.rb
+- lib/libsql_activerecord.rb
+- lib/libsql_activerecord/railtie.rb
+- lib/libsql_activerecord/version.rb
+homepage: https://github.com/speria-jp/libsql-activerecord2
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: ActiveRecord adapter for libSQL / Turso
+test_files: []