activerecord-turbopuffer-adapter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89fff3a49b190acd9a305bcd7be04cf0cc5c4880c1c3043ce51925c7a4dafee3
+  data.tar.gz: c03353b5f1b93e25c54b8b70dd3da248beb56aaf8b018b797c1b0aa0a6721f16
+SHA512:
+  metadata.gz: baf2d0855805fb1b4e42839a92221c8983af5d372370a9b2ae86885748716aed1b2c91f4e0c5f6e99afd5c4b20bca172ec3c81464eda9d428723eac07d257926
+  data.tar.gz: 02faeb7bde3748592e604d5fc568e134918a509301b116bbada20cc3f0fa0afb951a7fb247d26607987175eb0539d2d73c771924e584052cd10c52c7608f1c1f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Richard Monette
+
+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,157 @@
+# activerecord-turbopuffer-adapter
+
+[![CI](https://github.com/richardmonette/activerecord-turbopuffer-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/richardmonette/activerecord-turbopuffer-adapter/actions/workflows/ci.yml)
+
+activerecord-turbopuffer-adapter is an unofficial, fan made Ruby on Rails ActiveRecord database adapter for turbopuffer. If you are looking for the official turbopuffer Ruby gem see: https://github.com/turbopuffer/turbopuffer-ruby
+
+The purpose of this gem is to provide Rails developers a familiar ActiveRecord style interface to turbopuffer.
+
+## Installation
+
+To use this gem, install via Bundler by adding the following to your application's Gemfile:
+
+```ruby
+gem 'activerecord-turbopuffer-adapter'
+```
+
+## Usage
+
+### Configuration
+
+In `config/database.yml` define a turbopuffer adapter:
+
+
+```yaml
+development:
+  adapter: turbopuffer
+  region: gcp-us-central1
+  api_key: <%= ENV["TURBOPUFFER_API_KEY"] %>
+  database_tasks: false
+```
+
+Optionally, you can define `namespace_prefix`, which is useful for separating namespaces for production and development environments.
+
+### Defining a model
+
+```ruby
+class Document < ApplicationRecord
+  turbopuffer_attribute "id",        "uuid",   not_null: 1
+  turbopuffer_attribute "title",     "string", filterable: true
+  turbopuffer_attribute "body",      "string", full_text_search: true
+  turbopuffer_attribute "published", "bool",   filterable: true
+  turbopuffer_attribute "embedding", "[1536]f32", ann: true
+end
+```
+
+By default the namespace is the model's table_name, but it can be customized with `self.table_name = "..."` Currently, ids are always UUIDv7 (which sort chronologically, to support pagination.)
+
+The distance metric applies to all vector columns in a namespace and defaults to `cosine_distance`. To use `euclidean_squared` instead, declare it in the model:
+
+```ruby
+class Document < ApplicationRecord
+  turbopuffer_distance_metric "euclidean_squared"
+
+  turbopuffer_attribute "id",        "uuid",      not_null: 1
+  turbopuffer_attribute "embedding", "[1536]f32", ann: true
+end
+```
+
+### Creating records
+
+```ruby
+Document.create!(title: "Hello", body: "...", published: true)
+
+doc = Document.new(title: "Draft")
+doc.save!
+
+doc.update!(published: true)
+doc.destroy
+```
+
+> Note that inserts are treated as upserts, such that writing a row whose id already exists is effectively treated as an update.
+
+> Note that transactions are not supported, interacting with that portion of the ActiveRecord API is no-op
+
+To avoid N+1s you can use insert_all/upsert_all.
+
+```ruby
+Document.insert_all(
+  documents.map { |doc| { title: doc.title, body: doc.body, body_embedding: doc.embedding } }
+)
+```
+
+### Querying
+
+```ruby
+Document.where(published: true)
+Document.where(id: ["a", "b"])
+Document.where.not(id: ["a", "b"])
+Document.where(created_at: 1.week.ago..)
+
+Document.where(title: /^walrus/i)
+Document.where(title: Document.glob("walrus*"))
+
+Document.where(tags: "walrus")
+Document.where(tags: ["walrus", "narwhal"])
+Document.where.not(tags: "walrus")
+Document.where(tags: nil)
+Document.where(scores: 90..)
+
+Document.order(:title).limit(20)
+Document.group(:title).count
+Document.count
+Document.find("018f...")
+
+Document.rank_by("vector", "ANN", query_vector).limit(10)
+Document.rank_by("text", "BM25", "quick walrus").limit(10)
+
+Document
+  .where(published: true)
+  .rank_by(["Sum", [
+    ["Product", 2, ["category", "BM25", "mammal"]],
+    ["text", "BM25", "quick walrus"],
+  ]])
+  .limit(10)
+```
+
+> Note that turbopuffer has a limit on the maximum number of documents returned (https://turbopuffer.com/docs/query#param-limit), so Document.all.to_a etc. will only return at most 10,000 items
+
+### Using alongside Postgres
+
+While something of a lark, aspirationally the idea of this gem is to make turbopuffer conveniently usable as the primary db in a Rails app. In practice, however, using turbopuffer alongside a traditional primary db (such as postgres) is a supported, potentially more practical solution.
+
+A dual db approach can be setup as follows:
+
+```yaml
+development:
+  primary:
+    adapter: postgresql
+    database: myapp_development
+  turbopuffer:
+    adapter: turbopuffer
+    region: gcp-us-central1
+    api_key: <%= ENV["TURBOPUFFER_API_KEY"] %>
+    namespace_prefix: myapp-development
+    database_tasks: false
+```
+
+```ruby
+class TurbopufferRecord < ApplicationRecord
+  self.abstract_class = true
+
+  connects_to database: { writing: :turbopuffer, reading: :turbopuffer }
+end
+
+class Document < TurbopufferRecord
+  turbopuffer_attribute "id",   "uuid",   not_null: 1
+  turbopuffer_attribute "body", "string", full_text_search: true
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/richardmonette/activerecord-turbopuffer-adapter. As this is an unofficial gem, please do not report bugs upstream.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/active_record/connection_adapters/turbopuffer_adapter.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+require "turbopuffer"
+
+require "arel/visitors/turbopuffer"
+require "turbopuffer/active_record/schema"
+require "turbopuffer/active_record/type"
+
+module ActiveRecord
+  module ConnectionAdapters
+    class CachedQuery < ActiveRecord::StatementCache::Query
+      def initialize(ast, visitor)
+        @ast, @visitor, @retryable = ast, visitor, true
+      end
+
+      def sql_for(binds, connection)
+        @visitor.compile(@ast, bound_values: binds).first
+      end
+    end
+
+    class TurbopufferAdapter < AbstractAdapter
+      ADAPTER_NAME = "Turbopuffer"
+
+      class << self
+        private
+
+        def initialize_type_map(m)
+          m.register_type "string",   Type::String.new
+          m.register_type "uuid",     Type::String.new
+          m.register_type "int",      Type::Integer.new(limit: 8)
+          m.register_type "uint",     ::Turbopuffer::ActiveRecord::Type::UnsignedInteger.new(limit: 8)
+          m.register_type "float",    Type::Float.new
+          m.register_type "bool",     Type::Boolean.new
+          m.register_type "datetime", ::Turbopuffer::ActiveRecord::Type::DateTime.new
+          m.register_type(%r{\A\[\].+\z}) do |type|
+            ::Turbopuffer::ActiveRecord::Type::Array.new(m.lookup(type.delete_prefix("[]")))
+          end
+          m.register_type(%r{\A\[\d+\]f(?:16|32)\z}) do |type|
+            ::Turbopuffer::ActiveRecord::Type::Vector.new(type[/\d+/].to_i)
+          end
+        end
+      end
+
+      TYPE_MAP = Type::TypeMap.new.tap { |m| initialize_type_map(m) }
+      EXTENDED_TYPE_MAPS = Concurrent::Map.new
+
+      def column_definitions(table_name)
+        ::Turbopuffer::ActiveRecord::Schema::Model.for_table(table_name).turbopuffer_attributes
+      end
+
+      def tables
+        ::Turbopuffer::ActiveRecord::Schema::Model.namespaces.map(&:table_name).uniq
+      end
+      def views = []
+      def data_sources = tables
+      def table_exists?(name) = tables.include?(name.to_s)
+      def data_source_exists?(name) = table_exists?(name)
+
+      def supports_insert_on_duplicate_skip? = true
+      def supports_insert_on_duplicate_update? = true
+
+      def supports_savepoints? = false
+      def supports_ddl_transactions? = false
+      def supports_transaction_isolation? = false
+      def supports_lazy_transactions? = false
+      def supports_restart_db_transaction? = false
+      def supports_advisory_locks? = false
+
+      def begin_db_transaction = nil
+      def commit_db_transaction   = nil
+      def exec_rollback_db_transaction = nil
+      def create_savepoint(name = nil)          = nil
+      def exec_rollback_to_savepoint(name = nil) = nil
+      def release_savepoint(name = nil)          = nil
+
+      def begin_isolated_db_transaction(isolation)
+        raise ActiveRecord::TransactionIsolationError, "Turbopuffer does not support isolation levels"
+      end
+
+      def primary_key(table_name)
+        "id"
+      end
+
+      def default_insert_value(column)
+        nil
+      end
+
+      def self.quote_column_name(name) = name.to_s
+
+      def view_exists?(name) = false
+
+      def write_query?(sql)
+        query = sql.is_a?(Array) ? sql.first : sql
+        query.op != :select
+      end
+
+      def type_cast(value)
+        case value
+        when Array
+          value
+        else
+          super
+        end
+      end
+
+      def new_column_from_field(table_name, field, definitions)
+        Column.new(field.name, lookup_cast_type(field.type), nil, nil, field.notnull.to_i == 0)
+      end
+
+      def build_insert_sql(insert)
+        columns = insert.keys_including_timestamps.to_a
+        rows, _binds = insert.values_list
+
+        upsert_rows = rows.map do |row|
+          attributes = columns.zip(row).to_h
+          attributes["id"] ||= SecureRandom.uuid_v7
+          attributes
+        end
+
+        Arel::Visitors::TurbopufferQuery.new(
+          op:          :insert,
+          namespace:   insert.model.table_name,
+          upsert_rows: upsert_rows
+        )
+      end
+
+      def high_precision_current_timestamp
+        ::Time.current
+      end
+
+      def cacheable_query(klass, arel)
+        _discarded, binds = visitor.compile(arel.ast, collecting_binds: true)   # only needed to build the BindMap
+        [ CachedQuery.new(arel.ast, visitor), binds ]
+      end
+
+      TurbopufferResult = Struct.new(:fields, :rows, :affected_rows, keyword_init: true) do
+        def self.affected(count) = new(fields: [], rows: [], affected_rows: count)
+      end
+
+      def turbopuffer_insert(namespace, query)
+        table_name = query.namespace
+        model = ::Turbopuffer::ActiveRecord::Schema::Model.for_table(table_name)
+
+        tpuf_insert_args = {
+          upsert_rows: query.upsert_rows,
+          schema: model.turbopuffer_schema_hash
+        }
+
+        if model.turbopuffer_attributes.any?(&:ann)
+          tpuf_insert_args[:distance_metric] = model.turbopuffer_distance_metric
+        end
+
+        tpuf_result = namespace.write(tpuf_insert_args)
+
+        fields = column_definitions(table_name).map(&:name)
+        rows = query.upsert_rows.map { |r| fields.map { |f| r[f] } }
+
+        TurbopufferResult.new(fields: fields, rows: rows, affected_rows: tpuf_result.rows_affected)
+      end
+
+      def turbopuffer_update(namespace, query)
+        patch = query.upsert_rows.to_h
+        pending = pending_patch_filter(patch)
+        filters = query.filters ? [ "And", [ query.filters, pending ] ] : pending
+
+        affected = write_in_batches(
+          namespace,
+          patch_by_filter: { filters: filters, patch: patch.transform_keys(&:to_sym) },
+          patch_by_filter_allow_partial: true
+        )
+
+        TurbopufferResult.affected(affected)
+      end
+
+      def write_in_batches(namespace, args)
+        affected = 0
+
+        loop do
+          tpuf_result = namespace.write(args)
+          affected += tpuf_result.rows_affected
+
+          break unless tpuf_result.rows_remaining
+
+          if tpuf_result.rows_affected.zero?
+            raise ActiveRecord::StatementInvalid, "write made no progress: rows still match #{args.inspect}"
+          end
+        end
+
+        affected
+      end
+
+      def pending_patch_filter(patch)
+        conditions = patch.flat_map do |attribute, value|
+          if value.nil?
+            [ [ attribute, "NotEq", nil ] ]
+          else
+            [ [ attribute, "NotEq", value ], [ attribute, "Eq", nil ] ]
+          end
+        end
+
+        [ "Or", conditions ]
+      end
+
+      def turbopuffer_delete(namespace, query)
+        attribute, operator, value = query.filters
+
+        affected = if query.filters.nil?
+          turbopuffer_delete_namespace(namespace)
+        elsif attribute == "id" && operator == "Eq"
+          namespace.write(deletes: [ value ]).rows_affected
+        elsif attribute == "id" && operator == "In"
+          namespace.write(deletes: value).rows_affected
+        else
+          write_in_batches(namespace, delete_by_filter: query.filters, delete_by_filter_allow_partial: true)
+        end
+
+        TurbopufferResult.affected(affected)
+      end
+
+      def turbopuffer_delete_namespace(namespace)
+        count = namespace.query(aggregate_by: { count: [ "Count" ] }).aggregations[:count]
+        namespace.delete_all
+        count
+      rescue Turbopuffer::Errors::NotFoundError
+        0
+      end
+
+      def turbopuffer_aggregate(namespace, query)
+        aggregate_alias, aggregate = query.aggregate_by
+
+        tpuf_query_args = {
+          aggregate_by: { aggregate_alias => aggregate }
+        }
+
+        tpuf_query_args[:filters] = query.filters if query.filters
+
+        if query.group_by.present?
+          tpuf_query_args[:group_by] = query.group_by
+          tpuf_query_args[:top_k] = query.top_k if query.top_k.present?
+        end
+
+        result = namespace.query(tpuf_query_args)
+
+        if query.group_by.present?
+          fields = query.group_by + [ aggregate_alias ]
+          rows = result.aggregation_groups.map(&:to_h).map { |g| fields.map { |f| g[f.to_sym] } }
+
+          TurbopufferResult.new(fields:, rows:, affected_rows: 0)
+        else
+          count = result.aggregations[aggregate_alias.to_sym]
+
+          TurbopufferResult.new(fields: [ aggregate_alias ], rows: [ [ count ] ], affected_rows: 0)
+        end
+      rescue Turbopuffer::Errors::NotFoundError
+        TurbopufferResult.affected(0)
+      end
+
+      def turbopuffer_select(namespace, query)
+        fields = if query.include_attributes == [ "*" ]
+          column_definitions(query.namespace).map(&:name)
+        else
+          query.include_attributes
+        end
+
+        tpuf_query_args = {
+          include_attributes: fields,
+          top_k: query.top_k.present? ? query.top_k : 10_000
+        }
+
+        tpuf_query_args[:rank_by] = query.rank_by.first if query.rank_by.present?
+        tpuf_query_args[:filters] = query.filters if query.filters
+
+        tpuf_result = namespace.query(tpuf_query_args)
+
+        rows = tpuf_result.rows.map(&:to_h).map { |r| fields.map { |f| r[f.to_sym] } }
+
+        TurbopufferResult.new(fields:, rows:, affected_rows: 0)
+      rescue Turbopuffer::Errors::NotFoundError
+        TurbopufferResult.affected(0)
+      end
+
+      def perform_query(raw_connection, sql, binds, type_casted_binds, prepare:, notification_payload:, batch:)
+        tpuf_query = sql.is_a?(Array) ? sql.first : sql
+
+        namespace_name = [ @config[:namespace_prefix], tpuf_query.namespace ].compact_blank.join("-")
+        namespace = raw_connection.namespace(namespace_name)
+
+        result = case tpuf_query.op
+        when :insert then turbopuffer_insert(namespace, tpuf_query)
+        when :update then turbopuffer_update(namespace, tpuf_query)
+        when :delete then turbopuffer_delete(namespace, tpuf_query)
+        when :select
+          if tpuf_query.aggregate_by
+            turbopuffer_aggregate(namespace, tpuf_query)
+          else
+            turbopuffer_select(namespace, tpuf_query)
+          end
+        end
+
+        notification_payload[:row_count] = result.rows.size
+        result
+      end
+
+      def arel_visitor
+        Arel::Visitors::Turbopuffer.new
+      end
+
+      def cast_result(result)
+        if result.fields.empty?
+          ActiveRecord::Result.empty(affected_rows: result.affected_rows)
+        else
+          ActiveRecord::Result.new(result.fields, result.rows, affected_rows: result.affected_rows)
+        end
+      end
+
+      def prefetch_primary_key?(table_name = nil)
+        true
+      end
+
+      def next_sequence_value(sequence_name)
+        SecureRandom.uuid_v7
+      end
+
+      def affected_rows(result)
+        result.affected_rows
+      end
+
+      def get_full_version
+        Turbopuffer::VERSION
+      end
+
+      def active?
+        connected?
+      end
+
+      def connect
+        @raw_connection = Turbopuffer::Client.new(
+          region: @config[:region],
+          api_key: @config[:api_key]
+        )
+      end
+
+      def disconnect!
+        @raw_connection = nil
+      end
+
+      def requires_reloading? = false
+
+      private
+
+      def reconnect
+        connect
+      end
+    end
+  end
+end

data/lib/activerecord-turbopuffer-adapter.rb

@@ -0,0 +1 @@
+require "turbopuffer/active_record"

data/lib/arel/nodes/glob.rb

@@ -0,0 +1,15 @@
+module Arel::Nodes
+  class Glob < Arel::Nodes::Binary
+    attr_reader :case_sensitive
+
+    def initialize(left, right, case_sensitive: true)
+      super(left, right)
+      @case_sensitive = case_sensitive
+    end
+
+    def hash = [ self.class, left, right, case_sensitive ].hash
+
+    def eql?(other) = super && case_sensitive == other.case_sensitive
+    alias == eql?
+  end
+end

data/lib/arel/nodes/rank_by_node.rb

@@ -0,0 +1,15 @@
+module Arel::Nodes
+  class RankByNode < Arel::Nodes::Unary
+    attr_reader :expression
+
+    def initialize(*expression)
+      @expression = expression.size == 1 ? expression.first : expression
+      super(nil)
+    end
+
+    def hash = [ self.class, expression ].hash
+
+    def eql?(other) = self.class == other.class && expression == other.expression
+    alias == eql?
+  end
+end

data/lib/arel/visitors/turbopuffer.rb

@@ -0,0 +1,280 @@
+module Arel::Visitors
+  class TurbopufferQuery
+    def to_h
+      {
+        op: @op,
+        namespace: @namespace,
+        filters: @filters,
+        group_by: @group_by,
+        top_k: @top_k,
+        rank_by: @rank_by,
+        include_attributes: @include_attributes,
+        aggregate_by: @aggregate_by,
+        upsert_rows: @upsert_rows
+      }
+    end
+    def to_s = JSON.generate(to_h)
+    alias inspect to_s
+    def hash = to_h.hash
+    def eql?(other) = other.is_a?(self.class) && to_h == other.to_h
+    alias == eql?
+
+    attr_reader :op, :namespace, :filters, :top_k, :rank_by, :include_attributes, :upsert_rows, :aggregate_by, :group_by
+
+    def initialize(op:, namespace:, filters: nil, top_k: nil, rank_by: nil,
+                   include_attributes: nil, upsert_rows: nil, aggregate_by: nil, group_by: nil)
+      @op = op
+      @namespace = namespace
+      @filters = filters
+      @top_k = top_k
+      @rank_by = rank_by
+      @include_attributes = include_attributes
+      @aggregate_by = aggregate_by
+      @group_by = group_by
+      @upsert_rows = upsert_rows
+    end
+  end
+
+  class Turbopuffer < Arel::Visitors::Visitor
+    def initialize
+      super
+      @binds = []
+    end
+
+    attr_accessor :binds
+
+    def compile(node, _collector = nil, bound_values: nil, collecting_binds: false)
+      @binds = []
+      @bound_values = bound_values
+      @collecting_binds = collecting_binds
+      [ visit(node), @binds ]
+    ensure
+      @bound_values = nil
+      @collecting_binds = false
+    end
+
+    private
+
+    def conjoin(filters)
+      case filters.size
+      when 0 then nil
+      when 1 then filters.first
+      else [ "And", filters ]
+      end
+    end
+
+    def aggregate_node(projection)
+      projection.is_a?(Arel::Nodes::As) ? projection.left : projection
+    end
+
+    def aggregate?(projection)
+      aggregate_node(projection).is_a?(Arel::Nodes::Function)
+    end
+
+    def counted_attribute(projection)
+      node = aggregate_node(projection)
+      return unless node.is_a?(Arel::Nodes::Count)
+
+      expression = node.expressions.first
+      expression if expression.is_a?(Arel::Attributes::Attribute)
+    end
+
+    def aggregate_for(o)
+      raise NotImplementedError, "distinct is not implemented yet" if o.distinct
+
+      case o
+      when Arel::Nodes::Count then [ "Count" ]
+      when Arel::Nodes::Sum then [ "Sum", visit(o.expressions.first) ]
+      else
+        raise NotImplementedError, "#{o.class.name.demodulize} is not supported, turbopuffer aggregates are Count and Sum"
+      end
+    end
+
+    def visit_Arel_Nodes_SelectStatement(o)
+      raise NotImplementedError, "offset is not supported, filter on a sortable attribute for cursor pagination" if o.offset
+      # https://turbopuffer.com/docs/query#ordering-by-attributes: "Ordering by
+      # multiple attributes isn't yet implemented."
+      raise NotImplementedError, "one ranking per query, sort in Ruby after loading" if o.orders.size > 1
+
+      core = o.cores.last
+
+      raise NotImplementedError, "distinct is not implemented yet" if core.set_quantifier
+      raise NotImplementedError, "having is not implemented yet" if core.havings.any?
+
+      aggregates, attributes = core.projections.partition { |p| aggregate?(p) }
+      aggregate = aggregates.first
+
+      filters = core.wheres.map { |w| visit(w) }
+      counted = aggregate && counted_attribute(aggregate)
+      filters << [ visit(counted), "NotEq", nil ] if counted
+
+      TurbopufferQuery.new(
+        op:                 :select,
+        namespace:          visit(core.source),
+        filters:            conjoin(filters),
+        top_k:              o.limit && visit(o.limit),
+        rank_by:            o.orders.map { |ord| visit(ord) },
+        include_attributes: attributes.flat_map { |p| visit(p) },
+        group_by:           core.groups.map { |g| visit(g) },
+        aggregate_by:       aggregate && visit(aggregate)
+      )
+    end
+
+    def visit_Arel_Nodes_InsertStatement(o)
+      raise NotImplementedError, "INSERT ... SELECT" if o.select
+
+      columns = o.columns.map { |c| visit(c) }
+      rows    = o.values ? visit(o.values) : [ [] ]
+
+      TurbopufferQuery.new(
+        op:          :insert,
+        namespace:   visit(o.relation),
+        upsert_rows: rows.map { |row| columns.zip(row).to_h }
+      )
+    end
+
+    def visit_Arel_Nodes_UpdateStatement(o)
+      rows = o.values ? visit(o.values) : [ [] ]
+
+      TurbopufferQuery.new(
+        op:          :update,
+        namespace:   visit(o.relation),
+        filters:     conjoin(o.wheres.map { |w| visit(w) }),
+        upsert_rows: rows
+      )
+    end
+
+    def visit_Arel_Nodes_DeleteStatement(o)
+      TurbopufferQuery.new(
+        op:        :delete,
+        namespace: visit(o.relation),
+        filters:   conjoin(o.wheres.map { |w| visit(w) })
+      )
+    end
+
+    def visit_ActiveModel_Attribute(o)
+      @binds << o
+
+      attribute = @bound_values ? @bound_values[@binds.size - 1] : o
+
+      if ActiveRecord::StatementCache::Substitute === attribute.value_before_type_cast
+        return nil if @collecting_binds
+        raise "unbound statement-cache placeholder for #{o.name.inspect}"
+      end
+
+      attribute.value_for_database
+    end
+    alias visit_ActiveRecord_Relation_QueryAttribute visit_ActiveModel_Attribute
+
+    def visit_Arel_Nodes_BindParam(o)
+      visit(o.value)
+    end
+
+    def visit_Arel_Nodes_ValuesList(o)
+      o.rows.map { |row| row.map { |v| visit(v) } }
+    end
+
+    def visit_Arel_Nodes_JoinSource(o)
+      raise NotImplementedError, "turbopuffer has no joins" if o.right.any?
+      visit(o.left)
+    end
+
+    def visit_Arel_Table(o) = o.name
+
+    # filters
+    def visit_Arel_Nodes_And(o)      = [ "And", o.children.map { |c| visit(c) } ]
+    def visit_Arel_Nodes_Or(o)       = [ "Or", [ visit(o.left), visit(o.right) ] ]
+    def visit_Arel_Nodes_Grouping(o) = visit(o.expr)
+
+    def visit_Arel_Nodes_UnqualifiedColumn(o)
+      visit o.expr
+    end
+
+    def visit_Arel_Nodes_Assignment(o)
+      [ visit(o.left), visit(o.right) ]
+    end
+
+    ARRAY_OPERATORS = {
+      "Eq" => "Contains", "NotEq" => "NotContains",
+      "In" => "ContainsAny", "NotIn" => "NotContainsAny",
+      "Lt" => "AnyLt", "Lte" => "AnyLte", "Gt" => "AnyGt", "Gte" => "AnyGte"
+    }.freeze
+
+    def comparison(node, operator, value = visit(node.right))
+      operator = ARRAY_OPERATORS.fetch(operator) if array_attribute?(node.left) && !value.nil?
+
+      [ visit(node.left), operator, value ]
+    end
+
+    def array_attribute?(node)
+      node.is_a?(Arel::Attributes::Attribute) &&
+        node.able_to_type_cast? &&
+        node.type_caster.is_a?(::Turbopuffer::ActiveRecord::Type::Array)
+    end
+
+    def visit_Arel_Nodes_Equality(o)           = comparison(o, "Eq")
+    def visit_Arel_Nodes_NotEqual(o)           = comparison(o, "NotEq")
+    def visit_Arel_Nodes_GreaterThan(o)        = comparison(o, "Gt")
+    def visit_Arel_Nodes_GreaterThanOrEqual(o) = comparison(o, "Gte")
+    def visit_Arel_Nodes_LessThan(o)           = comparison(o, "Lt")
+    def visit_Arel_Nodes_LessThanOrEqual(o)    = comparison(o, "Lte")
+    def visit_Arel_Nodes_In(o)                 = comparison(o, "In")
+
+    def visit_Arel_Nodes_HomogeneousIn(o)
+      comparison(o, o.type == :in ? "In" : "NotIn", o.casted_values)
+    end
+
+    def visit_Arel_Nodes_Between(o)
+      low, high = o.right.children.map { |bound| visit(bound) }
+
+      [ "And", [ comparison(o, "Gte", low), comparison(o, "Lte", high) ] ]
+    end
+
+    def visit_Arel_Nodes_Not(o) = [ "Not", visit(o.expr) ]
+
+    def visit_Arel_Nodes_Regexp(o)
+      pattern = visit(o.right)
+
+      [ visit(o.left), "Regex", o.case_sensitive ? pattern : "(?i)#{pattern}" ]
+    end
+
+    def visit_Arel_Nodes_NotRegexp(o) = [ "Not", visit_Arel_Nodes_Regexp(o) ]
+
+    def visit_Arel_Nodes_Glob(o) = [ visit(o.left), o.case_sensitive ? "Glob" : "IGlob", visit(o.right) ]
+
+    def visit_Arel_Nodes_Count(o)    = [ "count_all", aggregate_for(o) ]
+    def visit_Arel_Nodes_Sum(o)      = [ "sum_#{visit(o.expressions.first)}", aggregate_for(o) ]
+    def visit_Arel_Nodes_Function(o) = aggregate_for(o)
+
+    def visit_Arel_Nodes_As(o)
+      aggregate?(o) ? [ o.right.to_s, aggregate_for(o.left) ] : visit(o.left)
+    end
+
+    def visit_Arel_Nodes_Group(o) = visit(o.expr)
+
+    # leaves — this is where binds get resolved
+    def visit_Arel_Attributes_Attribute(o) = o.name.to_s
+    def visit_Arel_Nodes_Casted(o)         = o.value_for_database
+    def visit_Arel_Nodes_Quoted(o)         = o.expr
+    def visit_Arel_Nodes_Limit(o)          = visit(o.expr)
+    def visit_Arel_Nodes_Ascending(o)      = [ visit(o.expr), "asc" ]
+    def visit_Arel_Nodes_Descending(o)     = [ visit(o.expr), "desc" ]
+
+    def visit_Arel_Nodes_RankByNode(o) = o.expression
+
+    def visit_Arel_Nodes_SqlLiteral(o)
+      return "id" if o == ActiveRecord::FinderMethods::ONE_AS_ONE
+
+      raise NotImplementedError, "raw SQL is not supported: #{o}"
+    end
+    def visit_Arel_Nodes_BoundSqlLiteral(o) = raise(NotImplementedError, "raw SQL is not supported: #{o.sql_with_placeholders}")
+
+    def visit_Array(o)   = o.map { |x| visit(x) }
+    def visit_Integer(o) = o
+    def visit_Float(o)   = o
+    def visit_String(o)  = o
+    def visit_TrueClass(o)  = o
+    def visit_FalseClass(o) = o
+    def visit_NilClass(_) = nil
+  end
+end

data/lib/turbopuffer/active_record/glob.rb

@@ -0,0 +1,12 @@
+module Turbopuffer
+  module ActiveRecord
+    class Glob
+      attr_reader :pattern, :case_sensitive
+
+      def initialize(pattern, case_sensitive: true)
+        @pattern = pattern
+        @case_sensitive = case_sensitive
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/railtie.rb

@@ -0,0 +1,19 @@
+require "rails/railtie"
+
+module Turbopuffer
+  module ActiveRecord
+    class Railtie < ::Rails::Railtie
+      initializer "turbopuffer.register_adapter", before: "active_record.initialize_database" do
+        ::Turbopuffer::ActiveRecord.register_adapter!
+      end
+
+      initializer "turbopuffer.model_extensions" do
+        ActiveSupport.on_load(:active_record) do
+          require "turbopuffer/active_record/schema"
+
+          include ::Turbopuffer::ActiveRecord::Schema::Model
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/schema/attribute.rb

@@ -0,0 +1,30 @@
+module Turbopuffer
+  module ActiveRecord
+    module Schema
+      class Attribute
+        TYPES = %r{\A(?:\[\])?(?:string|uuid|int|uint|float|bool|datetime)\z|\A\[\d+\]f(?:16|32)\z}
+
+        attr_reader :name, :type, :filterable, :full_text_search, :ann, :glob, :regex, :notnull
+
+        def initialize(name, type, not_null: 0, filterable: false, full_text_search: false,
+                       ann: false, glob: false, regex: false)
+          type = type.to_s
+
+          unless TYPES.match?(type)
+            raise ArgumentError, "unknown turbopuffer type #{type.inspect} for attribute #{name.inspect}"
+          end
+
+          @name = name
+          @type = type
+          @filterable = filterable
+          @full_text_search = full_text_search
+          @ann = ann
+          @glob = glob
+          @regex = regex
+
+          @notnull = not_null
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/schema/model.rb

@@ -0,0 +1,101 @@
+module Turbopuffer
+  module ActiveRecord
+    module Schema
+      module Model
+        extend ActiveSupport::Concern
+
+        DISTANCE_METRICS = [ "cosine_distance", "euclidean_squared" ].freeze
+
+        included do
+          class_attribute :turbopuffer_attributes,        instance_accessor: false, default: [].freeze
+          class_attribute :_turbopuffer_distance_metric,  instance_accessor: false, default: "cosine_distance"
+        end
+
+        class << self
+          def namespaces
+            ::ActiveRecord::Base.descendants.select do |model|
+              model.respond_to?(:turbopuffer_namespace?) &&
+                !model.abstract_class? &&
+                model.turbopuffer_namespace?
+            end
+          end
+
+          def for_table(table_name)
+            model = namespaces.find { |m| m.table_name == table_name }
+
+            unless model
+              raise UnknownNamespace,
+                "No turbopuffer namespace registered for #{table_name.inspect}. " \
+                "Declare attributes in the model with `turbopuffer_attribute`. " \
+                "Registered: #{namespaces.map(&:table_name).sort.join(", ")}"
+            end
+
+            model
+          end
+        end
+
+        class_methods do
+          def turbopuffer_attribute(name, type, not_null: 0, filterable: false,
+                                    full_text_search: false, ann: false, glob: false, regex: false)
+            attribute = ::Turbopuffer::ActiveRecord::Schema::Attribute.new(
+              name.to_s, type, not_null:, filterable:, full_text_search:, ann:, glob:, regex:
+            )
+
+            self.turbopuffer_attributes =
+              (turbopuffer_attributes.reject { |a| a.name == attribute.name } + [ attribute ]).freeze
+
+            attribute
+          end
+
+          def turbopuffer_distance_metric(value = nil)
+            return _turbopuffer_distance_metric if value.nil?
+
+            unless DISTANCE_METRICS.include?(value)
+              raise ArgumentError,
+                "distance metric must be one of #{DISTANCE_METRICS.join(", ")}, got #{value.inspect}"
+            end
+
+            self._turbopuffer_distance_metric = value
+          end
+
+          def rank_by(*expression)
+            expression = expression.first if expression.size == 1
+            order(::Arel::Nodes::RankByNode.new(expression))
+          end
+
+          def glob(pattern, case_sensitive: true)
+            ::Turbopuffer::ActiveRecord::Glob.new(pattern, case_sensitive:)
+          end
+
+          def predicate_builder
+            @predicate_builder ||= super.tap do |builder|
+              builder.register_handler(::Regexp, lambda { |attribute, regexp|
+                ::Arel::Nodes::Regexp.new(attribute, ::Arel::Nodes.build_quoted(regexp.source), !regexp.casefold?)
+              })
+
+              builder.register_handler(::Turbopuffer::ActiveRecord::Glob, lambda { |attribute, glob|
+                ::Arel::Nodes::Glob.new(attribute, ::Arel::Nodes.build_quoted(glob.pattern), case_sensitive: glob.case_sensitive)
+              })
+            end
+          end
+
+          def turbopuffer_namespace? = turbopuffer_attributes.any?
+
+          def turbopuffer_schema_hash
+            turbopuffer_attributes.each_with_object({}) do |attribute, schema|
+              attrs = { type: attribute.type }
+
+              attrs[:filterable] = true if attribute.filterable
+              attrs[:full_text_search] = true if attribute.full_text_search
+              attrs[:ann] = true if attribute.ann
+              attrs[:glob] = true if attribute.glob
+              attrs[:regex] = true if attribute.regex
+
+              schema[attribute.name] = attrs
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/schema.rb

@@ -0,0 +1,13 @@
+require "arel/nodes/glob"
+require "arel/nodes/rank_by_node"
+require "turbopuffer/active_record/glob"
+require "turbopuffer/active_record/schema/attribute"
+require "turbopuffer/active_record/schema/model"
+
+module Turbopuffer
+  module ActiveRecord
+    module Schema
+      class UnknownNamespace < StandardError; end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type/array.rb

@@ -0,0 +1,30 @@
+module Turbopuffer
+  module ActiveRecord
+    module Type
+      class Array < ::ActiveModel::Type::Value
+        include ::ActiveModel::Type::Helpers::Mutable
+
+        def initialize(element_type)
+          @element_type = element_type
+          super()
+        end
+
+        def serialize(value)
+          case value
+          when nil then nil
+          when ::Array then value.map { |element| @element_type.serialize(element) }
+          else @element_type.serialize(value)
+          end
+        end
+
+        def deserialize(value)
+          case value
+          when nil then nil
+          when ::Array then value.map { |element| @element_type.deserialize(element) }
+          else @element_type.deserialize(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type/date_time.rb

@@ -0,0 +1,19 @@
+module Turbopuffer
+  module ActiveRecord
+    module Type
+      class DateTime < ::ActiveRecord::Type::DateTime
+        def serialize(value)
+          casted = cast(value)
+
+          if casted.respond_to?(:utc)
+            casted.utc.iso8601
+          elsif casted.is_a?(::Date)
+            ::Time.utc(casted.year, casted.month, casted.day).iso8601
+          else
+            casted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type/unsigned_integer.rb

@@ -0,0 +1,12 @@
+module Turbopuffer
+  module ActiveRecord
+    module Type
+      class UnsignedInteger < ::ActiveRecord::Type::Integer
+        private
+
+        def max_value = 1 << 64
+        def min_value = 0
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type/vector.rb

@@ -0,0 +1,30 @@
+module Turbopuffer
+  module ActiveRecord
+    module Type
+      class Vector < ::ActiveModel::Type::Value
+        include ::ActiveModel::Type::Helpers::Mutable
+
+        def initialize(dimensions)
+          @dimensions = dimensions
+          super()
+        end
+
+        def serialize(value)
+          return if value.nil?
+
+          vector = ::Array.wrap(value).map { |component| Float(component) }
+
+          unless vector.size == @dimensions
+            raise ArgumentError, "expected a vector of #{@dimensions} dimensions, got #{vector.size}"
+          end
+
+          vector
+        end
+
+        def deserialize(value)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/active_record/type.rb

@@ -0,0 +1,11 @@
+require "turbopuffer/active_record/type/date_time"
+require "turbopuffer/active_record/type/unsigned_integer"
+require "turbopuffer/active_record/type/array"
+require "turbopuffer/active_record/type/vector"
+
+module Turbopuffer
+  module ActiveRecord
+    module Type
+    end
+  end
+end

data/lib/turbopuffer/active_record/version.rb

@@ -0,0 +1,5 @@
+module Turbopuffer
+  module ActiveRecord
+    VERSION = "0.1.0"
+  end
+end

data/lib/turbopuffer/active_record.rb

@@ -0,0 +1,20 @@
+require "turbopuffer/active_record/version"
+
+module Turbopuffer
+  module ActiveRecord
+    class Error < StandardError; end
+
+    # Teaches Active Record that `adapter: turbopuffer` in database.yml maps to
+    # our adapter. The railtie calls this during boot; test harnesses and
+    # non-Rails consumers call it themselves.
+    def self.register_adapter!
+      ::ActiveRecord::ConnectionAdapters.register(
+        "turbopuffer",
+        "ActiveRecord::ConnectionAdapters::TurbopufferAdapter",
+        "active_record/connection_adapters/turbopuffer_adapter"
+      )
+    end
+  end
+end
+
+require "turbopuffer/active_record/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-turbopuffer-adapter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Richard Monette
+bindir: bin
+cert_chain: []
+date: 2026-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: turbopuffer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Interact with turbopuffer through a native feeling Active Record database
+  adapter
+email: richard.monette@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE.txt
+- README.md
+- lib/active_record/connection_adapters/turbopuffer_adapter.rb
+- lib/activerecord-turbopuffer-adapter.rb
+- lib/arel/nodes/glob.rb
+- lib/arel/nodes/rank_by_node.rb
+- lib/arel/visitors/turbopuffer.rb
+- lib/turbopuffer/active_record.rb
+- lib/turbopuffer/active_record/glob.rb
+- lib/turbopuffer/active_record/railtie.rb
+- lib/turbopuffer/active_record/schema.rb
+- lib/turbopuffer/active_record/schema/attribute.rb
+- lib/turbopuffer/active_record/schema/model.rb
+- lib/turbopuffer/active_record/type.rb
+- lib/turbopuffer/active_record/type/array.rb
+- lib/turbopuffer/active_record/type/date_time.rb
+- lib/turbopuffer/active_record/type/unsigned_integer.rb
+- lib/turbopuffer/active_record/type/vector.rb
+- lib/turbopuffer/active_record/version.rb
+homepage: https://github.com/richardmonette/activerecord-turbopuffer-adapter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/richardmonette/activerecord-turbopuffer-adapter
+  changelog_uri: https://github.com/richardmonette/activerecord-turbopuffer-adapter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Active Record adapter for turbopuffer
+test_files: []