make_taggable 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be8e033e4d750a0bc75a77f652351843c096f38d8f8332f56e9d642e2085f12b
-  data.tar.gz: 698531499c7e7636b241b854cf60e2e2aee3799af3dba3d2d8a5f1ae2ff954f1
+  metadata.gz: 9313e4b6fc5d1b81f44b56665f2dbf6c6a8c8a8213f492b00e17e1e20c0a27bb
+  data.tar.gz: ef32dbb42368817bea0791803f1013f1481d58ca50992551131483b7fac416ab
 SHA512:
-  metadata.gz: c2f772cac980b2bab6c101c087916f3083f519aaec61c8c45ad4cd8750ab95dc6f9534d4ac2a511a6411872590dcfb4a58c3af7f68611458365ff8e5ce024866
-  data.tar.gz: 50aae450f2dfd5923ecf8c18a348b6e7e27b761d71d7fd59b61498c338341f607b735194b2a56da154624ad71e84a748f3a3aebec84beb0a6a21b3a7d0f244b0
+  metadata.gz: 750c882a7d5836848cfd7d536896403cb619868121a817d9aa89ac2aed7e36d6f3d9cf70be5be04e1dd428e35484957b1f49ba17a2e7ef50f2a67adc271d7510
+  data.tar.gz: d14dba688a46a5e48507a082d7b65071aa8e0197df657156c3859652fcabd8eca5e0c5256033f7a9c4665d197c87177f0d9107c010e811d671fc1de2011b4d1f

data/CHANGELOG.md

@@ -5,7 +5,26 @@ 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.0.0] - unreleased
+## [1.1.0] - 2026-08-22
+
+### Added
+
+- A migration adding `taggings_unowned_idx`, a partial unique index that stops duplicate unowned
+  taggings at the database level. `taggings_idx` never could: it spans the nullable tagger columns,
+  and SQL compares nulls as distinct, so only the model validation stood in the way and a validation
+  cannot win a race. MySQL has no partial indexes, so the migration is a no-op there.
+
+  Install it with `rails make_taggable_engine:install:migrations`. If it fails, the table already
+  holds duplicates -- see [docs/database.md](docs/database.md).
+
+### Internal
+
+- The suite runs in random order. Examples were leaking state into each other: tagging declarations
+  on the shared models, and the library configuration -- one example leaving `remove_unused_tags`
+  on could make an unrelated example fail a foreign key check. Both are now snapshotted and restored
+  around every example.
+
+## [1.0.0] - 2026-08-22
 
 ### Breaking
 

data/CONTRIBUTING.md

@@ -47,10 +47,16 @@ bundle exec appraisal rake
 
 ### A note on test ordering
 
-The suite runs in defined order. Several examples mutate shared model classes — adding a context to
-`TaggableModel`, flipping `preserve_tag_order` — and rely on siblings having run first. Randomising
-the order exposes this. Making those examples self-contained is welcome work; until then, please
-don't add new examples that depend on a sibling's side effects.
+The suite runs in random order, so an example that depends on a sibling having run first will fail
+sooner or later. Reproduce a failure with the seed it reports:
+
+```shell
+bundle exec rspec --order random:12345
+```
+
+Examples are free to change global state — the tagging declarations on the shared models, and the
+`MakeTaggable` configuration — because `spec_helper.rb` snapshots both and restores them after every
+example. Anything else you make global is yours to clean up.
 
 ## Documentation
 

data/UPGRADING.md

@@ -23,6 +23,10 @@ This release renames the declaration methods and changes how delimiters are esca
 
 4. Requirements are now Ruby 3.2 and Active Record 7.2 or newer.
 
+Note for anyone upgrading past 1.0: a later migration adds a unique index
+preventing duplicate unowned taggings. If it fails, your taggings table
+already holds duplicates -- docs/database.md has a snippet to clear them.
+
 Install any new migrations:
 
     rails make_taggable_engine:install:migrations

data/db/migrate/6_add_unowned_taggings_unique_index.rb

