activerecord-quack-adapter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85c40e8e221c6b640fd8989d2cf5255f02057dc71df355e37fd689a81cf519c0
+  data.tar.gz: a4df3550a3df4ebf50d1404b131fddcade2710de33440e3c1768f7b8a782f773
+SHA512:
+  metadata.gz: ce81bc7fb7a4ea719a14f389f56a70eb3f355f761f198307263c67bddce9d03e4066955ac7dd7e5c86814958a33ee9357482735d538f23f53b6e728e0fbeb339
+  data.tar.gz: f185a72163bfaddd2c02217b4f2a67d7f354277ed18fc7fbda3a440c682cf0e38257b8f0bc1c142010c5de64b14df676279c3d6d4bcb8b7870930d7e21507db0

data/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2026 quack-ruby contributors
+
+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.
+
+Portions adapted from Ruby on Rails:
+Copyright (c) David Heinemeier Hansson
+
+Arel originally copyright (c) 2007-2016 Nick Kallen, Bryan Helmkamp, Emilio Tagua, Aaron Patterson
+
+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/LICENSE-ActiveRecord

@@ -0,0 +1,22 @@
+Copyright (c) David Heinemeier Hansson
+
+Arel originally copyright (c) 2007-2016 Nick Kallen, Bryan Helmkamp, Emilio Tagua, Aaron Patterson
+
+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,193 @@
+# activerecord-quack-adapter
+
+Direct Quack protocol adapter for Rails / Active Record 7.2, 8.0 and 8.1,
+backed by [quack-ruby](https://github.com/sidequery/quack-ruby). Connections use
+HTTP(S) rather than ADBC or an embedded DuckDB database.
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem "activerecord-quack-adapter", "~> 0.1.0"
+```
+
+The adapter installs `quack-ruby` automatically. Its precompiled gems cover Ruby
+3.2–3.4 on macOS and Linux glibc, on both Intel/x86-64 and ARM64. The Quack
+extension needs no Cargo or compiler on those combinations. Source installs
+on other platforms require the client's native build prerequisites.
+A Quack server and database must already exist. Supported servers are DuckDB
+1.5.5 and 2.0.0. Ruby entry points and the `adapter: quack` setting are unchanged.
+
+## Rails configuration and usage
+
+A Quack server must already be running. Configure `config/database.yml`:
+
+```yaml
+default: &default
+  adapter: quack
+  uri: <%= ENV.fetch("QUACK_URI") %>
+  auth_token: <%= ENV.fetch("QUACK_TOKEN") %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5) %>
+  timeout: 30 # Seconds per HTTP request, not Rails' pool checkout timeout.
+  # ssl_fingerprint: <%= ENV["QUACK_SSL_FINGERPRINT"] %>
+  # catalog: analytics
+  # schema: main
+
+development:
+  <<: *default
+test:
+  <<: *default
+production:
+  <<: *default
+```
+
+`uri` accepts `quack:host:port`, `host:port`, bracketed IPv6, or an HTTP(S) URL.
+Alternatively set `host` and `port`. `database` is accepted as an endpoint alias;
+use `catalog` to select a database attached on the server. Native connection
+options such as `ssl`, headers and protocol-version bounds also work in YAML.
+
+For self-signed HTTPS, configure the certificate's SHA-256 `ssl_fingerprint`.
+A pin implies HTTPS and trusts that exact certificate. Without a pin, HTTPS uses
+normal certificate and hostname validation.
+
+Models and migrations use the normal Rails interfaces:
+
+```ruby
+class Event < ApplicationRecord
+end
+
+class CreateEvents < ActiveRecord::Migration[7.2]
+  def change
+    create_table :events do |t|
+      t.string :name, null: false
+      t.bigint :count
+      t.decimal :amount, precision: 20, scale: 6
+      t.timestamps
+    end
+  end
+end
+
+Event.create!(name: "signup", count: 1)
+Event.where(name: "signup").count
+Event.insert_all!([{name: "signup", count: 2}], returning: %w[id name])
+Event.transaction { Event.where(name: "signup").update_all(count: 3) }
+```
+
+The adapter implements CRUD, bound queries, generated IDs via sequences and
+`RETURNING`, SQL bulk insert/upsert, transactions, table/column/primary-key/index
+inspection, ordinary table/column/index migrations and sequence-aware
+`schema.rb` dumping/loading. Rails owns pooling; each adapter connection owns one
+remote session. There is no second Rust connection pool beneath Active Record.
+
+`rails db:migrate` operates on the existing remote database. `db:create` checks
+that the endpoint is accessible and reports it already exists. Provision and
+remove databases on the server; client-side `db:drop`, `db:purge`, `db:reset`, and
+SQL structure dump/load tasks are intentionally unavailable. Use Ruby schema
+format. For an analytics-only secondary connection, use Rails' multiple-database
+configuration with `database_tasks: false` and an abstract model with
+`connects_to`.
+
+## Data types
+
+| DuckDB value | Ruby value |
+| --- | --- |
+| Signed/unsigned integers, including 128-bit and BIGNUM | `Integer`, without precision loss |
+| Decimal | `BigDecimal` |
+| Boolean, floating point, text, NULL | `true`/`false`, `Float`, `String`, `nil` |
+| BLOB / other byte payloads | Binary-encoded `String` |
+| Date | Proleptic Gregorian `Date` |
+| Timestamp | `Quack::Timestamp < Time`, retaining SQL units, timezone kind and nanoseconds |
+| Time / time with offset | `Quack::TimeOfDay` (supports `24:00:00`) |
+| Interval | `Quack::Interval(months, days, microseconds)` |
+| Infinite date/timestamp | `Quack::InfiniteTemporal` |
+| List/array, struct | `Array`, string-keyed `Hash` |
+| JSON, UUID, ENUM | `String` (Rails casts JSON to Ruby objects) |
+| MAP | `Quack::Map`, with `entries`, `[]`, `each`, `to_h` |
+| BIT | `Quack::BitString(bits)`, a string of logical 0/1 bits |
+| GEOMETRY | `Quack::Geometry(wkb, crs)`, standard WKB and optional CRS |
+| UNION | `Quack::Union(tag, value, members)`; tag distinguishes a NULL member from SQL NULL |
+| VARIANT | `Quack::Variant`, with a typed `node` tree and logical Ruby `value` |
+| TUPLE / unnamed STRUCT | `Quack::Tuple(values)`, preserving every ordinal field |
+
+These logical values support SQL parameters, model assignment and native v1
+append, including values nested in lists, arrays and structs. BIGNUM decoding,
+DuckDB 2.0 type IDs and unnamed field handling are fixed in the packaged crate;
+no separate fork download is needed to build the gem.
+
+Read timestamps retain their SQL kind when rebound. Construct one explicitly
+with `Quack::Timestamp.from(time, "TIMESTAMP_NS")` or, on DuckDB 2.0,
+`Quack::Timestamp.from(time, "TIMESTAMPTZ_NS")`. Plain `Time`/`DateTime` values
+use TIMESTAMPTZ when microseconds suffice and TIMESTAMP_NS when nanoseconds are
+needed. Connections initialize `TimeZone = 'UTC'`, including after reconnect.
+Subsequent explicit timezone changes follow DuckDB's normal cast semantics.
+Values beyond a destination's precision are rejected by native append rather
+than silently truncated. Rails writes preserve nine fractional digits.
+
+`Quack::Variant.new({"items" => [1, nil, "é"]})` builds a heterogeneous value.
+Use `Quack::Variant.new(value, type: "UBIGINT")` to specify a scalar type.
+`variant.value` returns a Ruby tree; `variant.node` preserves each nested scalar
+type. Assign a new Variant to edit it. DuckDB normalizes a root VARIANT null to
+SQL NULL (`nil`); nulls inside containers remain nested nodes. Geometry uses
+standard WKB rather than a client geometry engine, preserving Z/M, empty values,
+collections and CRS metadata.
+
+All storable public type families are exercised on the supported server versions.
+DuckDB 1.5 cannot persist unnamed STRUCT/ROW tuples (even regular SQL INSERT fails);
+their query/parameter roundtrips work, and tuple persistence is tested on 2.0.
+TIMESTAMPTZ_NS is a DuckDB 2.0 type and is unavailable on 1.5. Internal/binder-only
+types and types supplied by optional server extensions are not universal targets.
+
+Scalar and logical values support normal create/update/reload, bound queries
+and SQL bulk writes. Lists, structs and nested maps track in-place edits.
+Use explicit SQL migrations for DuckDB types without a Rails migration helper.
+
+## Adapter limits
+
+- DuckDB has no savepoints. Joined nested transactions work; `requires_new`
+  savepoints and custom isolation levels are unsupported.
+- Foreign-key/check-constraint migration helpers and expression/partial-index
+  helpers are unavailable. They raise rather than silently dropping constraints.
+- Schema dumps support the ordinary migration types, including generated-ID
+  sequences. Comprehensive complex-type schema dumping is not implemented;
+  manage those objects with explicit SQL migrations.
+- Provision/drop remote databases on the server. Client db:drop, db:purge,
+  db:reset and SQL structure dump/load tasks are unavailable. Use schema.rb
+  for supported migration types.
+- Statements are never replayed after a session/transport failure, including
+  through Rails' allow_retry. Handle the failure and reconnect explicitly.
+- Rails owns pooling; one adapter connection owns one remote session. Native
+  network waits release the GVL. Create/check out connections after forking.
+
+## Development
+
+```sh
+CARGO="$PWD/script/cached-cargo" bundle install
+script/test
+BUNDLE_GEMFILE=gemfiles/active_record_72.gemfile CARGO="$PWD/script/cached-cargo" bundle install
+BUNDLE_GEMFILE=gemfiles/active_record_72.gemfile script/test
+BUNDLE_GEMFILE=gemfiles/active_record_80.gemfile CARGO="$PWD/script/cached-cargo" bundle install
+BUNDLE_GEMFILE=gemfiles/active_record_80.gemfile script/test
+bundle exec rake package
+```
+
+Tests use uv to start real DuckDB 1.5.5/v1 and 2.0.0/v3 servers and stop them
+after each run. They exercise model/result/bind roundtrips across all storable
+public type families, nested mutation tracking, CRUD, bulk insert/upsert,
+transactions, pooling, metadata, schema migrations/dumps and a Rails app that
+boots from database.yml and serves database-backed POST/GET requests.
+
+CI is configured for all three Active Record series on Linux/macOS. The
+client's separate suite covers protocol, TLS, lifecycle and native v1 append.
+The `Release` workflow builds the adapter gem and tests installed packages
+against all three Rails series with Cargo and rustc blocked. Dispatch it from
+main with a patch, minor or major bump to update versions and locks, commit/tag,
+test, publish through RubyGems Trusted Publishing, and create a GitHub Release.
+An optional `release_tag` publishes an existing matching tag without a bump.
+Publish the matching client version first; update the client dependency when
+moving to a new client minor series.
+
+## License
+
+MIT. Adapted Active Record quoting/bulk-insert code retains the upstream
+notice in LICENSE-ActiveRecord. Quack's native dependency has its own licenses.

data/lib/active_record/connection_adapters/quack/legacy_database_statements.rb

@@ -0,0 +1,37 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module Quack
+      # Rails 7.2 predates the perform_query/cast_result adapter hooks.
+      module LegacyDatabaseStatements
+        def internal_exec_query(sql, name = "SQL", binds = [], prepare: false, async: false, allow_retry: false)
+          sql = transform_query(sql)
+          check_if_write_query(sql)
+          mark_transaction_written_if_write(sql)
+          cast_result(legacy_raw_query(sql, name, binds, prepare: prepare, async: async))
+        end
+
+        def exec_delete(sql, name = "SQL", binds = [])
+          sql = transform_query(sql)
+          check_if_write_query(sql)
+          mark_transaction_written_if_write(sql)
+          affected_rows(legacy_raw_query(sql, name, binds))
+        end
+        alias exec_update exec_delete
+
+        private
+        def raw_execute(sql, name, async: false, allow_retry: false, materialize_transactions: true)
+          legacy_raw_query(sql, name, [], async: async, materialize_transactions: materialize_transactions)
+        end
+
+        def legacy_raw_query(sql, name, binds, prepare: false, async: false, materialize_transactions: true)
+          casted = type_casted_binds(binds)
+          log(sql, name, binds, casted, async: async) do |payload|
+            with_raw_connection(allow_retry: false, materialize_transactions: materialize_transactions) do |connection|
+              perform_query(connection, sql, binds, casted, prepare: prepare, notification_payload: payload)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/quack/schema_dumper.rb

@@ -0,0 +1,25 @@
+require "active_record/connection_adapters/abstract/schema_dumper"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Quack
+      class SchemaDumper < ConnectionAdapters::SchemaDumper
+        private
+        def tables(stream)
+          # Sequence-backed primary keys must survive loading schema.rb into a
+          # fresh database, including sequences supplied by the application.
+          @connection.select_values(<<~SQL, "SCHEMA").each do |sql|
+            SELECT sql FROM duckdb_sequences()
+            WHERE database_name = current_database() AND schema_name = current_schema()
+            ORDER BY sequence_name
+          SQL
+            statement = sql.sub(/\ACREATE SEQUENCE\b/i, "CREATE SEQUENCE IF NOT EXISTS")
+            stream.puts "  execute #{statement.inspect}"
+          end
+          stream.puts
+          super
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/quack/schema_statements.rb

@@ -0,0 +1,143 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module Quack
+      class TableDefinition < ConnectionAdapters::TableDefinition
+        def foreign_key(*)
+          raise ActiveRecord::StatementInvalid, "Quack foreign-key migration helpers are unsupported; use explicit DuckDB SQL"
+        end
+
+        def check_constraint(*)
+          raise ActiveRecord::StatementInvalid, "Quack check-constraint migration helpers are unsupported; use explicit DuckDB SQL"
+        end
+      end
+
+      module SchemaStatements
+        def add_foreign_key(*)
+          raise ActiveRecord::StatementInvalid, "Quack foreign-key migration helpers are unsupported; use explicit DuckDB SQL"
+        end
+        alias remove_foreign_key add_foreign_key
+
+        def add_check_constraint(*)
+          raise ActiveRecord::StatementInvalid, "Quack check-constraint migration helpers are unsupported; use explicit DuckDB SQL"
+        end
+        alias remove_check_constraint add_check_constraint
+
+        def create_table(table_name, id: :primary_key, primary_key: nil, **options, &block)
+          if [:primary_key, :bigint, :integer].include?(id) && !primary_key.is_a?(Array) && !options[:as] && !options.key?(:default)
+            parts = ::Quack::SQL.identifier_parts(table_name)
+            sequence = parts[0...-1] + ["#{parts.last}_#{primary_key || 'id'}_seq"]
+            sequence_name = sequence.map { |part| quote_column_name(part) }.join(".")
+            execute("CREATE SEQUENCE IF NOT EXISTS #{sequence_name}")
+            id = {type: id == :integer ? :integer : :bigint, default: -> { "nextval(#{quote(sequence_name)})" }}
+          end
+          super(table_name, id: id, primary_key: primary_key, **options, &block)
+        end
+
+        def primary_keys(table_name)
+          row = internal_exec_query("SELECT constraint_column_names FROM duckdb_constraints() WHERE #{catalog_scope(table_name)} AND constraint_type = 'PRIMARY KEY'", "SCHEMA").first
+          row ? row.fetch("constraint_column_names") : []
+        end
+
+        def indexes(table_name)
+          internal_exec_query("SELECT index_name, is_unique, expressions, sql FROM duckdb_indexes() WHERE #{catalog_scope(table_name)}", "SCHEMA").map do |row|
+            expressions = row.fetch("sql")[/\bON\b.*?\((.*)\)\s*;?\z/im, 1]
+            parts = expressions.to_s.split(/,\s*/)
+            simple = parts.all? { |part| part.match?(/\A(?:"(?:[^"]|"")*"|[A-Za-z_][A-Za-z_0-9]*)\z/) }
+            columns = simple ? parts.map { |part| part.delete_prefix('"').delete_suffix('"').gsub('""', '"') } : expressions
+            IndexDefinition.new(table_name, row.fetch("index_name"), row.fetch("is_unique"), columns)
+          end
+        end
+
+        def rename_table(table_name, new_name, **)
+          execute("ALTER TABLE #{quote_table_name(table_name)} RENAME TO #{quote_column_name(new_name)}")
+          schema_cache.clear_data_source_cache!(table_name.to_s)
+          schema_cache.clear_data_source_cache!(new_name.to_s)
+        end
+
+        def change_column_default(table_name, column_name, default_or_changes)
+          default = extract_new_default_value(default_or_changes)
+          column = column_for(table_name, column_name)
+          execute("ALTER TABLE #{quote_table_name(table_name)} ALTER COLUMN #{quote_column_name(column_name)} SET DEFAULT #{quote_default_expression(default, column)}")
+        end
+
+        def change_column_null(table_name, column_name, null, default = nil)
+          validate_change_column_null_argument!(null)
+          unless null || default.nil?
+            execute("UPDATE #{quote_table_name(table_name)} SET #{quote_column_name(column_name)} = #{quote(default)} WHERE #{quote_column_name(column_name)} IS NULL")
+          end
+          execute("ALTER TABLE #{quote_table_name(table_name)} ALTER COLUMN #{quote_column_name(column_name)} #{null ? 'DROP' : 'SET'} NOT NULL")
+        end
+
+        def change_column(table_name, column_name, type, **options)
+          execute("ALTER TABLE #{quote_table_name(table_name)} ALTER COLUMN #{quote_column_name(column_name)} TYPE #{type_to_sql(type, **options)}")
+          change_column_default(table_name, column_name, options[:default]) if options.key?(:default)
+          change_column_null(table_name, column_name, options[:null]) if options.key?(:null)
+        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
+
+        def remove_index(table_name, column_name = nil, **options)
+          return if options[:if_exists] && !index_exists?(table_name, column_name, **options)
+          name = index_name_for_remove(table_name, column_name, options)
+          execute("DROP INDEX #{quote_table_name(name)}")
+        end
+
+        def type_to_sql(type, limit: nil, **options)
+          if type.to_s == "integer"
+            return {1 => "TINYINT", 2 => "SMALLINT", 4 => "INTEGER", 8 => "BIGINT"}.fetch(limit || 4) { raise ArgumentError, "unsupported integer limit: #{limit}" }
+          end
+          super(type, limit: limit, **options)
+        end
+
+        def create_schema_dumper(options)
+          Quack::SchemaDumper.create(self, options)
+        end
+
+        private
+        def create_table_definition(name, **options)
+          Quack::TableDefinition.new(self, name, **options)
+        end
+
+        def catalog_scope(name)
+          parts = ::Quack::SQL.identifier_parts(name)
+          table = parts.pop
+          schema = parts.pop
+          catalog = parts.pop
+          "database_name = #{catalog ? quote(catalog) : 'current_database()'} AND schema_name = #{schema ? quote(schema) : 'current_schema()'} AND table_name = #{quote(table)}"
+        end
+
+        def data_source_sql(name = nil, type: nil)
+          parts = name ? ::Quack::SQL.identifier_parts(name) : []
+          table, schema, catalog = parts.reverse
+          sql = +"SELECT table_name FROM information_schema.tables WHERE table_catalog = #{catalog ? quote(catalog) : 'current_database()'} AND table_schema = #{schema ? quote(schema) : 'current_schema()'}"
+          sql << " AND table_name = #{quote(table)}" if table
+          sql << " AND table_type = #{quote(type)}" if type
+          sql << " ORDER BY table_name"
+        end
+
+        def column_definitions(table_name)
+          internal_exec_query("SELECT column_name, data_type, column_default, is_nullable FROM duckdb_columns() WHERE #{catalog_scope(table_name)} ORDER BY column_index", "SCHEMA").to_a
+        end
+
+        def new_column_from_field(_table_name, field, _definitions)
+          sql_type = field.fetch("data_type")
+          metadata = fetch_type_metadata(sql_type)
+          cast_type = lookup_cast_type(sql_type)
+          raw_default = field["column_default"]
+          literal = raw_default && raw_default.match?(/\A(?:NULL|true|false|[-+]?\d+(?:\.\d+)?|'(?:[^']|'')*'(?:::[\w ]+)?)\z/i)
+          default = if literal
+            text = raw_default.sub(/::[\w ]+\z/, "")
+            text = text[1...-1].gsub("''", "'") if text.start_with?("'")
+            raw_default.casecmp?("NULL") ? nil : text
+          end
+          default_function = raw_default unless literal
+          args = [field.fetch("column_name"), default, metadata, field.fetch("is_nullable"), default_function]
+          args.insert(1, cast_type) if ActiveRecord.gem_version >= Gem::Version.new("8.1")
+          Column.new(*args)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/quack/value_type.rb

@@ -0,0 +1,21 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module Quack
+      class DateTimeType < Type::DateTime
+        def serialize_cast_value(value)
+          # Active Support's DateTime#getutc converts calendar fields to Time.
+          # Normalize the calendar first so Julian dates keep their instant.
+          value = value.new_start(Date::GREGORIAN) if value.is_a?(::DateTime)
+          super(value)
+        end
+      end
+
+      class ValueType < Type::Value
+        def cast(value) = ::Quack::Codec.copy(value)
+        alias deserialize cast
+        def mutable? = true
+        def changed_in_place?(raw_old_value, new_value) = raw_old_value != new_value
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/quack_adapter.rb

@@ -0,0 +1,253 @@
+require "active_record/connection_adapters/abstract_adapter"
+require "quack"
+require_relative "quack/schema_statements"
+require_relative "quack/schema_dumper"
+require_relative "quack/legacy_database_statements"
+require_relative "quack/value_type"
+
+module ActiveRecord
+  module ConnectionAdapters
+    class QuackAdapter < AbstractAdapter
+      ADAPTER_NAME = "Quack"
+      include Quack::SchemaStatements
+      include Quack::LegacyDatabaseStatements if ActiveRecord.gem_version < Gem::Version.new("8.0")
+
+      NATIVE_DATABASE_TYPES = {
+        primary_key: "BIGINT PRIMARY KEY",
+        string: {name: "VARCHAR"}, text: {name: "VARCHAR"},
+        integer: {name: "INTEGER"}, bigint: {name: "BIGINT"},
+        float: {name: "DOUBLE"}, decimal: {name: "DECIMAL"},
+        datetime: {name: "TIMESTAMP"}, timestamp: {name: "TIMESTAMP"},
+        time: {name: "TIME"}, date: {name: "DATE"},
+        binary: {name: "BLOB"}, boolean: {name: "BOOLEAN"},
+        json: {name: "JSON"}, uuid: {name: "UUID"}
+      }.freeze
+
+      class << self
+        def new_client(config)
+          uri = config[:uri] || config[:database]
+          unless uri
+            host = config.fetch(:host, "localhost")
+            host = "[#{host}]" if host.include?(":") && !host.start_with?("[")
+            uri = "quack:#{host}:#{config.fetch(:port, 9494)}"
+          end
+          options = config.stringify_keys.slice(*::Quack::Connection::OPTIONS).symbolize_keys
+          ::Quack::Connection.new(uri, **options)
+        end
+
+        def native_database_types = NATIVE_DATABASE_TYPES
+        def quote_column_name(name) = ::Quack::SQL.identifier(name)
+        def quote_table_name(name) = ::Quack::SQL.identifier_parts(name).map { |part| quote_column_name(part) }.join(".")
+
+        private
+        def initialize_type_map(map)
+          super
+          map.register_type(/\ATIMESTAMP(?:_S|_MS|_NS|TZ|TZ_NS| WITH TIME ZONE)?\z/i, Quack::DateTimeType.new)
+          {"TINYINT" => 1, "SMALLINT" => 2, "INTEGER" => 4, "BIGINT" => 8,
+           "UTINYINT" => 2, "USMALLINT" => 4, "UINTEGER" => 8,
+           "UBIGINT" => 16, "HUGEINT" => 16, "UHUGEINT" => 32}.each do |name, limit|
+            map.register_type(/\A#{name}\z/i, Type::Integer.new(limit: limit))
+          end
+          map.register_type(/\AUUID\z/i, Type::String.new)
+          map.register_type(/(?:\[\d*\]\z|\A(?:STRUCT|TUPLE|MAP|UNION|VARIANT|BIT|GEOMETRY|BIGNUM)\b)/i, Quack::ValueType.new)
+          map.register_type(/\AINTERVAL\z/i, Quack::ValueType.new)
+        end
+      end
+      TYPE_MAP = Type::TypeMap.new.tap { |map| initialize_type_map(map) }
+
+      def supports_ddl_transactions? = true
+      def supports_savepoints? = false
+      def supports_transaction_isolation? = false
+      def supports_lazy_transactions? = true
+      def supports_insert_returning? = true
+      def supports_insert_on_duplicate_skip? = true
+      def supports_insert_on_duplicate_update? = true
+      def supports_insert_conflict_target? = true
+      def supports_views? = true
+      def supports_json? = true
+      def supports_common_table_expressions? = true
+      def supports_datetime_with_precision? = true
+      def supports_explain? = true
+      def native_database_types = NATIVE_DATABASE_TYPES
+      def connected? = !!@raw_connection&.connected?
+
+      def active?
+        @lock.synchronize do
+          return false unless connected?
+          @raw_connection.query("SELECT 1")
+          verified!
+          true
+        end
+      rescue ::Quack::Error
+        false
+      end
+
+      def disconnect!
+        @lock.synchronize do
+          super
+          begin
+            @raw_connection&.close
+          rescue ::Quack::ConnectionError, ::Quack::ProtocolError, ::Quack::ForkError
+            # Retire a failed or inherited connection without replaying SQL.
+          ensure
+            @raw_connection = nil
+          end
+        end
+      end
+
+      def quote_column_name(name) = self.class.quote_column_name(name)
+      def quote_table_name(name) = self.class.quote_table_name(name)
+      def quote_table_name_for_assignment(_table, attr) = quote_column_name(attr)
+      def quote_string(text) = text.gsub("'", "''")
+      def quoted_true = "TRUE"
+      def quoted_false = "FALSE"
+      def unquoted_true = true
+      def unquoted_false = false
+      def quoted_binary(value) = ::Quack::SQL.literal(value.to_s.b)
+      # DuckDB resolves the bare CURRENT_TIMESTAMP keyword as a column inside
+      # ON CONFLICT's update clause; the equivalent function avoids that.
+      def high_precision_current_timestamp = Arel.sql("now()")
+
+      def quote(value)
+        case value
+        when String, BigDecimal, Integer, Float
+          ::Quack::SQL.literal(value)
+        when ::Quack::Interval, ::Quack::TimeOfDay, ::Quack::InfiniteTemporal, Array, Hash
+          ::Quack::SQL.literal(value)
+        when ::Quack::Map, ::Quack::Union, ::Quack::Variant, ::Quack::Tuple, ::Quack::BitString, ::Quack::Geometry
+          ::Quack::SQL.literal(value)
+        else super
+        end
+      end
+
+      def type_cast(value)
+        case value
+        when BigDecimal, ::Quack::Interval, ::Quack::TimeOfDay, ::Quack::InfiniteTemporal, Array, Hash,
+             ::Quack::Map, ::Quack::Union, ::Quack::Variant, ::Quack::Tuple, ::Quack::BitString, ::Quack::Geometry
+          value
+        else super
+        end
+      end
+
+      def quoted_time(value)
+        inner = value.is_a?(Type::Time::Value) ? value.__getobj__ : value
+        inner.is_a?(::Quack::TimeOfDay) ? inner.to_s : super
+      end
+
+      def quoted_date(value)
+        # AbstractAdapter formats only six fractional digits, even for
+        # TIMESTAMP_NS columns. DuckDB accepts all nine from a string bind.
+        return super unless value.is_a?(Time) || value.is_a?(DateTime)
+        normalized = if value.is_a?(Time)
+          default_timezone == :utc ? value.getutc : value.getlocal
+        else
+          (default_timezone == :utc ? value.new_offset(0) : value).new_start(Date::GREGORIAN)
+        end
+        normalized.strftime("%Y-%m-%d %H:%M:%S.%N")
+      end
+
+      def begin_db_transaction
+        internal_execute("BEGIN TRANSACTION", "TRANSACTION", materialize_transactions: false)
+      end
+      def commit_db_transaction
+        internal_execute("COMMIT", "TRANSACTION", materialize_transactions: false)
+      end
+      def exec_rollback_db_transaction
+        internal_execute("ROLLBACK", "TRANSACTION", materialize_transactions: false)
+      end
+      def create_savepoint(*)
+        raise ActiveRecord::StatementInvalid, "DuckDB does not support savepoints"
+      end
+
+      READ_QUERY = AbstractAdapter.build_read_query_regexp(:describe, :show, :summarize, :explain)
+      def write_query?(sql) = !READ_QUERY.match?(sql)
+
+      # Adapted from Active Record's PostgreSQL adapter (MIT licensed).
+      def build_insert_sql(insert)
+        sql = +"INSERT #{insert.into} #{insert.values_list}"
+        if insert.skip_duplicates?
+          sql << " ON CONFLICT #{insert.conflict_target} DO NOTHING"
+        elsif insert.update_duplicates?
+          sql << " ON CONFLICT #{insert.conflict_target} DO UPDATE SET "
+          if insert.raw_update_sql?
+            sql << insert.raw_update_sql
+          else
+            sql << insert.touch_model_timestamps_unless { |column| "#{insert.model.quoted_table_name}.#{column} IS NOT DISTINCT FROM excluded.#{column}" }
+            sql << insert.updatable_columns.map { |column| "#{column}=excluded.#{column}" }.join(",")
+          end
+        end
+        sql << " RETURNING #{insert.returning}" if insert.returning
+        sql
+      end
+
+      def explain(arel, binds = [], _options = [])
+        internal_exec_query("EXPLAIN #{to_sql(arel, binds)}", "EXPLAIN", binds).rows.map(&:last).join("\n")
+      end
+
+      private
+      if ActiveRecord.gem_version >= Gem::Version.new("8.0")
+        def raw_execute(*args, **options)
+          super(*args, **options.merge(allow_retry: false))
+        end
+      end
+      def connect
+        @raw_connection = self.class.new_client(@config)
+      end
+      def reconnect
+        disconnect!
+        connect
+      end
+      def get_database_version
+        raw_connection.info.fetch("server_version").to_s.delete_prefix("v")
+      end
+      def configure_connection
+        super
+        @raw_connection.execute("USE #{quote_table_name(@config[:catalog])}") if @config[:catalog]
+        @raw_connection.execute("SET schema = #{quote(@config[:schema])}") if @config[:schema]
+        @raw_connection.execute("SET TimeZone = 'UTC'")
+      end
+      def perform_query(raw_connection, sql, binds, type_casted_binds, prepare:, notification_payload:, batch: false)
+        # Binds are substituted with the same quoting rules as unprepared SQL.
+        # No Rust pool: the AR pool owns each session and transaction affinity.
+        query = ::Quack::SQL.bind(sql, type_casted_binds.empty? ? nil : type_casted_binds.map { |v| v.is_a?(Type::Binary::Data) ? v.to_s.b : v })
+        result = raw_connection.query(query)
+        verified!
+        notification_payload[:row_count] = result.rows.length
+        notification_payload[:affected_rows] = result.affected_rows
+        result
+      end
+      def cast_result(result)
+        types = {}
+        result.column_metadata.each_with_index do |column, index|
+          types[index] = types[column.fetch("name")] = result_type(column)
+        end
+        ActiveRecord::Result.new(result.columns, result.rows, types)
+      end
+      def affected_rows(result) = result.affected_rows
+      def returning_column_values(result) = result.rows.first
+      def result_type(column)
+        return lookup_cast_type("JSON") if column["alias"]&.casecmp?("JSON")
+        id = column.fetch("type")
+        if id == "Decimal"
+          return lookup_cast_type("DECIMAL(#{column.fetch('precision')},#{column.fetch('scale')})")
+        end
+        sql_type = {"TimestampTz" => "TIMESTAMP", "TimestampTzNs" => "TIMESTAMP", "TimestampSec" => "TIMESTAMP", "TimestampMs" => "TIMESTAMP", "TimestampNs" => "TIMESTAMP", "Double" => "DOUBLE", "SqlNull" => "NULL"}.fetch(id, id.upcase)
+        lookup_cast_type(sql_type)
+      end
+      def translate_exception(exception, message:, sql:, binds:)
+        klass = case exception
+        when ::Quack::ConnectionError, ::Quack::ForkError then ActiveRecord::ConnectionFailed
+        when ::Quack::TimeoutError then ActiveRecord::AdapterTimeout
+        when ::Quack::ServerError
+          case exception.message
+          when /PRIMARY KEY|UNIQUE constraint|Duplicate key/i then ActiveRecord::RecordNotUnique
+          when /NOT NULL constraint/i then ActiveRecord::NotNullViolation
+          when /FOREIGN KEY constraint|violates foreign key/i then ActiveRecord::InvalidForeignKey
+          when /Transaction conflict|Conflict on (?:update|tuple)/i then ActiveRecord::SerializationFailure
+          end
+        end
+        klass ? klass.new(message, sql: sql, binds: binds, connection_pool: @pool) : super
+      end
+    end
+  end
+end

data/lib/active_record/tasks/quack_database_tasks.rb

@@ -0,0 +1,43 @@
+require "active_record/tasks/database_tasks"
+
+module ActiveRecord
+  module Tasks
+    parent = defined?(AbstractTasks) ? AbstractTasks : Object
+    class QuackDatabaseTasks < parent
+      def self.using_database_configurations? = true
+
+      def initialize(config, *)
+        @configuration_hash = config.respond_to?(:configuration_hash) ? config.configuration_hash : config
+        super(config) if defined?(AbstractTasks)
+      end
+
+      def create
+        require "active_record/connection_adapters/quack_adapter"
+        config = @configuration_hash.symbolize_keys
+        connection = ConnectionAdapters::QuackAdapter.new_client(config)
+        begin
+          connection.execute("USE #{ConnectionAdapters::QuackAdapter.quote_table_name(config[:catalog])}") if config[:catalog]
+          connection.execute("SELECT 1")
+        ensure
+          connection.close
+        end
+        # The endpoint's database is provisioned by its server operator.
+        raise ActiveRecord::DatabaseAlreadyExists
+      end
+
+      def drop
+        raise DatabaseNotSupported, "Quack connects to an existing remote database; provision or remove it on the server"
+      end
+      alias purge drop
+
+      def structure_dump(*)
+        raise DatabaseNotSupported, "Quack supports schema.rb; use schema_format = :ruby"
+      end
+      alias structure_load structure_dump
+      def charset = "UTF-8"
+      def collation = nil
+    end
+
+    DatabaseTasks.register_task(/\Aquack\z/, QuackDatabaseTasks)
+  end
+end

data/lib/activerecord-quack-adapter.rb

@@ -0,0 +1,7 @@
+require "active_record"
+require_relative "active_record/tasks/quack_database_tasks"
+
+ActiveRecord::ConnectionAdapters.register(
+  "quack", "ActiveRecord::ConnectionAdapters::QuackAdapter",
+  "active_record/connection_adapters/quack_adapter"
+)

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-quack-adapter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nico
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: quack-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- LICENSE-ActiveRecord
+- README.md
+- lib/active_record/connection_adapters/quack/legacy_database_statements.rb
+- lib/active_record/connection_adapters/quack/schema_dumper.rb
+- lib/active_record/connection_adapters/quack/schema_statements.rb
+- lib/active_record/connection_adapters/quack/value_type.rb
+- lib/active_record/connection_adapters/quack_adapter.rb
+- lib/active_record/tasks/quack_database_tasks.rb
+- lib/activerecord-quack-adapter.rb
+homepage: https://github.com/sidequery/activerecord-quack-adapter
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sidequery/activerecord-quack-adapter
+  bug_tracker_uri: https://github.com/sidequery/activerecord-quack-adapter/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+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: Direct Quack protocol adapter for Active Record
+test_files: []