activerecord-precompiled 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 491ffe9057eef6ea61d917c9811cf90747a0e76f1dd438228e144fc2cc57dbde
+  data.tar.gz: 1a7435d366a3c7542f600e3fef0704b73a49bf894e4fe45ba1c444203be0c8b5
+SHA512:
+  metadata.gz: 43ed76ec56fa4d2827c898b5805706f3c4376158e8fccc37904ce0163432d161129a5278ce017bbcab9346a0a6350d091bc718fc2137234df968e56e98760421
+  data.tar.gz: 792f076ccf90410f48604a188d3fb4c6d223641d2c38b7edca7b9fb98f85be5e1610bb1a2b061bb526ff81cec19289c427b4968ecc788fc239302e985f460261

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.1.0 (2026-10-19)
+
+First release. An ahead-of-time compiler for ActiveRecord query chains on
+SQLite: the build rewrites chains in app source into calls on precompiled
+Sites that run ActiveRecord's own SQL directly on the SQLite handle, keeping
+the original chain as the fallback.
+
+- Chains rooted at a model constant: `all`, `where`/`where.not` (hash
+  conditions, belongs_to keys, Array values as IN lists), `order` (literals,
+  `Arel.sql("...")`), `group`, `limit`, `offset`, static scopes,
+  `includes`/`preload`; terminators `to_a`, `first`/`last`/`take` (and `!`),
+  `find`, `find_by`/`find_by!`, `count`, `exists?` (with conditions or an id),
+  `pluck`, `sum`/`maximum`/`minimum`/`average`, plus `each`/`map`/... with a block.
+- Chains rooted at a collection association (`user.posts.where(...)`,
+  has_many :through, HABTM), one Site per owner model.
+- Precompiled preloads, including through/HABTM associations; whole
+  `includes` trees run without the Preloader, mirroring Preloader::Batch
+  (rounds, deferral, batching of equal queries).
+- friendly_id `friendly.find`, ar_lazy_preload's `auto_preload`, deterministic
+  encrypted attributes (including `extend_queries`).
+- Fast-path queries are instrumented as `sql.active_record` (logs with
+  `filter_attributes`, APM, query counts; `ActiveRecordPrecompiled.active_record_events
+  = false` to skip) and as `sql.active_record_precompiled`, and use ActiveRecord's query
+  cache store when it is on.
+- A schema guard: if the runtime table layout differs from the build's, those
+  sites use ActiveRecord.
+- `ar_precompile:scopes` reports which scopes compile, and how to fix the rest.
+- `ar_precompile:schema:dump` writes the production schema to
+  `config/ar_precompile_schema_cache.yml`; the build uses it for a SQLite
+  database whose file is missing or has no tables (and removes that file), so
+  it runs without the database (`docker build`). Migrations newer than the
+  dump run on its tables, rebuilt in memory, so the build sees the schema
+  production will have after the deploy.
+  The build switches to the dumps after loading the app, so databases that
+  models connect to as they load (`connects_to`) get theirs too.
+- Loaded Sites keep one copy of each string, bind, preload plan and option
+  they share, and allocate caches on first use; a Site object has six
+  instance variables (64 bytes on Ruby 4.1, 80 on 4.0; `bench/memory.rb`).
+
+Supports Ruby 3.4+, ActiveRecord 8.0, 8.1 and main (8.2; association keys as
+ActiveRecord::Key, October 2026), the sqlite3 adapter;
+JRuby 10 with Rails 8.1 and activerecord-jdbc master. The gem no longer
+depends on the sqlite3 gem itself (the app's adapter brings its driver).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sampo Kuokkanen
+
+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,284 @@
+# activerecord-precompiled
+
+[![CI](https://github.com/sampokuokkanen/activerecord-precompiled/actions/workflows/ci.yml/badge.svg)](https://github.com/sampokuokkanen/activerecord-precompiled/actions/workflows/ci.yml)
+
+`assets:precompile` for your ActiveRecord queries, on SQLite. You write normal
+ActiveRecord; at deploy time, on production only, the query chains in your
+source are rewritten into precompiled SQL that runs straight on the `sqlite3`
+handle: no Arel, no relation objects. Logs, APM and the query cache see them as
+usual.
+
+```ruby
+# what you write (and commit)
+def self.named(name) = User.find_by(name: name)
+
+# what runs in production after `rails ar_precompile:build`
+def self.named(name) = ::ActiveRecordPrecompiled::Sites::S9802ca3c9c_0.call(name) { |__xs0| User.find_by(name: __xs0) }
+BEGIN { ::ActiveRecordPrecompiled::Site.define(:S9802ca3c9c_0, model: "User", kind: :one, sql: "SELECT \"users\".* FROM \"users\" WHERE \"users\".\"name\" = ? LIMIT ?", binds: [[:arg, 0, "name"], [:val, 1, "LIMIT"]], schema: "e79cff1769c2ac6f") } # activerecord-precompiled v0.1.0
+```
+
+Same idea as ruby-next's `nextify` (source-to-source at build time) and
+bootsnap (do the expensive work once, ahead of time), applied to queries.
+
+## How it works
+
+* **SQL comes from ActiveRecord itself.** For each chain, the build runs the real
+  ActiveRecord method with placeholder arguments and intercepts the query at
+  the adapter. The SQL is byte-for-byte what ActiveRecord would send.
+* **Binds are cast like ActiveRecord does it**: `type_for_attribute(col).serialize`, then
+  `connection.type_cast`, so enums, booleans, times, and decimals behave the same.
+* **Execution** goes through `with_raw_connection`, using the adapter's own
+  prepared statement pool. Locking, lazy transactions, and reconnects behave as
+  they do in ActiveRecord.
+* **The original chain is kept as a fallback block.** It runs for `nil`,
+  Range, Relation, or record arguments (and arrays ActiveRecord wouldn't turn
+  into a plain IN list), inside `scoping`/`unscoped` blocks, on
+  non-SQLite connections, when `ActiveRecordPrecompiled.enabled = false`, and to raise
+  `RecordNotFound` for `find`/`find_by!`/`first!`/`take!` misses.
+* **Line numbers are preserved**: site definitions go into one `BEGIN {}` line
+  at the end of the file.
+* **Schema guard.** Each site records a fingerprint of its table's columns,
+  including their order. If the runtime schema differs, the site logs one
+  warning and uses ActiveRecord from then on.
+
+## Supported
+
+Chains rooted at a model constant:
+`all`, `where(col: v, ...)`, `where.not(col: v, ...)`, `order(literals)`, `group(:cols)`, `limit(int)`, `offset(int)`,
+`includes(literals)`, `preload(literals)`, static scopes,
+followed by `to_a`, `first`, `last`, `take`, `first!`, `take!`, `find`, `find_by`, `find_by!`, `count`,
+`exists?`, `exists?(col: v, ...)`, `exists?(id)`, `pluck(:cols)`, `sum`/`maximum`/`minimum`/`average(:col)`, or one of `each`, `map`, `flat_map`, `filter_map`,
+`each_with_index`, `each_with_object`, `index_by`, `group_by` with a block.
+`order` also takes `Arel.sql("...")` with a plain string. Calculations return what ActiveRecord does
+(the column's type; `average` of an integer or decimal column is a BigDecimal;
+`sum` of nothing is 0). With `group`, `count` and the calculations return
+ActiveRecord's Hash (keys cast with the columns' types, an Array key for
+several columns); `having` is left to ActiveRecord. `exists?(id)` takes the
+fast path for an Integer or String id; `false`, `nil`, Arrays, Hashes and
+records mean something else to ActiveRecord and go to it.
+
+`includes`/`preload` run the main query on the fast path and then preload,
+as `Relation#load` does. Each association's query is precompiled
+(ActiveRecord's SQL for `key = ?` and `key IN (?, ...)`, up to 100 keys) for
+associations whose scope is a fixed `where`/`order`. For `has_many`/`has_one
+:through` and `has_and_belongs_to_many` that is the two queries the Preloader
+runs for them (owners to the through records, then to the targets), each
+checked at runtime against the scope ActiveRecord builds for it.
+
+When every association in an `includes` tree has one, the Site preloads the
+tree without building the Preloader's objects or the association scopes. It
+follows what `Preloader::Batch` does, in the same order: rounds of runnable
+loaders, loaders deferred while another branch will still load their table,
+loaders with equal queries loaded by one query (so, as with ActiveRecord, a
+comment's `author` can be the very object that is its `post.user`), grouping
+by owner, inverses and already-loaded targets. A through association takes
+this path when its two inner preloads assign what they load (no conditions,
+order or `distinct` on it). Otherwise the Preloader runs as usual and only
+its queries are precompiled. A through query that ActiveRecord joins (a
+`where` on the through association, `source_type`), nested through
+associations, polymorphic ones and scopes that read the clock stay with
+ActiveRecord. If includes would JOIN instead (conditions or order on the
+included table), or with `pluck`, the chain is left to ActiveRecord.
+
+A condition value may be an Array at runtime: `where(id: ids)` runs
+ActiveRecord's `id IN (?, ...)` (`NOT IN` for `where.not`) for any length up
+to 100, and a one-element array the scalar SQL, as ActiveRecord does. The
+build checks the IN form against ActiveRecord for each argument. Empty arrays,
+arrays with `nil`, ranges or records, and longer ones go to ActiveRecord.
+
+Chains can also start at a collection association (`has_many`, `has_many
+:through`, `has_and_belongs_to_many`): `user.posts.where(title: t).first`,
+`@trip.trip_days.count`, or `photos.maximum(:position)` inside a model. The
+receiver's class isn't known at build time, so each model with an association
+of that name whose scopes are static gets its own Site, with the owner's key
+as a bind; at runtime the CollectionProxy tells which owner it is. Records
+point back to the owner (inverse) and take its strict_loading mode, as
+ActiveRecord's AssociationRelation does. ActiveRecord runs the chain for a
+new or strict-loading owner, an owner class the build didn't see, and, when
+the terminator is called on the association itself (`posts.first`), when the
+association is loaded or holds unsaved records, since ActiveRecord may answer
+from memory then. `posts.to_a`/`posts.each` (which load the association into
+the owner) are left alone.
+
+A condition key can also be a `belongs_to` association: `where(site: site)`
+binds `site.id` to `site_id`, as ActiveRecord does (an id works too).
+Polymorphic associations are left to ActiveRecord.
+
+`Model.friendly.find(id)` from [friendly_id](https://github.com/norman/friendly_id)
+compiles too, for `:slugged` and `:history` setups with an integer primary key
+and FriendlyId's own finders: the slug, old-slug, and primary-key lookups are
+each precompiled and tried in FriendlyId's order. A miss runs the original
+chain, so it raises FriendlyId's own `RecordNotFound`.
+
+Deterministic encrypted attributes (`encrypts :email, deterministic: true`)
+work as condition keys: the argument is encrypted at runtime with the
+attribute's type, like ActiveRecord does. With `extend_queries`, the extra
+values it adds (the clear text, previous schemes) are bound too. A value that
+isn't a String, or an encryption setup that differs from the build's, goes to
+ActiveRecord. Constants compared to an encrypted attribute aren't compiled,
+since their ciphertext would be made with the build machine's keys.
+
+With [ar_lazy_preload](https://github.com/DmitryTsepelev/ar_lazy_preload)'s
+`auto_preload` on, fast-path records get the same lazy-preload context that
+`Relation#load` gives them, so their associations still load in batches.
+
+Scopes are compiled when their body is static: one chain of `all`/`where`/
+`where.not`/`order`/`limit`/`offset`/`includes`/`preload` and other static scopes, with
+literals or the scope's own parameters as values (ranges included). Scopes
+Rails generates (enum values, `with_rich_text_*`, `with_attached_*`) count as
+static too:
+
+```ruby
+scope :adults, -> { where(age: 18..) }              # compiled
+scope :named, ->(n) { where(name: n) }              # compiled
+scope :born_since, ->(t) { where(born_at: t..) }    # compiled
+scope :recent, -> { where(created_at: 1.week.ago..) } # not: evaluated per call
+```
+
+To see which scopes compile and how to fix the rest:
+
+```sh
+bin/rails ar_precompile:scopes        # or: bundle exec ar-precompile scopes
+```
+```
+✅ User.adults                test/test_helper.rb:58
+❌ User.recent                app/models/user.rb:12
+   `1.week.ago` in `created_at:` is computed when the scope runs; make it a parameter:
+   ->(x) { where(created_at: x..) } and pass the value from the caller
+activerecord-precompiled: 14 of 19 scopes can be compiled (plus 6 enum scopes)
+```
+
+Bare constants resolve the way Ruby does: inside `module Admin`, `User` means
+`Admin::User` if it exists.
+
+Everything else is left alone: non-static scopes, joins, `eager_load` (and `includes`
+that would JOIN), string conditions, chains on a relation held in a variable,
+models with `default_scope`, keys that are neither columns nor `belongs_to`
+associations, and arguments that are ranges or heredocs. STI subclasses work.
+
+## Deploy
+
+```ruby
+gem "activerecord-precompiled"
+```
+
+Run once per release, after `db:migrate` and before the app boots:
+
+```sh
+RAILS_ENV=production bin/rails ar_precompile:build   # DRY_RUN=1 to preview
+```
+
+or `bundle exec ar-precompile [--dry-run] [--force] [paths]` from the Rails root.
+Paths default to `app` and `lib`; for the rake task, set `AR_PRECOMPILE_PATHS=app,lib/foo`.
+It refuses to run outside production unless `FORCE=1` / `--force`, it prints every
+skipped call site with the reason, and running it again changes nothing. It never
+writes a file that doesn't parse. Never commit the rewritten files.
+
+### Building without the database (`docker build`)
+
+The build needs the production schema (columns, in order, with their types),
+never data. Dump it where the production database is, and commit the file:
+
+```sh
+RAILS_ENV=production bin/rails ar_precompile:schema:dump   # or: bundle exec ar-precompile schema-dump
+# writes config/ar_precompile_schema_cache.yml (ActiveRecord's schema cache format)
+```
+
+Then the build runs anywhere, the image build included:
+
+```dockerfile
+RUN SECRET_KEY_BASE_DUMMY=1 RAILS_ENV=production bin/rails ar_precompile:build
+```
+
+When a SQLite database's file is missing, the build uses its dump on an empty
+in-memory database, so it writes no database file into the image. The output
+is the same as a build against the production database. A database file with
+no tables counts as missing, and the build removes it: that is what an
+initializer or gem that connects while the app loads leaves behind, and the
+app would otherwise start on it in production. When the dump is older than your newest
+migrations, the build recreates its tables (columns in order, keys, indexes)
+and runs those migrations on them, as the deploy will on production: SQLite
+adds a column last, so the order comes out the same. Dump again once they
+have run on production. A migration that can't run on empty tables (one that
+needs data, or a view) leaves the dump as it is, with a warning; the schema
+guard then notices at runtime, and the queries it changes run on ActiveRecord. Other databases (Solid Cache,
+Queue, Cable) don't need a dump: without one, queries on them are left to
+ActiveRecord. `AR_PRECOMPILE_SCHEMA=dump` uses the dumps even when the
+database is there, and `=database` never uses them.
+
+The dump is kept apart from ActiveRecord's own `db/schema_cache.yml` on
+purpose: the app would load that one at boot, and the schema guard has to see
+the real database.
+
+## Trade-offs
+
+* Fast-path queries are instrumented like ActiveRecord's own: a
+  `sql.active_record` event with the same payload (`sql`, `name`, `binds` as
+  named attributes, `type_casted_binds`, `connection`, `row_count`, ...) and
+  `precompiled: true`. So they show up in the Rails log (with
+  `filter_attributes` applied), APM, query counts (`assert_queries_count`) and
+  the request's "ActiveRecord: ...ms (N queries)". The event costs about as
+  much as ActiveRecord's (a few microseconds; Rails always has a subscriber).
+  To skip it: `ActiveRecordPrecompiled.active_record_events = false`. They are also
+  published as `sql.active_record_precompiled` (payload `sql`, `name`, `binds`,
+  `row_count`), which costs nothing when nobody subscribes.
+* With ActiveRecord's query cache on (as in every request), fast-path results
+  are cached in the connection's own cache store, so they live exactly as
+  long as ActiveRecord's (any write clears them; `uncached` skips them).
+  Entries aren't shared with uncompiled calls of the same query. A hit is
+  logged and counted as `CACHE`, as ActiveRecord's are.
+* SQL is fixed at build time, so build against the production schema: after
+  `db:migrate` on the production database, or from its
+  [dump](#building-without-the-database-docker-build). Column order matters,
+  and it is the order of the database's own migration history; a database
+  loaded from `schema.rb` has the order of whichever database dumped it. The
+  schema guard catches a mismatch, but those sites then run on ActiveRecord.
+* Works with `query_log_tags_enabled`, which turns prepared statements off: the
+  build turns them on just while capturing SQL, and the runtime always binds.
+  Fast-path queries don't carry the query-log comment.
+
+## Results on a real app (golf-buddy, 720 Ruby files)
+
+* 407 call sites rewritten in 183 files (about 190 of them on associations).
+* Every rewritten site with data in the dev database (172 of them) returned
+  results identical to ActiveRecord, preloaded associations included. Query
+  cache off on both sides, fast-path queries instrumented as
+  `sql.active_record`: median 1.98× faster, geomean 2.17× (2.33× and 2.61×
+  with `active_record_events = false`). Medians by kind: association
+  `count`/`exists?` 3.0–3.5×, `exists?` 2.6×, `friendly.find` 2.5×,
+  `count` 2.3×, single-record lookups about 1.8× (loading the record
+  dominates on wide models). Given five-element arrays instead, the 62 sites
+  with IN lists matched too.
+* The app's test suite (4317 runs, same seed, one worker) gives the same
+  results before and after the rewrite: the same 3 failures, which are in the
+  clean baseline too.
+* Whole requests (12 public pages, production mode, dev data, fragment cache
+  off, query cache on): 1.6% less time in total. Pages run 15–175 queries, of
+  which the fast path takes 1–19; venue pages (4–6 fast-path queries) are 4–6%
+  faster, the rest within noise. Most remaining queries are lazy association
+  loads (`venue.venue_photos`, `photo.image` inside loops), which no rewritten
+  call site covers.
+
+## Requirements
+
+Ruby 3.4+, ActiveRecord 8.0–8.2 (8.2 tested against Rails main, see
+`Gemfile.edge`; 8.0 with `Gemfile.rails80`), the `sqlite3` adapter (the
+`sqlite3` gem, or on JRuby activerecord-jdbc's sqlite3 adapter). JRuby 10 works
+with Rails 8.1 and activerecord-jdbc's master branch, which is the only
+activerecord-jdbc for Rails 8 so far (`Gemfile.jruby`): the fast path runs the
+precompiled SQL on its JDBC connection, about 1.3–2.2× faster than ActiveRecord
+there.
+
+The build checks that it can still capture queries before touching any file.
+If a Rails change breaks that, it stops with `ActiveRecordPrecompiled::Capture::Broken`
+instead of finishing without rewriting anything.
+
+## Development
+
+```sh
+bundle exec rake            # differential tests: every case runs through AR and the rewrite
+bundle exec rake test:edge  # the same against Rails main
+BUNDLE_GEMFILE=Gemfile.rails80 bundle exec rake test  # ActiveRecord 8.0
+BUNDLE_GEMFILE=Gemfile.jruby bundle exec rake test    # JRuby (see Gemfile.jruby)
+bundle exec ruby bench/bench.rb
+```

data/exe/ar-precompile

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage (from the Rails root):
+#   RAILS_ENV=production bundle exec ar-precompile [--dry-run] [--force] [paths...]
+#   bundle exec ar-precompile scopes     # which scopes can be compiled, and why not
+#   RAILS_ENV=production bundle exec ar-precompile schema-dump   # for builds without the database
+require "optparse"
+
+if ARGV.first == "scopes"
+  require File.expand_path("config/environment", Dir.pwd)
+  Rails.application.eager_load!
+  ActiveRecordPrecompiled::ScopeCheck.new(root: Rails.root).run(out: $stdout)
+  exit
+end
+
+if ARGV.first == "schema-dump"
+  require File.expand_path("config/environment", Dir.pwd)
+  unless Rails.env.production? || ARGV.include?("--force")
+    abort "activerecord-precompiled: the build needs the production schema; run this with " \
+      "RAILS_ENV=production where the production database is, or override with --force"
+  end
+  Rails.application.eager_load! # every database a model connects to
+  ActiveRecordPrecompiled::SchemaDump.dump(Rails.root, out: $stdout)
+  exit
+end
+
+options = { dry_run: false, force: false }
+schema = ENV["AR_PRECOMPILE_SCHEMA"]
+OptionParser.new do |o|
+  o.banner = "Usage: ar-precompile [--dry-run] [--force] [paths (default: app lib)]"
+  o.on("--dry-run", "Report what would be rewritten, write nothing") { options[:dry_run] = true }
+  o.on("--force", "Allow running outside RAILS_ENV=production") { options[:force] = true }
+  o.on("--schema MODE", "auto (a schema dump for a missing database), dump or database") { schema = it }
+end.parse!
+
+require File.expand_path("config/environment", Dir.pwd)
+Rails.application.eager_load! # before: models connect to their databases (connects_to) as they load
+ActiveRecordPrecompiled::SchemaDump.use(Rails.root, mode: schema, out: $stdout)
+
+ActiveRecordPrecompiled::Build.new(
+  root: Rails.root,
+  paths: ARGV.empty? ? %w[app lib] : ARGV,
+  env: Rails.env,
+  out: $stdout,
+  **options,
+).run

data/lib/active_record_precompiled/assoc_site.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ActiveRecordPrecompiled
+  # A chain on a collection association: `owner.posts.where(name: n).first`
+  # becomes `AssocSite.call(owner.posts, n) { |proxy, n| proxy.where(name: n).first }`.
+  # The build compiled one Site per model with such an association, with the
+  # owner's key as its first bind; the CollectionProxy says which owner and
+  # which key this call is for.
+  #
+  # The original chain runs when the proxy isn't one of those, when the owner
+  # is a new record or loads strictly, and, for a terminator called on the
+  # association itself (`posts.first`, `posts.count`), when the association is
+  # loaded or holds unsaved records: ActiveRecord may answer from memory then.
+  class AssocSite
+    def self.define(name, **options)
+      Sites.send(:remove_const, name) if Sites.const_defined?(name, false)
+      Sites.const_set(name, new(**options))
+    end
+
+    # `owners`: owner class name => [Site name, owner key attribute].
+    def initialize(association:, direct:, owners:)
+      @association = association
+      @direct = direct
+      @owners = owners
+      @by_class = {}.compare_by_identity
+    end
+
+    def call(proxy, *args, &fallback)
+      return fallback.call(proxy, *args) unless proxy.is_a?(ActiveRecord::Associations::CollectionProxy)
+
+      association = proxy.proxy_association
+      owner = association.owner
+      site, key_name = entry_for(owner.class)
+      return fallback.call(proxy, *args) unless site && association.reflection.name == @association
+      return fallback.call(proxy, *args) if owner.new_record? || owner.strict_loading? || association.reflection.strict_loading?
+      return fallback.call(proxy, *args) if @direct && (association.loaded? || !association.target.empty?)
+
+      key = owner._read_attribute(key_name)
+      return fallback.call(proxy, *args) unless key.is_a?(Integer) || key.is_a?(String)
+
+      result = site.call(key, *args) { fallback.call(proxy, *args) }
+      case result
+      when ActiveRecord::Base then loaded(association, result)
+      when Array then result.each { loaded(association, it) if it.is_a?(ActiveRecord::Base) }
+      end
+      result
+    end
+
+    private
+
+    # As AssociationRelation#exec_queries: the record points back to the
+    # owner and takes its strict_loading mode.
+    def loaded(association, record)
+      association.set_inverse_instance_from_queries(record)
+      association.set_strict_loading(record)
+    end
+
+    def entry_for(klass)
+      @by_class.fetch(klass) do
+        site, key = @owners[klass.name]
+        @by_class[klass] = site ? [Sites.const_get(site, false), key] : nil
+      end
+    end
+  end
+end

data/lib/active_record_precompiled/build.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ActiveRecordPrecompiled
+  # Rewrites application files in place. Meant to run once per release, on the
+  # production host (or in the production image build), after the app has
+  # booted and the database schema is in place. Never commit the output.
+  class Build
+    NotProduction = Class.new(StandardError)
+    Report = Data.define(:files_changed, :sites, :skipped)
+
+    def initialize(root:, paths: %w[app lib], env: ENV["RAILS_ENV"] || ENV["RACK_ENV"], dry_run: false, force: false, out: nil)
+      @root = root.to_s
+      @paths = paths
+      @env = env
+      @dry_run = dry_run
+      @force = force
+      @out = out
+    end
+
+    def run
+      unless @force || @env == "production"
+        raise NotProduction, "activerecord-precompiled rewrites source in place; run it with RAILS_ENV=production, " \
+          "or override with FORCE=1 (rake), --force (CLI) or force: true (Ruby)"
+      end
+
+      Capture.verify!
+
+      files_changed = sites = 0
+      skipped = []
+      files.each do |file|
+        relative = file.delete_prefix("#{@root}/")
+        result = Rewriter.new(path: relative).rewrite(File.read(file))
+        skipped.concat(result.skipped)
+        result.skipped.each { @out&.puts "activerecord-precompiled: skipped #{it}" }
+        next if result.sites.zero?
+
+        files_changed += 1
+        sites += result.sites
+        @out&.puts "activerecord-precompiled: #{relative} (#{result.sites} queries)"
+        File.write(file, result.source) unless @dry_run
+      end
+      @out&.puts "activerecord-precompiled: #{sites} queries in #{files_changed} files#{" (dry run)" if @dry_run}"
+      Report.new(files_changed, sites, skipped)
+    end
+
+    private
+
+    def files
+      @paths.flat_map { Dir.glob(File.join(@root, it, "**", "*.rb")) }.sort
+    end
+  end
+end

data/lib/active_record_precompiled/capture.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActiveRecordPrecompiled
+  # Build-time only: runs a real ActiveRecord terminator (`first`, `count`,
+  # `find`, ...) but intercepts the query at the adapter, so we get the exact
+  # SQL and binds ActiveRecord would send, without touching any data.
+  module Capture
+    Query = Data.define(:sql, :binds)
+
+    Broken = Class.new(StandardError)
+
+    # Every relation read (records, count, pluck, exists?, find_by_sql) goes
+    # through `select_all`, on 8.0/8.1 and on Rails main, where the private
+    # `select` it used to call is gone. Compile the SQL and binds the way
+    # `select_all` does and return an empty result instead of running it.
+    module AdapterHook
+      def select_all(arel, name = nil, binds = [], preparable: nil, **)
+        log = Thread.current[:__ar_precompiled_capture]
+        return super unless log
+
+        sql, binds, = to_sql_and_binds(arel_from_relation(arel), binds, preparable)
+        log << Query.new(sql, binds)
+        ActiveRecord::Result.empty
+      end
+    end
+
+    # Placeholder for a runtime argument. ActiveRecord keeps it as the
+    # `value_before_type_cast` of the bind it creates (possibly a dup, hence
+    # the index), which tells us which `?` belongs to which argument. It is a
+    # String so that types which validate input (enums) can be satisfied.
+    # `record_key` is set for a belongs_to key (`where(site: x)`): the runtime
+    # value may be a record, whose primary key ActiveRecord binds instead.
+    class Sentinel < String
+      attr_reader :index, :record_key
+
+      def self.for(type, index, record_key: nil)
+        sentinel = new(index, record_key:)
+        return sentinel if bindable?(sentinel, type)
+
+        label = type.respond_to?(:mapping, true) && type.send(:mapping).keys.first
+        label ? new(index, label.to_s, record_key:) : sentinel
+      end
+
+      # Would ActiveRecord turn this value into a plain `column = ?` bind?
+      def self.bindable?(value, type)
+        attribute = ActiveRecord::Relation::QueryAttribute.new("probe", value, type)
+        !attribute.nil? && !attribute.unboundable?
+      end
+
+      def initialize(index, text = "__ar_precompiled_arg_#{index}__", record_key: nil)
+        super(text)
+        @index = index
+        @record_key = record_key
+        freeze
+      end
+    end
+
+    # Proves the hook still sees queries on this Rails version. Without this a
+    # Rails change would make every chain "run 0 queries" and the build would
+    # succeed while rewriting nothing.
+    def self.verify!
+      pool = ActiveRecord::Base.connection_handler.connection_pool_list(:all)
+        .find { it.db_config.adapter.to_s.start_with?("sqlite") }
+      return unless pool
+
+      captured = pool.with_connection { |conn| queries { conn.select_all("SELECT 1 AS ar_precompiled_probe") } }
+      return if captured.any? { it.sql.include?("ar_precompiled_probe") }
+
+      raise Broken, "activerecord-precompiled cannot capture queries on ActiveRecord #{ActiveRecord.version}; " \
+        "nothing was rewritten. This ActiveRecord version is not supported yet."
+    end
+
+    def self.install!
+      ActiveRecord::ConnectionAdapters::SQLite3Adapter.prepend(AdapterHook) unless
+        ActiveRecord::ConnectionAdapters::SQLite3Adapter <= AdapterHook
+    end
+
+    # Yields, returning every query ActiveRecord tried to run. Errors raised
+    # because the result was empty (RecordNotFound) are expected.
+    def self.queries
+      install!
+      log = []
+      previous = Thread.current[:__ar_precompiled_capture]
+      Thread.current[:__ar_precompiled_capture] = log
+      begin
+        ActiveRecord::Base.uncached { yield }
+      rescue ActiveRecord::RecordNotFound
+      ensure
+        Thread.current[:__ar_precompiled_capture] = previous
+      end
+      log
+    end
+  end
+end

data/lib/active_record_precompiled/friendly_site.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveRecordPrecompiled
+  # `Model.friendly.find(id)` from friendly_id, as precompiled Sites taken in
+  # the order FriendlyId::FinderMethods#find tries them:
+  #
+  # * a Numeric id is "unfriendly": find by primary key;
+  # * a String is looked up by slug, then (with :history) by old slug, then,
+  #   if it parses as an integer, by primary key.
+  #
+  # Anything else, any step that can't take the fast path, and a miss (which
+  # raises FriendlyId's own RecordNotFound) run the original chain.
+  class FriendlySite
+    def self.define(name, **options)
+      Sites.send(:remove_const, name) if Sites.const_defined?(name, false)
+      Sites.const_set(name, new(**options))
+    end
+
+    def initialize(slug:, id:, history: nil)
+      @slug = Sites.const_get(slug, false)
+      @history = history && Sites.const_get(history, false)
+      @id = Sites.const_get(id, false)
+    end
+
+    def call(id, &fallback)
+      catch do |tag|
+        give_up = ->(*) { throw tag }
+        return @id.call(id, &give_up) if id.is_a?(Integer)
+
+        if id.is_a?(String)
+          record = @slug.call(id, &give_up) || @history&.call(id, &give_up)
+          return record if record
+          return @id.call(id, &give_up) if integer?(id)
+        end
+      end
+      fallback.call(id)
+    end
+
+    private
+
+    # FriendlyId's potential_primary_key? for an integer primary key.
+    def integer?(id)
+      Integer(id, 10)
+      true
+    rescue ArgumentError
+      false
+    end
+  end
+end