make_taggable 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b40ab74ad5312aa300ba26015e4fc7d5da67e5e37c5f4c7efb235aa494e28d0
-  data.tar.gz: 84db5687e59dfb33259222e47bc58fdb7d94dd35882faafc2f1ceede7effc841
+  metadata.gz: 1d900a8ac37e0f88ead6c0516fd30ddee5e8cc11c893b7d64e85c090a8b59598
+  data.tar.gz: b364eef565e3a171c56558f928360de5230c445b4b210e1aab8f536f9b998c70
 SHA512:
-  metadata.gz: a71b99737d5b1f09b1fe76ffa1b5710c50f6330d1222d107bdfd685c966f6c4681040a688d29df8427b5cf3e91e1d29c458d00085de110187272afb925393ebb
-  data.tar.gz: 6ce73b0b7e0497f084080f1d4a774c974f2acb0c94ffec9d90bdbe8326f4a1e2f28721f5b4372c7d7b71ddbe0c567490faec4eb22cf884b9723fc39cddc579f0
+  metadata.gz: 611fd4635e580ff5aaaee314600d2d66e7cdb70a2bd22d8988e3eb541c3d632fc25625e485880821beeec8f0bfb71677242f3d0d14ba96e98e0dd4d15038e0ae
+  data.tar.gz: b1713ea6a65eb7a8e45dfb0d4b8d41c9d72334cfb8de93ef2c1e60a21a6a4e04758acdcb7761a117b8b275f0aecb3e98d78258a8c7f8389f433836353e676958

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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

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/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
 

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:
 
@@ -183,6 +189,14 @@ its own — add `.distinct` if you want records back rather than matches.
   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

@@ -158,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

data/lib/make_taggable/taggable/core.rb

@@ -118,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
@@ -179,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
@@ -442,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
 
@@ -587,7 +606,13 @@ 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

data/lib/make_taggable/taggable/ownership.rb

@@ -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/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.4.0"
+  VERSION = "1.5.0"
 end

data/lib/make_taggable.rb

@@ -254,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.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Matthew Kennedy