make_taggable 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b11d21dbd46411b5b827d1b70cb44bcb641259804a32fa221597e56e02aa906
-  data.tar.gz: 3ebf2e595313e19cc88e28ab7541c40bae5fd1c702a09b8f60873fb68605bfcd
+  metadata.gz: 1d900a8ac37e0f88ead6c0516fd30ddee5e8cc11c893b7d64e85c090a8b59598
+  data.tar.gz: b364eef565e3a171c56558f928360de5230c445b4b210e1aab8f536f9b998c70
 SHA512:
-  metadata.gz: 543f460b5117fd847d6f2ed9a7bc694aece6306b3268912710c058cf6bb48275932d1a06ee0adf867492c175ca858cf84794db4238e52b8bad4f2f8ff71fdbc2
-  data.tar.gz: 9983b5c3084235e612097a52bda93c4bd48799e4c29a8c30b354d2ad8d24bc07db2ec99d4077956e193dfa5c175e21198f3238d912882a7015887d72438ea1a2
+  metadata.gz: 611fd4635e580ff5aaaee314600d2d66e7cdb70a2bd22d8988e3eb541c3d632fc25625e485880821beeec8f0bfb71677242f3d0d14ba96e98e0dd4d15038e0ae
+  data.tar.gz: b1713ea6a65eb7a8e45dfb0d4b8d41c9d72334cfb8de93ef2c1e60a21a6a4e04758acdcb7761a117b8b275f0aecb3e98d78258a8c7f8389f433836353e676958

data/AATO_ISSUE_TRIAGE.md

@@ -0,0 +1,122 @@
+# acts-as-taggable-on open issues — applicability to MakeTaggable
+
+All 66 open issues on `mbleigh/acts-as-taggable-on` (as of 2026-08-23) checked against
+`make_taggable` at 1.1.1. Everything marked **confirmed** was reproduced by running code
+against the gem's own SQLite harness (Ruby 4.0.1 / Active Record 8.1.3); everything marked
+**static** was read out of the source. Adapter-specific reports that need MySQL/PostgreSQL
+are listed separately as unverified.
+
+Verdict counts: 29 apply, 5 apply as feature gaps, 13 do not apply, 8 unverified,
+11 documentation issues already covered.
+
+---
+
+## Applies — confirmed by reproduction
+
+### Query builder
+
+| Upstream | Symptom in MakeTaggable | Evidence |
+|---|---|---|
+| #402, #993 | `tagged_with` returns a record once per matching tagging. A record tagged `"interesting"` in two contexts comes back twice. No `DISTINCT`, no context filter. | `OtherTaggableModel.tagged_with("interesting")` → 2 rows for 1 record |
+| #701 | `:exclude` ignores `:on`. `ExcludeTagsQuery#tags_not_in_list` builds no context predicate at all. | generated SQL contains no `context` clause |
+| #630 | `tagged_with([], exclude: true)` returns nothing. `core.rb` returns `none` on an empty list before the strategy is chosen, so "exclude nothing" excludes everything. | 0 rows, should be all |
+| #1094 | `tagged_with(tags, order_by_matching_tag_count: true)` raises `ActiveRecord::UnknownAttributeReference`. `AllTagsQuery#order_conditions` passes a raw subquery string to `.order`. | raises; the `any: true` path is fine because it wraps in `Arel.sql` |
+| #692, #1109, #530 | `.count` / `.size` on an `any: true` relation emits `COUNT("table".*)`, which is invalid SQL on SQLite, MySQL and PostgreSQL. Chaining two `tagged_with` calls compounds it. | `SQLite3::SQLException: near "*"` |
+| #936 | `AnyTagsQuery#build` calls `select(all_fields)`, so a caller's own `select` is appended rather than honoured. Also what breaks #395 (`merge` overwriting the SELECT). | `SELECT "taggable_models".*, "taggable_models"."id"` |
+| #915 + our own | `ExcludeTagsQuery#tags_not_in_list` hardcodes `taggable_arel_table[:id]` instead of the model's primary key. Any model with a non-`id` primary key raises on `exclude: true`. This is strictly worse than the upstream report. | `NonStandardIdTaggableModel.tagged_with(["k"], exclude: true)` → `StatementInvalid` |
+| #277, #387 | No way to order by `taggings.created_at`. `tagged_with` hides the taggings behind SHA aliases; `all_tags(order: "taggings.created_at desc")` builds a subquery that doesn't project the column. | `no such column: taggings.created_at` |
+| #293 | `tagged_with` still emits one `INNER JOIN` per tag in the default (all-tags) mode. | 12 tags → 12 joins |
+| #1028, #657 | `QueryBase#tag_match_type` wraps the column in `LOWER()` unconditionally. On PostgreSQL the operator is already `ILIKE`, so the `LOWER()` is redundant *and* defeats `index_tags_on_name`. Same cause as the #657 cache-miss report. | static + confirmed in generated SQL |
+| #328 | SQLite's `LOWER()` is ASCII-only, so `Tag.named_any` misses case variants of non-ASCII names. | `Tag.named_any(["ünicode"])` → 0 for a tag named `"Ünicode"` |
+
+### Attribute / dirty tracking
+
+| Upstream | Symptom | Evidence |
+|---|---|---|
+| #1024, #1064, #1029 | `tag_list` is declared as an `attribute`, so it appears in `as_json` (triggering a tag query per record) but reads back `nil` from `attributes`. | 19 queries to serialize 3 records; `attributes["tag_list"] == nil` |
+| #1155 | `tag_ids = []` after `as_json` silently does nothing — the tags stay attached. | tags survive the assignment |
+| #373 | `tag_list.add(...)` / `.remove(...)` mutate the array in place without `attribute_will_change!`, so `tag_list_changed?` stays false. Only whole-list assignment is tracked. | `false` after `.add("sfw")` |
+| #1047 | `TagList#remove` compares raw objects, so `remove(:foo)` is a no-op while `remove("foo")` works. | list unchanged |
+| #1139 | `TagList` carries `@parser`, which holds a *Class*. `Psych.safe_dump` refuses it, so anything serialising a taggable to YAML (audited, ActiveJob args) blows up. | `Psych::DisallowedClass: Tried to dump unspecified class: Class` |
+
+### Saving
+
+| Upstream | Symptom | Evidence |
+|---|---|---|
+| #1176 | `strict_loading` is violated on save. `save_tags` → `tagging_contexts` → `custom_contexts` lazily loads `taggings`. | `StrictLoadingViolationError` on saving a persisted record |
+| #1128 | The same path means every save — even a no-op — issues tagging queries. | 3 queries on a save with no changes |
+| #665 | A tag over 255 characters fails `Tag`'s length validation, `create` returns it unsaved, and the taggable then fails with a misleading `Validation failed: Tag can't be blank`. | raises `RecordInvalid` |
+| #508 | `Tag.find_or_create_all_with_like_by_name` uses non-bang `create`, so validation errors added by a `Tag` subclass are swallowed and surface later as the wrong error. | static |
+| #947 | `save_tags` and `save_owned_tags` create taggings in list order, so two concurrent saves touching the same tags can deadlock on the `taggings_count` counter cache. Sorting `new_tags` by id would fix it. | static |
+| #290 | `preserve_tag_order` is one `class_attribute` for the whole model, so `make_taggable` and `make_ordered_taggable` in the same class clobber each other — the last call wins for every context. | `make_taggable :skills` + `make_ordered_taggable :books` → `preserve_tag_order?` is `true` for `:skills` |
+| #1044 | A context whose name starts with a digit raises a **`SyntaxError`** while the class body loads (we generate `def 1category_taggings`). Upstream only got an invalid-ivar error, so ours fails harder. | `SyntaxError` from `has_many` |
+
+### Ownership and caching
+
+| Upstream | Symptom | Evidence |
+|---|---|---|
+| #233 | `Tagger#tag` does not refresh `cached_<context>_list`. `save_cached_tag_list` only mirrors unowned lists, so a cached column silently drifts from `all_tags_list`. | `cached_tag_list` stayed `nil` while `all_tags_list == ["owned"]` |
+| #571 | `Tagger#tag` always parses `:with` through the default parser. There is no `parse: false`, so a tag legitimately containing a comma is split into two. | `with: ["a, b"]` → `["a", "b"]` |
+
+### Configuration
+
+| Upstream | Symptom | Evidence |
+|---|---|---|
+| #781, #945 | `force_binary_collation=` still issues an `ALTER TABLE` every time it's called. Set in an initializer, that runs on every boot — including every Sidekiq/cron process — and takes a metadata lock on the tags table. | `apply_binary_collation` still calls `ActiveRecord::Migration.execute` |
+| #769 | `force_parameterize` maps tags through `String#parameterize`, which reduces a fully non-ASCII tag to the empty string and `clean!` then drops it. | `["日本語", "ok tag"]` → `["ok-tag"]` |
+
+## Applies — feature gaps rather than bugs
+
+| Upstream | Gap |
+|---|---|
+| #91 | No eager-loading path for tag lists. `includes(:tags)` doesn't stop `tag_list` re-querying (13 queries for 5 records). |
+| #804 | `tagged_with(tags, on: [:skills, :interests])` raises `TypeError: can't quote Array`. Only one context per call. |
+| #783 | The `Tag` class is hardcoded. `find_or_create_tags_from_list_with_context` lets you create subclass rows, but the associations still return `MakeTaggable::Tag`. |
+| #909 | `all_tags` / `all_tag_counts` accept no scope on the taggable's own attributes (`assert_valid_keys` rejects `:scope`). |
+| #698 | The generated migration has no `type:` on the polymorphic references, so a UUID-keyed taggable needs the migration edited by hand. Not documented. |
+
+## Does not apply
+
+| Upstream | Why |
+|---|---|
+| #908, #914 | `Model.create!(tags: [tag])` works — the tagging saves with the default context. |
+| #1151 | Repeated single-context `make_taggable` calls define `<context>_from` correctly; `Ownership.included` re-runs on every call. |
+| #576 | Adding a tag in a second context does not delete the first context's taggings. |
+| #867 | Chaining `tagged_with` with the same tag produces one join — Active Record dedupes the identical alias. |
+| #1033 | `tagged_with(..., exclude: true)` returns the same result on a relation as on the class. |
+| #946 | `remove_unused_tags` behaves as documented; re-tagging after a removal works. |
+| #1023 | Ordered taggable + owner works. Our `order` argument is a bare `taggings.id`, which Active Record accepts. |
+| #1099 | `upsert_all` on a taggable model works. |
+| #395 | The `merge` symptom is #936's `select(all_fields)`, already listed. Not separately actionable. |
+| #300 (part) | `find_related_*.blank?` works; only `.count` is broken (listed as #300/#907). |
+| #455, #603 | Caching is documented — `docs/caching.md`. |
+| #848 | The array form of the strong parameter is documented in `docs/getting-started.md`. |
+| #981 | Docs already use `rails make_taggable_engine:install:migrations`, not `rake`. |
+| #885 | `docs/ownership.md` builds owned lists from `locations_from(user)`, not `all_tags_list`, so the cascade the issue describes can't happen. |
+| #754 | `tagged_with` parsing its argument is documented on the method. |
+
+## Unverified — needs a PostgreSQL or MySQL run
+
+| Upstream | What to check |
+|---|---|
+| #852 | `tag_counts_on` on a relation built with `includes(...).where(other_table: ...)` → "subquery has too many columns". Our `generate_tagging_scope_in_clause` does `except(:select).select(pkey)`, which may already fix it. |
+| #1026 | `find_related_*` groups by every column on PostgreSQL; a `json` column has no equality operator and breaks `GROUP BY`. `Related#group_columns` still does this. |
+| #1069 | Ambiguous column on `.count` with a joined scope. Did not reproduce on SQLite. |
+| #1100 | "no implicit conversion of nil into String" on update — no reproduction in the issue. |
+| #1103 | Ownership with `acts_as_tenant`: owned taggings created through `taggings.create!` and destroyed through a bare `Tagging.where(...)` may bypass the tenant scope. |
+| #810 | Ordering against `acts_as_nested_set` — depends on callback order in the host app. |
+| #657 | The PostgreSQL index-miss half of #1028; needs an `EXPLAIN` on a real table. |
+| #915 | The integer-vs-varchar join half (separate from the primary-key bug above). |
+
+---
+
+## Suggested order of work
+
+1. **#1044** — a `SyntaxError` at class-load time. Cheapest fix (validate the context name, or reject it with a clear error) and the worst failure mode.
+2. **#915/exclude** — `ExcludeTagsQuery` hardcoding `:id`. One-line fix, silently wrong today.
+3. **#701, #630** — `:exclude` ignoring context and the empty-list short circuit. Both are wrong *answers*, not errors.
+4. **#402/#993** — duplicate rows from `tagged_with`. Needs a decision on `DISTINCT` vs. a subquery.
+5. **#692/#1109/#530, #936, #1094** — the `AnyTagsQuery` select and the `AllTagsQuery` order. `.count` not working on a documented query option is a hard edge.
+6. **#1139, #1047, #373** — small, self-contained `TagList` fixes.
+7. **#1176, #1128** — stop `save_tags` loading `taggings` when nothing was assigned.
+8. **#1024/#1064/#1029, #1155** — the `attribute :tag_list` design. The largest change; worth its own discussion.