@@ -0,0 +1,18 @@
+class AddUnownedTaggingsUniqueIndex < ActiveRecord::Migration[7.2]
+  # taggings_idx spans tagger_id and tagger_type, which are NULL on every
+  # tagging nobody owns. SQL compares NULLs as distinct, so that index does not
+  # stop two identical unowned taggings -- only the model validation does, and a
+  # validation cannot win a race between two concurrent writes.
+  #
+  # A partial index closes it. MySQL has no partial indexes, so it keeps the
+  # validation on its own.
+  def change
+    return if MakeTaggable::Utils.using_mysql?
+
+    add_index MakeTaggable.taggings_table,
+      [:tag_id, :taggable_id, :taggable_type, :context],
+      unique: true,
+      where: "tagger_id IS NULL",
+      name: "taggings_unowned_idx"
+  end
+end

data/docs/database.md

@@ -34,22 +34,39 @@ That suits read-heavy tagging. If your application writes taggings in bulk, the
 looking at — every index is maintained on insert, and several of the standalone ones are prefixes of
 composites that already exist. Drop what your queries do not use.
 
-### The unique index does not stop duplicate unowned taggings
+### Duplicate unowned taggings
 
 `taggings_idx` is unique across
 `[tag_id, taggable_id, taggable_type, context, tagger_id, tagger_type]`. Because `tagger_id` and
-`tagger_type` are null for unowned taggings, and SQL treats nulls as distinct, **the database will
-accept two identical unowned taggings**. Only the Active Record uniqueness validation prevents them,
-and a validation cannot prevent a race between two concurrent writes.
+`tagger_type` are null on every tagging nobody owns, and SQL compares nulls as distinct, that index
+does not stop two identical unowned taggings. Only the model validation does, and a validation
+cannot win a race between two concurrent writes.
 
-If duplicate taggings would be a problem for you, add a partial unique index. On PostgreSQL:
+Migration 6 closes it with a partial unique index, `taggings_unowned_idx`, covering
+`[tag_id, taggable_id, taggable_type, context]` where `tagger_id IS NULL`.
+
+**MySQL has no partial indexes**, so it keeps the validation on its own and the migration is a no-op
+there. If duplicate taggings would be a serious problem on MySQL, the usual workaround is a
+generated column holding a sentinel for the null tagger, indexed uniquely alongside the rest.
+
+If the migration fails with a uniqueness error, the table already contains duplicates. Remove them
+first:
 
 ```ruby
-add_index :taggings,
-  [:tag_id, :taggable_id, :taggable_type, :context],
-  unique: true,
-  where: "tagger_id IS NULL",
-  name: "taggings_unowned_idx"
+duplicates = MakeTaggable::Tagging
+  .where(tagger_id: nil)
+  .group(:tag_id, :taggable_id, :taggable_type, :context)
+  .having("COUNT(*) > 1")
+  .pluck(Arel.sql("MIN(id), COUNT(*)"))
+
+duplicates.each do |keep_id, _count|
+  tagging = MakeTaggable::Tagging.find(keep_id)
+  MakeTaggable::Tagging
+    .where(tagger_id: nil, tag_id: tagging.tag_id, taggable_id: tagging.taggable_id,
+      taggable_type: tagging.taggable_type, context: tagging.context)
+    .where.not(id: keep_id)
+    .delete_all
+end
 ```
 
 ## PostgreSQL

data/lib/make_taggable/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Matthew Kennedy
@@ -46,6 +46,7 @@ files:
 - db/migrate/3_change_tag_name_collation_mysql.rb
 - db/migrate/4_add_index_to_tags.rb
 - db/migrate/5_add_index_to_taggings.rb
+- db/migrate/6_add_unowned_taggings_unique_index.rb
 - docs/caching.md
 - docs/configuration.md
 - docs/contexts.md
@@ -116,6 +117,10 @@ post_install_message: |
 
   4. Requirements are now Ruby 3.2 and Active Record 7.2 or newer.
 
+  Note for anyone upgrading past 1.0: a later migration adds a unique index
+  preventing duplicate unowned taggings. If it fails, your taggings table
+  already holds duplicates -- docs/database.md has a snippet to clear them.
+
   Install any new migrations:
 
       rails make_taggable_engine:install:migrations