data/AATO_UPSTREAM_COMMIT_REVIEW.md

@@ -0,0 +1,74 @@
+# Upstream commits since the fork point — what's worth pulling
+
+## Fork point
+
+`make_taggable`'s history starts at a squashed "Initial commit" (7698fe0, 2020-11-16) with no
+shared ancestry, so the base had to be recovered by matching blobs. The fork's initial tree is
+**upstream v6.5.0** (`6b38c652`, 2019-10-29) — 62 of 75 Ruby/Markdown files match that tree
+exactly, and the bundled `CHANGELOG.md` stops at the v6.5.0 release notes.
+
+Since then upstream has 93 commits (v7.0.0 → v13.0.0), of which **39 touch `lib/` or `db/`**.
+Everything below is that 39, reviewed one by one.
+
+## The important negative result
+
+**Upstream has not fixed any of the 29 confirmed bugs from the issue triage.** I checked HEAD
+(`4d58c53`) directly:
+
+- `ExcludeTagsQuery#tags_not_in_list` still hardcodes `taggable_arel_table[:id]`
+- `AnyTagsQuery#build` still calls `select(all_fields)`
+- `AllTagsQuery#order_conditions` still passes a raw string to `.order` without `Arel.sql`
+
+So there is no shortcut: that backlog is ours to fix either way. What upstream *does* have that we
+don't is a handful of small correctness fixes and three features.
+
+---
+
+## Worth pulling — correctness
+
+| Upstream | What it fixes | Status here |
+|---|---|---|
+| **12f08be** (#1081, v10) | `find_or_create_all_with_like_by_name` issues a raw `ActiveRecord::Base.connection.execute "ROLLBACK"` when it hits `RecordNotUnique`. That breaks any enclosing transaction and ignores multiple-database setups. Upstream replaced it with `transaction(requires_new: true) { create(...) }`. | **We still have the raw ROLLBACK.** Highest-value pull on this list — it corrupts caller transactions, and our own spec suite runs inside a transaction. |
+| **426d960 + a0cadfb** | `remove_unused_tags` handling when the counter cache is off, and avoiding a needless `tag.reload`. | **Ours is worse than upstream's pre-fix state.** `MakeTaggable.remove_unused_tags` is gated on `&& MakeTaggable.tags_counter`, so with `tags_counter = false` the setting silently does nothing. Verified: orphan tag survives. This is upstream issue #946 arriving by a different route. |
+| **2a8acc1** (#1065) | `using_postgresql?` matches only `"PostgreSQL"`, so the PostGIS adapter falls through to the MySQL/generic path — `LIKE` instead of `ILIKE`, and the wrong `GROUP BY` strategy. | Absent. One-line fix: `%w[PostgreSQL PostGIS].include?(adapter_name)`. |
+| **38fb4d2 / b915ca8** | `Utils.connection` uses the model-level `.connection`, soft-deprecated in Rails 7.2 in favour of `lease_connection`. | Absent. Worth taking since our floor is already AR 7.2 — go straight to `lease_connection`, no fallback branch needed. Note: I did **not** observe an actual deprecation warning on AR 8.1.3, so this is hygiene, not breakage. |
+| **1df5ac3** | Upstream dropped four single-column indexes on `taggings` as redundant against the composite ones. | **Applies, and ours is worse.** Our migrations produce **12 indexes** on `taggings`. At least five are dead weight: `tag_id` (prefix of `taggings_idx`), `taggable_id` (prefix of `taggings_taggable_context_idx`), `taggable_type`, `tagger_id` (prefix of the tagger pair), and we create the tagger pair **in both column orders** (`index_taggings_on_tagger_id_and_tagger_type` *and* `index_taggings_on_tagger_type_and_tagger_id`, the latter from `t.references`). Every tagging insert pays for all of them. |
+
+## Worth pulling — features
+
+| Upstream | Feature | Note |
+|---|---|---|
+| **2014fcc** (#1082, v10) | `wild: :prefix` / `wild: :suffix` in addition to `wild: true`. | Small and self-contained, and it partly answers issue #1028: a suffix match (`foo%`) can use a plain btree index, where `%foo%` never can. |
+| **52d7dae** (#1053, v9) | `all_tag_counts(id: [...])` accepts an array of taggable ids, not just one. | Lets a caller compute tag counts for a page of records in one query instead of N. Cheap to take. |
+| **b4eed9b + 8ba7fee** (v9/v10) | A `base_class` config so `Tag` and `Tagging` inherit from the host's `ApplicationRecord` instead of `::ActiveRecord::Base` — needed for horizontally sharded / multi-database apps. 8ba7fee then changed it to a **String** because Zeitwerk won't let you reference a model constant at initializer time. | If we take this, take both commits: the String form is the correct one. Also relevant to issue #1103 (ownership + tenancy). |
+| **7e696e3 + 4a7948e + e2d211b + 5d86cce** (v8) | A `tenant` column on `taggings`, `acts_as_taggable_tenant`, `Tag.for_tenant`, `Tagging.by_tenant`. | The largest item here — a migration plus API surface. Directly addresses issue #1103. I'd treat this as a "do we want it?" product decision rather than a pull; it overlaps with what `acts_as_tenant` already does in the host app. |
+
+## Not worth pulling
+
+| Upstream | Why not |
+|---|---|
+| **47da503** (case-sensitivity third arg to `matches`) | **Already present.** Our `query_base.rb` passes `MakeTaggable.strict_case_match`. |
+| **b54771d** (`force_encoding('BINARY')` removal) | **Already present** — we fixed this independently in 1.0.0 and the CHANGELOG records it. |
+| **f18679a** (drop `mb_chars` / `unicode_downcase`) | **Already present** — our `Tag` uses `name.to_s.downcase`. |
+| **31f29c9** (caching always on) | This deletes the lazy `columns` interception that upstream themselves added in PR #911 to avoid clobbering a host's own `columns` override. Our `Cache::Columns` is the better design and we have a spec for it (`ColumnsOverrideModel`). Taking this would be a regression. |
+| **93fd6d2, a54cc54, bdb86da** (v11 `ActiveSupport::Concern` / Zeitwerk refactors) | Pure restructuring of code we have already restructured differently in 1.0.0. No behaviour change. |
+| **380c0bc** (combine migrations into one) | Upstream folded migrations 1–7 into a single idempotent `SetupActsAsTaggableOn`. Tempting, but our six-migration chain is already published and 1.1.0 just added migration 6 — collapsing them now would break `install:migrations` for existing installs for no functional gain. Take the *index trimming* from 1df5ac3 without the consolidation. |
+| **89a4d7f, 37bfebc, 4c49575, cfd6e06, 866c38f, 46c4e2d, f7bfad9, 69e6bff, b1d7651, 6fa6b55, 8548529, e0f859e, 6fbd9d1, b7122b9, 25266d6, 954e7ce** | Release commits, CI/docker chores, formatting, Ruby 2.7 / Rails 6.1 / Rails 8 compatibility we already exceed, and migration-syntax cleanups against migration files we don't share. |
+
+---
+
+## Recommendation
+
+Four small commits are worth taking more or less as-is, and they're cheap:
+
+1. **12f08be** — the raw `ROLLBACK` (correctness, affects callers' transactions)
+2. **remove_unused_tags with `tags_counter = false`** (our own regression, upstream-adjacent)
+3. **2a8acc1** — PostGIS adapter detection
+4. **1df5ac3-style index trim** — but sized to our 12-index reality, as a *new* migration 7 that drops the redundant ones rather than by editing migration 5
+
+Then **2014fcc** (`wild: :prefix`/`:suffix`) and **52d7dae** (array `:id`) as easy feature wins.
+
+`base_class` and the tenant feature are both real decisions rather than pulls — worth discussing
+before either lands.
+
+None of this changes the issue triage: the 29 confirmed bugs have no upstream fix to inherit.

data/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-08-23
+
+### Added
+
+- `:on` accepts several contexts as well as one, so a query can search a subset:
+  `tagged_with("classic", on: [:genres, :moods], any: true)`. Passing an array previously raised
+  `TypeError` from inside Arel.
+
+### Fixed
+
+- `force_parameterize` discarded a tag outright when the name had no ASCII in it. `parameterize`
+  reduces such a name to an empty string, which was then rejected as blank, so a user tagging in
+  Japanese, Greek, Hebrew, Arabic or Cyrillic saved successfully and got back fewer tags than they
+  typed. The parameterized form is now kept only where there is one.
+
+- `force_binary_collation = true` ran an `ALTER TABLE` every time it was assigned, with no check for
+  whether the column already carried that collation. The documented home for it is an initializer,
+  which runs once per process, so a deployment issued a schema change against the `tags` table from
+  every web worker, background worker, console and rake task -- each one taking a metadata lock that
+  other queries queue behind. The current collation is now read first and the statement skipped when
+  it matches. The blanket `rescue`/`puts` around it is replaced by an explicit `table_exists?` check.
+
+- On PostgreSQL, tag names were matched as `LOWER(name) ILIKE ...`. `ILIKE` already folds case, so
+  the `LOWER()` changed nothing while making the expression non-sargable -- no index on `tags.name`
+  could be used, including a trigram index built for wild searches. It is skipped on PostgreSQL and
+  kept on the adapters that need it.
+
+- Taggings are created in tag id order. Each insert bumps the tag's counter cache, so two concurrent
+  saves touching the same tags took row locks in whatever order their lists happened to be in, which
+  invites deadlocks. Models using `make_ordered_taggable` are unaffected -- there the creation order
+  carries the meaning.
+
+## [1.4.0] - 2026-08-23
+
+### Fixed
+
+- `find_related_*` raised on `.count`. The relation selects the taggable's columns plus an aliased
+  count, and Active Record folded that select list into the `COUNT()` it built. It now counts the
+  grouped query as a subquery, so `.count` and `.size` return the number of related records.
+
+- `find_related_*` raised on PostgreSQL for any taggable model with a `json` column -- the query
+  grouped by every column on the table, and `json` has no equality operator so it cannot appear in
+  a `GROUP BY`. It now groups by the primary key on every adapter, which is what the other adapters
+  already did. `jsonb` was never affected, so the column type an application picked decided whether
+  the feature worked at all.
+
+- `TagList` could not be serialised to YAML. Every list carried its parser in an instance variable,
+  and that variable holds a Class, which Psych refuses to dump. Anything serialising a model's
+  attributes hit it -- change-history gems, Active Job arguments, `serialize` columns. The parser is
+  no longer stored; the reader falls back to the configured `MakeTaggable.default_parser`. One
+  consequence: a list now follows the configured parser rather than the one in force when it was
+  built.
+
+- `TagList#remove` ignored a symbol. `remove(:foo)` silently did nothing where `remove("foo")`
+  worked.
+
+- A tag that failed validation was reported as `Tag can't be blank`, naming the wrong attribute for
+  the wrong reason -- reachable with no customisation, since the shipped `Tag` validates name length
+  at 255 characters. The error now carries the tag itself, so it says what was actually wrong and
+  `error.record` is the tag. `save!` raises; `save` still returns `false` and writes nothing.
+
+- Saving a taggable read every tagging on the record, on every save, before establishing whether
+  any tag list had been assigned. That cost a query per save and made the gem unusable under
+  `strict_loading` -- a record whose tags were never touched still raised
+  `StrictLoadingViolationError`. Saves now consider only the contexts held in memory.
+
+### Changed
+
+- **Tag lists are no longer declared as Active Model attributes.** The declaration is what gave them
+  dirty tracking, and it also made Active Record treat them as columns where they are not. The dirty
+  API is unchanged -- `tag_list_changed?`, `_was`, `_change`, `will_save_change_to_*`,
+  `saved_change_to_*`, and the tag lists still appear in `changes` -- but it now runs on the gem's
+  own bookkeeping.
+
+  Three visible consequences, each of them the point:
+
+  - `as_json` no longer includes tag lists, so serialising a collection no longer queries once per
+    record. Serialising three records went from 16 queries to 1. Ask for a list explicitly with
+    `as_json(methods: :tag_list)`.
+  - `attributes` no longer carries a `tag_list` key. It previously held `nil` while `tag_list`
+    returned the tags.
+  - `upsert_all` still refuses a tag list -- it writes columns, and a tag list means writing
+    taggings -- but `as_json` output can now be round-tripped through it, which it could not before.
+
+  `MakeTaggable::Taggable::TagListType` is removed. It backed the attribute and has no other caller.
+
+### Fixed
+
+- `tag_ids = []` silently did nothing once `as_json` had been called on the record.
+
+- Mutating a list in place -- `record.tag_list.add("x")` -- did not mark the record as changed, so
+  `tag_list_changed?` stayed false and anything conditioned on it never ran. The list still saved;
+  what was wrong was everything that asks the record what changed.
+
 ## [1.3.0] - 2026-08-23
 
 ### Changed

data/docs/configuration.md

@@ -40,6 +40,10 @@ Tags are downcased as they are cleaned, so `"Ruby"` is stored as `"ruby"`.
 Tags are parameterized, so `"Ruby on Rails"` is stored as `"ruby-on-rails"`. Applied after
 `force_lowercase` if both are on.
 
+`String#parameterize` strips anything outside a conservative ASCII set, so a name with no ASCII in
+it -- `"日本語"` -- has no slug to reduce to. Such a name is kept as it is rather than parameterized
+into nothing and dropped.
+
 ### `strict_case_match`
 
 Off, tag lookups are case insensitive and `"Ruby"` finds `"ruby"`; a list containing both keeps one.
@@ -98,6 +102,12 @@ Note that the shipped migrations already apply `utf8mb4_bin` to the column on My
 setting adds is `strict_case_match`, which is what actually makes the library's lookups case
 sensitive — see [database.md](database.md).
 
+Because the migrations have usually applied the collation already, assigning this in an initializer
+is normally a no-op: the current collation is read first and the `ALTER TABLE` is skipped when it
+already matches. That matters because an initializer runs once per process — every web worker,
+background worker, console and rake task — and each `ALTER TABLE` takes a metadata lock on the tags
+table.
+
 ```ruby
 MakeTaggable.force_binary_collation = true
 ```

data/docs/contexts.md

@@ -30,16 +30,40 @@ with Active Support's inflector, so `:skills` gives `skill_list` and `skills`.
 | `find_related_skills_for(klass)` | instance | The same, against another model |
 | `caching_skill_list?` | class | Whether this context is cached in a column |
 
-`skill_list` takes part in dirty tracking like any other attribute:
+`skill_list` takes part in dirty tracking:
 
 ```ruby
 user.skill_list = "diving"
-user.skill_list_changed?          # => true
-user.skill_list_was               # => ["jogging"]
-user.skill_list_change            # => [["jogging"], ["diving"]]
-user.will_save_change_to_skill_list?
+user.skill_list_changed?             # => true
+user.skill_list_was                  # => ["jogging"]
+user.skill_list_change               # => [["jogging"], ["diving"]]
+user.will_save_change_to_skill_list?  # => true
+user.changes                          # => {"skill_list" => [["jogging"], ["diving"]]}
+user.save
+user.saved_change_to_skill_list?      # => true
+```
+
+Mutating the list in place counts too, not just assigning a new one:
+
+```ruby
+user.skill_list.add("diving")
+user.skill_list_changed?   # => true
 ```
 
+Order counts only where the model asked for it with `make_ordered_taggable`. Reordering the same
+tags is not a change otherwise.
+
+A tag list is **not** an Active Record attribute, though, and the difference shows in three places:
+
+```ruby
+user.attributes["skill_list"]   # => nil, and the key is absent -- use user.skill_list
+user.as_json                    # no "skill_list" key; ask for it with as_json(methods: :skill_list)
+User.upsert_all([{skill_list: "diving"}])   # raises -- upsert_all writes columns, and this is not one
+```
+
+Leaving tag lists out of `as_json` is deliberate: a list is loaded from the taggings table, so
+including it meant serialising a collection queried once per record.
+
 ### Naming a context
 
 Because the context becomes part of every name in the table above, it has to be usable as a Ruby

data/docs/database.md

@@ -107,8 +107,25 @@ end
 ## PostgreSQL
 
 - `named_like` uses `ILIKE`, so partial matching is case insensitive regardless of collation.
-- Tag counts group by every tag column, as PostgreSQL requires.
-- Nothing extra is needed for non-ASCII tags.
+- Queries group by the primary key. PostgreSQL wanted every selected non-aggregated column listed
+  before 9.1; since then it works the dependency out itself.
+
+**Case-insensitive matching of non-ASCII tags depends on the locale the cluster was created with.**
+Exact matching goes through `LOWER(name) = LOWER(?)`, and `LOWER()` follows `lc_ctype`. On a UTF-8
+locale it folds Cyrillic, Greek and the rest as you would expect. On a cluster initialised with
+`lc_ctype = C` it folds ASCII only, and `"ПРИВЕТ"` and `"привет"` become two separate tags — the same
+limitation described under SQLite below, on a database that otherwise has none.
+
+Check with:
+
+```sql
+SHOW lc_ctype;          -- C means ASCII-only folding
+SELECT LOWER('Ü');      -- returns 'Ü' unchanged on such a cluster
+```
+
+`ILIKE` is unaffected, so partial matching keeps working either way. If you need exact matching to
+fold non-ASCII, create the database with a UTF-8 locale, or set
+`MakeTaggable.strict_case_match = true` so the behaviour is at least consistent.
 
 ## MySQL
 
@@ -156,3 +173,20 @@ or set `MakeTaggable.strict_case_match = true` so the behaviour is at least cons
 
 `name` is validated at 255 characters, and the column is a `string`. Tags longer than that fail
 validation rather than being truncated.
+
+A tag that cannot be saved fails the save of the record being tagged. `save!` raises
+`ActiveRecord::RecordInvalid` carrying the **tag**, so the error says what was wrong with it and
+`error.record` is the tag itself; `save` returns `false` and writes nothing.
+
+The same applies to a `Tag` subclass with validations of its own:
+
+```ruby
+class PickyTag < MakeTaggable::Tag
+  validate { errors.add(:name, "must not be rude") if name.to_s.include?("rude") }
+end
+
+article.save!
+# => ActiveRecord::RecordInvalid: Validation failed: Name must not be rude
+```
+
+See [contexts.md](contexts.md) for wiring a `Tag` subclass to a context.

data/docs/querying.md

@@ -28,12 +28,18 @@ empty relation rather than every record — worth knowing when the tags come fro
 | `:exclude` | Match records carrying none of the tags |
 | `:match_all` | Match records carrying only these tags and no others |
 | `:wild` | Match tags *containing* the given text, i.e. `%sci%` |
-| `:on` | Restrict to one context. Honoured by every option, `:exclude` included |
+| `:on` | Restrict to one context, or an array of them. Honoured by every option, `:exclude` included |
 | `:owned_by` | Restrict to tags applied by one tagger |
 | `:order_by_matching_tag_count` | Order by how many matching taggings a record has, most first. No effect with `:match_all` |
 | `:start_at` | Only tags applied after this time. Honoured by every option, `:exclude` included |
 | `:end_at` | Only tags applied before this time. Honoured by every option, `:exclude` included |
 
+`:on` takes several contexts as well as one, for searching a subset:
+
+```ruby
+Book.tagged_with("classic", on: [:genres, :moods], any: true)
+```
+
 An empty tag list means "nothing matches" for the matching options and "nothing is ruled out" for
 `:exclude`, so the two always partition the scope between them:
 
@@ -181,6 +187,16 @@ its own — add `.distinct` if you want records back rather than matches.
   is what stops a record being returned once per matching tagging. Matching a dozen tags produces a
   dozen correlated subqueries rather than a dozen joins, which most planners handle better, but it
   is still worth reaching for `any: true` where the semantics allow it.
+- Saving a taggable reads nothing from the taggings table unless a tag list was actually assigned,
+  so a save that touches no tags costs no extra query and works under `strict_loading`.
+- On PostgreSQL, tag names are matched with `ILIKE` against the column itself rather than through
+  `LOWER()`, so an index on `tags.name` can be used. A wild search is the case that most wants one:
+
+  ```sql
+  CREATE EXTENSION IF NOT EXISTS pg_trgm;
+  CREATE INDEX index_tags_on_name_trgm ON tags USING gin (name gin_trgm_ops);
+  ```
+
 - `:order_by_matching_tag_count` adds a correlated subquery to the `ORDER BY`. It is fine for a
   page of results and expensive across a whole table.
 - `all_tag_counts` joins the taggables to count them. Reach for `all_tags` when the counts are not

data/lib/make_taggable/tag_list.rb

@@ -24,7 +24,7 @@ module MakeTaggable
   #
   class TagList < Array
     attr_accessor :owner
-    attr_accessor :parser
+    attr_writer :parser
 
     ##
     # Builds a tag list from the given names.
@@ -34,10 +34,26 @@ module MakeTaggable
     # @return [MakeTaggable::TagList]
     #
     def initialize(*args)
-      @parser = MakeTaggable.default_parser
       add(*args)
     end
 
+    ##
+    # The parser this list uses when asked to parse.
+    #
+    # Falls back to the configured {MakeTaggable.default_parser}, and deliberately does not store
+    # it. A stored parser is a Class held in an instance variable, and Psych validates instance
+    # variables when dumping, so carrying one made every tag list unserialisable -- `audited`,
+    # Active Job arguments and `serialize` columns all refuse it.
+    #
+    # A parser assigned explicitly is still stored, and a list carrying one is subject to the same
+    # limitation.
+    #
+    # @return [Class]
+    #
+    def parser
+      @parser || MakeTaggable.default_parser
+    end
+
     ##
     # Adds tags to the list, ignoring duplicates and blanks.
     #
@@ -101,6 +117,13 @@ module MakeTaggable
     #
     def remove(*names)
       extract_and_apply_options!(names)
+
+      # The list holds strings, so compare strings. Everything else that takes
+      # tag names normalises them -- add runs them through clean!, tagged_with
+      # parses them -- and a symbol silently matching nothing here was the odd
+      # one out.
+      names = names.map(&:to_s)
+
       delete_if { |name| names.include?(name) }
       self
     end
@@ -135,7 +158,11 @@ module MakeTaggable
       map!(&:to_s)
       map!(&:strip)
       map!(&:downcase) if MakeTaggable.force_lowercase
-      map!(&:parameterize) if MakeTaggable.force_parameterize
+      # A name with no ASCII in it parameterizes to "", and reject! below would
+      # then drop it -- so the tag vanished rather than being slugged. Keep the
+      # original where there is no slug to be had; a caller who wanted strict
+      # slugs still gets one wherever one exists.
+      map! { |tag| tag.parameterize.presence || tag } if MakeTaggable.force_parameterize
 
       MakeTaggable.strict_case_match ? uniq! : uniq! { |tag| tag.downcase }
       self
@@ -145,9 +172,9 @@ module MakeTaggable
       options = args.last.is_a?(Hash) ? args.pop : {}
       options.assert_valid_keys :parse, :parser
 
-      parser = options[:parser] || @parser
+      chosen_parser = options[:parser] || parser
 
-      args.map! { |a| parser.new(a).parse } if options[:parse] || options[:parser]
+      args.map! { |a| chosen_parser.new(a).parse } if options[:parse] || options[:parser]
 
       args.flatten!
     end

data/lib/make_taggable/taggable/core.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "tagged_with_query"
-require_relative "tag_list_type"
 
 module MakeTaggable::Taggable
   ##
@@ -58,8 +57,6 @@ module MakeTaggable::Taggable
               class_name: "MakeTaggable::Tag",
               through: context_taggings,
               source: :tag
-
-            attribute :"#{tags_type.singularize}_list", MakeTaggable::Taggable::TagListType.new
           end
 
           taggable_mixin.class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -68,15 +65,6 @@ module MakeTaggable::Taggable
             end
 
             def #{tag_type}_list=(new_tags)
-              parsed_new_list = MakeTaggable.default_parser.new(new_tags).parse
-
-              if self.class.preserve_tag_order? || (parsed_new_list.sort != #{tag_type}_list.sort)
-                unless #{tag_type}_list_changed?
-                  @attributes["#{tag_type}_list"] = ActiveModel::Attribute.from_user("#{tag_type}_list", #{tag_type}_list, MakeTaggable::Taggable::TagListType.new)
-                end
-                write_attribute("#{tag_type}_list", parsed_new_list)
-              end
-
               set_tag_list_on('#{tags_type}', new_tags)
             end
 
@@ -84,9 +72,33 @@ module MakeTaggable::Taggable
               all_tags_list_on('#{tags_type}')
             end
 
+            def #{tag_type}_list_changed?
+              tag_list_changed_on?('#{tags_type}')
+            end
+
+            def #{tag_type}_list_was
+              tag_list_was_on('#{tags_type}')
+            end
+
+            def #{tag_type}_list_change
+              tag_list_change_on('#{tags_type}')
+            end
+
+            def will_save_change_to_#{tag_type}_list?
+              tag_list_changed_on?('#{tags_type}')
+            end
+
+            def saved_change_to_#{tag_type}_list
+              saved_tag_list_changes['#{tag_type}_list']
+            end
+
+            def saved_change_to_#{tag_type}_list?
+              saved_tag_list_changes.key?('#{tag_type}_list')
+            end
+
             private
             def dirtify_tag_list(tagging)
-              attribute_will_change! tagging.context.singularize+"_list"
+              tag_list_changed_by_association(tagging.context)
             end
           RUBY
         end
@@ -106,7 +118,17 @@ module MakeTaggable::Taggable
         initialize_make_taggable_core
       end
 
-      # all column names are necessary for PostgreSQL group clause
+      ##
+      # Every column on a table, qualified, joined for a `GROUP BY` clause.
+      #
+      # Nothing in the library needs this any more. PostgreSQL wanted every selected
+      # non-aggregated column in the `GROUP BY` before 9.1; since then the primary key is enough,
+      # and that is what the library groups by. Kept because it is public and useful for building
+      # such a clause by hand.
+      #
+      # @param object [Class] the model whose columns to list
+      # @return [String]
+      #
       def grouped_column_names_for(object)
         object.column_names.map { |column| "#{object.table_name}.#{column}" }.join(", ")
       end
@@ -167,7 +189,12 @@ module MakeTaggable::Taggable
       end
     end
 
-    # all column names are necessary for PostgreSQL group clause
+    ##
+    # @see ClassMethods#grouped_column_names_for
+    #
+    # @param object [Class] the model whose columns to list
+    # @return [String]
+    #
     def grouped_column_names_for(object)
       self.class.grouped_column_names_for(object)
     end
@@ -192,7 +219,13 @@ module MakeTaggable::Taggable
     # @return [Array<String>, NilClass]
     #
     def add_custom_context(value)
-      custom_contexts << value.to_s unless custom_contexts.include?(value.to_s) || self.class.tag_types.map(&:to_s).include?(value.to_s)
+      # The declared contexts are checked first deliberately. Ruby evaluates the
+      # left operand of `||` first, so testing custom_contexts up front loaded
+      # every tagging on the record just to assign a list on an ordinary
+      # declared context.
+      return if self.class.tag_types.map(&:to_s).include?(value.to_s)
+
+      custom_contexts << value.to_s unless custom_contexts.include?(value.to_s)
     end
 
     ##
@@ -216,6 +249,151 @@ module MakeTaggable::Taggable
       instance_variable_defined?(variable_name) && instance_variable_get(variable_name)
     end
 
+    ##
+    # The tag lists as they stood when the record was loaded or last saved, keyed by context.
+    #
+    # @return [Hash{String => Array<String>}]
+    #
+    # @api private
+    #
+    def original_tag_lists
+      @original_tag_lists ||= {}
+    end
+
+    ##
+    # Records what a context's list looked like before anything touched it, if that has not been
+    # noted already. Called before every change, so the first note wins and later ones are ignored.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [void]
+    #
+    # @api private
+    #
+    def note_tag_list_original(context)
+      key = context.to_s
+      return if original_tag_lists.key?(key)
+
+      original_tag_lists[key] = tag_list_cache_on(key).to_a.dup
+    end
+
+    ##
+    # Notes the original list and drops the cached one, after a tagging was added or removed
+    # through the association rather than through a list.
+    #
+    # The cached list is what `tag_list_on` answers from, and pushing onto `record.tags` does not
+    # go near it -- so without dropping it the list before and after compare equal and nothing
+    # looks changed.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [void]
+    #
+    # @api private
+    #
+    def tag_list_changed_by_association(context)
+      note_tag_list_original(context)
+
+      singular = context.to_s.singularize
+      instance_variable_set("@#{singular}_list", nil)
+      instance_variable_set("@all_#{singular}_list", nil)
+    end
+
+    ##
+    # Whether a context's list differs from the one loaded or last saved.
+    #
+    # Order counts only where the model asked for it with `make_ordered_taggable`.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [TrueClass, FalseClass]
+    #
+    def tag_list_changed_on?(context)
+      key = context.to_s
+      return false unless original_tag_lists.key?(key)
+
+      comparable_tag_list(original_tag_lists[key]) != comparable_tag_list(tag_list_on(key))
+    end
+
+    ##
+    # A context's list as it stood when the record was loaded or last saved.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [Array<String>]
+    #
+    def tag_list_was_on(context)
+      key = context.to_s
+
+      original_tag_lists.key?(key) ? original_tag_lists[key] : tag_list_on(key).to_a
+    end
+
+    ##
+    # A context's list before and after, or `nil` when it has not changed.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [Array<Array<String>>, NilClass]
+    #
+    def tag_list_change_on(context)
+      return unless tag_list_changed_on?(context)
+
+      [tag_list_was_on(context), tag_list_on(context).to_a]
+    end
+
+    ##
+    # The tag list changes this record is carrying, keyed the way Active Model keys `changes`.
+    #
+    # @return [Hash{String => Array<Array<String>>}]
+    #
+    # @api private
+    #
+    def tag_list_changes
+      # assigned_tagging_contexts, not tagging_contexts: the latter reads the
+      # taggings table to find contexts used previously, and a record only has
+      # pending changes in contexts it holds a list for.
+      assigned_tagging_contexts.each_with_object({}) do |context, changes|
+        change = tag_list_change_on(context)
+        changes["#{context.to_s.singularize}_list"] = change if change
+      end
+    end
+
+    ##
+    # The tag list changes written by the most recent save.
+    #
+    # @return [Hash{String => Array<Array<String>>}]
+    #
+    # @api private
+    #
+    def saved_tag_list_changes
+      @saved_tag_list_changes ||= {}
+    end
+
+    ##
+    # Active Model's changes, plus the tag lists.
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess]
+    #
+    def changes
+      super.merge(tag_list_changes)
+    end
+
+    ##
+    # @return [Hash] the previous values of everything changed, tag lists included
+    #
+    def changed_attributes
+      super.merge(tag_list_changes.transform_values(&:first))
+    end
+
+    ##
+    # @return [TrueClass, FalseClass] whether anything changed, tag lists included
+    #
+    def changed?
+      super || tag_list_changes.any?
+    end
+
+    ##
+    # @return [Hash] the changes the last save wrote, tag lists included
+    #
+    def saved_changes
+      super.merge(saved_tag_list_changes)
+    end
+
     ##
     # A context's tag list, loading it from the caching column or the database as needed.
     #
@@ -224,13 +402,22 @@ module MakeTaggable::Taggable
     #
     def tag_list_cache_on(context)
       variable_name = "@#{context.to_s.singularize}_list"
-      if instance_variable_get(variable_name)
-        instance_variable_get(variable_name)
-      elsif cached_tag_list_on(context) && ensure_included_cache_methods! && self.class.caching_tag_list_on?(context)
-        instance_variable_set(variable_name, MakeTaggable.default_parser.new(cached_tag_list_on(context)).parse)
-      else
-        instance_variable_set(variable_name, MakeTaggable::TagList.new(tags_on(context).map(&:name)))
-      end
+      return instance_variable_get(variable_name) if instance_variable_get(variable_name)
+
+      list =
+        if cached_tag_list_on(context) && ensure_included_cache_methods! && self.class.caching_tag_list_on?(context)
+          MakeTaggable.default_parser.new(cached_tag_list_on(context)).parse
+        else
+          MakeTaggable::TagList.new(tags_on(context).map(&:name))
+        end
+
+      # Note what was there the first time the list is built, before anything
+      # can have touched it. A caller holding this list can mutate it in place
+      # -- tag_list.add("x") -- which never goes through the writer, so this is
+      # the only chance to see the original.
+      original_tag_lists[context.to_s] ||= list.to_a.dup
+
+      instance_variable_set(variable_name, list)
     end
 
     ##
@@ -270,11 +457,15 @@ module MakeTaggable::Taggable
       opts = ["#{tagging_table_name}.context = ?", context.to_s]
       scope = base_tags.where(opts)
 
+      group_columns = "#{MakeTaggable::Tag.table_name}.#{MakeTaggable::Tag.primary_key}"
+
       if MakeTaggable::Utils.using_postgresql?
-        group_columns = grouped_column_names_for(MakeTaggable::Tag)
+        # Ordering by an aggregate is why this groups at all. Grouping by the
+        # primary key alone is enough on every supported PostgreSQL -- it works
+        # the functional dependency out itself, and has since 9.1.
         scope.order(Arel.sql("max(#{tagging_table_name}.created_at)")).group(group_columns)
       else
-        scope.group("#{MakeTaggable::Tag.table_name}.#{MakeTaggable::Tag.primary_key}")
+        scope.group(group_columns)
       end.to_a
     end
 
@@ -303,6 +494,10 @@ module MakeTaggable::Taggable
     def set_tag_list_on(context, new_list)
       add_custom_context(context)
 
+      # Before the list is replaced, so the note captures what was there rather
+      # than what is being put there.
+      note_tag_list_original(context)
+
       variable_name = "@#{context.to_s.singularize}_list"
 
       parsed_new_list = MakeTaggable.default_parser.new(new_list).parse
@@ -319,6 +514,23 @@ module MakeTaggable::Taggable
       self.class.tag_types.map(&:to_s) + custom_contexts
     end
 
+    ##
+    # The contexts a save has to consider: the declared ones, plus any context this record has
+    # been handed a list for in memory.
+    #
+    # Deliberately not {#tagging_contexts}, which reads the taggings table to find contexts used
+    # previously. A save only writes lists held in memory, so the ones already loaded are the only
+    # ones that can have anything to write -- and reading the table on every save cost a query
+    # whether or not any tag changed, and broke `strict_loading` outright.
+    #
+    # @return [Array<String>]
+    #
+    # @api private
+    #
+    def assigned_tagging_contexts
+      self.class.tag_types.map(&:to_s) + (@custom_contexts || [])
+    end
+
     ##
     # Reloads the record, discarding the tag lists held in memory.
     #
@@ -346,7 +558,7 @@ module MakeTaggable::Taggable
     # @return [TrueClass]
     #
     def save_tags
-      tagging_contexts.each do |context|
+      assigned_tagging_contexts.each do |context|
         next unless tag_list_cache_set_on(context)
 
         # List of currently assigned tag names
@@ -355,6 +567,13 @@ module MakeTaggable::Taggable
         # Find existing tags or create non-existing tags:
         tags = find_or_create_tags_from_list_with_context(tag_list, context)
 
+        # A tag that failed its own validation comes back unsaved, with a nil
+        # id. Left alone it reaches taggings.create! as `tag_id: nil`, and the
+        # caller is told "Tag can't be blank" -- the wrong attribute, and no
+        # sign of what was actually wrong. Report the tag itself instead.
+        unsaved = tags.reject(&:persisted?)
+        raise ActiveRecord::RecordInvalid.new(unsaved.first) if unsaved.any?
+
         # Tag objects for currently assigned tags
         current_tags = tags_on(context)
 
@@ -387,31 +606,39 @@ module MakeTaggable::Taggable
           taggings.not_owned.by_context(context).where(tag_id: old_tags).destroy_all
         end
 
-        # Create new taggings:
+        # Create new taggings, in a consistent order. Each insert bumps the tag's
+        # counter cache, so two concurrent saves touching the same tags would
+        # otherwise take row locks in whatever order their lists happened to be
+        # in, and deadlock. Ordering is skipped where the model asked for tag
+        # order to be preserved, since there the creation order is the point.
+        new_tags = new_tags.sort_by(&:id) unless self.class.preserve_tag_order?
+
         new_tags.each do |tag|
           taggings.create!(tag_id: tag.id, context: context.to_s, taggable: self)
         end
       end
 
+      settle_tag_list_changes
+
       true
     end
 
-    private
-
-    def ensure_included_cache_methods!
-      self.class.columns
+    # Moves the pending tag list changes into the saved ones, so that after a
+    # save the record reports what the save wrote rather than what it was about
+    # to write. Mirrors what Active Model does for real attributes.
+    def settle_tag_list_changes
+      @saved_tag_list_changes = tag_list_changes
+      original_tag_lists.clear
     end
 
-    # Filters the tag lists from the attribute names.
-    def attributes_for_update(attribute_names)
-      tag_lists = tag_types.map { |tags_type| "#{tags_type.to_s.singularize}_list" }
-      super.delete_if { |attr| tag_lists.include? attr }
+    private
+
+    def comparable_tag_list(list)
+      self.class.preserve_tag_order? ? list.to_a : list.to_a.sort
     end
 
-    # Filters the tag lists from the attribute names.
-    def attributes_for_create(attribute_names)
-      tag_lists = tag_types.map { |tags_type| "#{tags_type.to_s.singularize}_list" }
-      super.delete_if { |attr| tag_lists.include? attr }
+    def ensure_included_cache_methods!
+      self.class.columns
     end
 
     ##

data/lib/make_taggable/taggable/ownership.rb

@@ -164,7 +164,7 @@ module MakeTaggable::Taggable
     # @return [TrueClass]
     #
     def save_owned_tags
-      tagging_contexts.each do |context|
+      assigned_tagging_contexts.each do |context|
         cached_owned_tag_list_on(context).each do |owner, tag_list|
           # Find existing tags or create non-existing tags:
           tags = find_or_create_tags_from_list_with_context(tag_list.uniq, context)
@@ -202,7 +202,10 @@ module MakeTaggable::Taggable
               tag_id: old_tags, context: context).destroy_all
           end
 
-          # Create new taggings:
+          # Create new taggings, in a consistent order -- see the note in
+          # Core#save_tags on why the order matters.
+          new_tags = new_tags.sort_by(&:id) unless self.class.preserve_tag_order?
+
           new_tags.each do |tag|
             taggings.create!(tag_id: tag.id, context: context.to_s, tagger: owner, taggable: self)
           end

data/lib/make_taggable/taggable/related.rb

@@ -115,12 +115,15 @@ module MakeTaggable::Taggable
       "#{klass.arel_table[klass.primary_key].not_eq(id).to_sql} AND" if [self.class.base_class, self.class].include? klass
     end
 
+    # Grouping by the primary key alone is enough on every adapter we support.
+    #
+    # PostgreSQL used to need every selected non-aggregated column listed here,
+    # which is why this branched. Since 9.1 it works the functional dependency
+    # out from the primary key on its own, and listing every column actively
+    # breaks a model with a `json` column -- json has no equality operator, so
+    # it cannot appear in a GROUP BY at all.
     def group_columns(klass)
-      if MakeTaggable::Utils.using_postgresql?
-        grouped_column_names_for(klass)
-      else
-        "#{klass.table_name}.#{klass.primary_key}"
-      end
+      "#{klass.table_name}.#{klass.primary_key}"
     end
 
     def related_where(klass, conditions)
@@ -129,6 +132,42 @@ module MakeTaggable::Taggable
         .group(group_columns(klass))
         .order("count DESC")
         .where(conditions)
+        .extending(CalculationMethods)
+    end
+
+    # These relations select the taggable's columns plus an aliased count, and
+    # order by that alias. Active Record folds the select list into the COUNT()
+    # it builds, which produced SQL no adapter accepts:
+    #
+    #   SELECT COUNT(taggable_models.*, COUNT(tags.id) AS count) ...
+    #
+    # Counting rows instead is not enough on its own either: the relation groups
+    # by primary key over a cross join, so dropping the grouping counts taggings
+    # rather than records, and the ORDER BY still names an alias that a bare
+    # COUNT(*) no longer selects.
+    #
+    # So count the grouped query as a subquery. `klass.unscoped` is the shell
+    # for it because it carries no extension of its own -- counting a relation
+    # derived from this one would re-enter this method.
+    module CalculationMethods
+      ##
+      # The number of related records.
+      #
+      # @param column_name [Symbol, String] accepted for signature compatibility; ignored
+      # @return [Integer]
+      #
+      def count(column_name = :all)
+        ids = except(:select, :order).select(Arel.sql("#{klass.table_name}.#{klass.primary_key}"))
+
+        klass.unscoped.from(Arel.sql("(#{ids.to_sql}) AS #{klass.table_name}_related")).count(:all)
+      end
+
+      ##
+      # @return [Integer] the number of related records
+      #
+      def size
+        loaded? ? to_a.size : count
+      end
     end
   end
 end

data/lib/make_taggable/taggable/tagged_with_query/all_tags_query.rb

@@ -56,7 +56,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
       end
 
       if options[:on].present?
-        condition = condition.and(tagging_arel_table[:context].eq(options[:on]))
+        condition = condition.and(context_predicate)
       end
 
       if (owner = options[:owned_by]).present?
@@ -92,7 +92,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
       end
 
       if options[:on].present?
-        on_condition = on_condition.and(tagging_arel_table[:context].eq(options[:on]))
+        on_condition = on_condition.and(context_predicate)
       end
 
       on_condition

data/lib/make_taggable/taggable/tagged_with_query/exclude_tags_query.rb

@@ -28,7 +28,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
       # Left off, the subquery gathers taggings from other contexts and other
       # times, and excludes records on the strength of them.
       if options[:on].present?
-        on_condition = on_condition.and(tagging_arel_table[:context].eq(options[:on]))
+        on_condition = on_condition.and(context_predicate)
       end
 
       if options[:start_at].present?
@@ -85,7 +85,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
       end
 
       if options[:on].present?
-        on_condition = on_condition.and(tagging_arel_table[:context].eq(options[:on]))
+        on_condition = on_condition.and(context_predicate)
       end
 
       on_condition

data/lib/make_taggable/taggable/tagged_with_query/query_base.rb

@@ -40,8 +40,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
     end
 
     def tag_match_type(tag)
-      matches_attribute = tag_arel_table[:name]
-      matches_attribute = matches_attribute.lower unless MakeTaggable.strict_case_match
+      matches_attribute = folded_name_attribute
 
       if options[:wild].present?
         matches_attribute.matches("%#{escaped_tag(tag)}%", "!", MakeTaggable.strict_case_match)
@@ -51,8 +50,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
     end
 
     def tags_match_type
-      matches_attribute = tag_arel_table[:name]
-      matches_attribute = matches_attribute.lower unless MakeTaggable.strict_case_match
+      matches_attribute = folded_name_attribute
 
       if options[:wild].present?
         matches_attribute.matches_any(tag_list.map { |tag| "%#{escaped_tag(tag)}%" }, "!", MakeTaggable.strict_case_match)
@@ -85,7 +83,7 @@ module MakeTaggable::Taggable::TaggedWithQuery
       end
 
       if options[:on].present?
-        condition = condition.and(tagging_arel_table[:context].eq(options[:on]))
+        condition = condition.and(context_predicate)
       end
 
       if (owner = options[:owned_by]).present?
@@ -101,6 +99,32 @@ module MakeTaggable::Taggable::TaggedWithQuery
       "(SELECT count(*) FROM #{tagging_model.table_name} WHERE #{matching_taggings.to_sql}) desc"
     end
 
+    # The predicate restricting a query to the context or contexts asked for.
+    #
+    # `:on` takes one context or several, so a caller can search a subset without either naming a
+    # single one or falling back to every context there is.
+    def context_predicate(tagging_table = tagging_arel_table)
+      contexts = Array(options[:on]).map(&:to_s)
+
+      contexts.one? ? tagging_table[:context].eq(contexts.first) : tagging_table[:context].in(contexts)
+    end
+
+    # The tag name attribute to match against, folded where the comparison will not fold it itself.
+    #
+    # PostgreSQL matches with ILIKE, which is already case-insensitive, so wrapping the column in
+    # LOWER() there changes nothing and costs everything -- the expression stops being sargable, so
+    # no index on tags.name can be used, including a trigram index built for wild searches.
+    #
+    # The other adapters do need it. The MySQL migration collates tags.name as utf8mb4_bin, which
+    # makes LIKE case-sensitive, and folding keeps SQLite consistent with the rest.
+    def folded_name_attribute
+      attribute = tag_arel_table[:name]
+
+      return attribute if MakeTaggable.strict_case_match || MakeTaggable::Utils.using_postgresql?
+
+      attribute.lower
+    end
+
     def escaped_tag(tag)
       tag = tag.downcase unless MakeTaggable.strict_case_match
       MakeTaggable::Utils.escape_like(tag)

data/lib/make_taggable/version.rb

@@ -6,5 +6,5 @@ module MakeTaggable
   #
   # @return [String]
   #
-  VERSION = "1.3.0"
+  VERSION = "1.5.0"
 end

data/lib/make_taggable.rb

@@ -47,7 +47,6 @@ module MakeTaggable
     autoload :Core
     autoload :Ownership
     autoload :Related
-    autoload :TagListType
   end
 
   autoload :Utils
@@ -255,16 +254,40 @@ module MakeTaggable
     #   `utf8mb4_general_ci`
     # @return [NilClass]
     #
+    ##
+    # Applies the collation `tags.name` should carry on MySQL, if it does not carry it already.
+    #
+    # This is a schema change, and the documented way to reach it is an initializer -- which runs
+    # once per process, so once per web worker, background worker, console and rake task. Issuing
+    # `ALTER TABLE` from each of those takes a metadata lock on the tags table every time. So the
+    # current collation is read first and the statement skipped when it already matches, which
+    # turns the common case into one cheap catalogue read.
+    #
+    # @param bincoll [TrueClass, FalseClass] whether to apply the binary collation
+    # @return [void]
+    #
     def self.apply_binary_collation(bincoll)
-      if Utils.using_mysql?
-        coll = "utf8mb4_general_ci"
-        coll = "utf8mb4_bin" if bincoll
-        begin
-          ActiveRecord::Migration.execute("ALTER TABLE #{Tag.table_name} MODIFY name varchar(255) CHARACTER SET utf8mb4 COLLATE #{coll};")
-        rescue => e
-          puts "Trapping #{e.class}: collation parameter ignored while migrating for the first time."
-        end
-      end
+      return unless Utils.using_mysql?
+
+      collation = bincoll ? "utf8mb4_bin" : "utf8mb4_general_ci"
+
+      # Nothing to apply to yet -- this runs during the first migration, before
+      # the table exists.
+      return unless Utils.connection.table_exists?(Tag.table_name)
+      return if current_tag_name_collation == collation
+
+      ActiveRecord::Migration.execute(
+        "ALTER TABLE #{Tag.table_name} MODIFY name varchar(255) CHARACTER SET utf8mb4 COLLATE #{collation};"
+      )
+    end
+
+    ##
+    # The collation `tags.name` currently carries, or `nil` where it cannot be read.
+    #
+    # @return [String, NilClass]
+    #
+    def self.current_tag_name_collation
+      Utils.connection.columns(Tag.table_name).find { |column| column.name == "name" }&.collation
     end
   end
   setup

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Matthew Kennedy
@@ -33,6 +33,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AATO_ISSUE_TRIAGE.md
+- AATO_UPSTREAM_COMMIT_REVIEW.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
@@ -70,7 +72,6 @@ files:
 - lib/make_taggable/taggable/core.rb
 - lib/make_taggable/taggable/ownership.rb
 - lib/make_taggable/taggable/related.rb
-- lib/make_taggable/taggable/tag_list_type.rb
 - lib/make_taggable/taggable/tagged_with_query.rb
 - lib/make_taggable/taggable/tagged_with_query/all_tags_query.rb
 - lib/make_taggable/taggable/tagged_with_query/any_tags_query.rb

data/lib/make_taggable/taggable/tag_list_type.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module MakeTaggable::Taggable
-  ##
-  # The Active Model type backing each generated `*_list` attribute, so tag lists take part in
-  # dirty tracking alongside ordinary columns.
-  #
-  # @api private
-  #
-  class TagListType < ActiveModel::Type::Value
-  end
-end