Why flag_shih_tzu is changing its default SQL for bit flags

flag_shih_tzu stores many boolean attributes in one integer column. Each boolean gets one bit 〰️ well that used to be true 〰️ v1.0.0 supports multi-bit flags, ternary, or even more for enum flags! 〰️ anyways, not the point of this article, so let's keep going:

class User < ApplicationRecord
  include FlagShihTzu

  has_flags 1 => :warpdrive,
    2 => :shields
end

Historically, the gem's default SQL for querying one flag used an IN() list.
For warpdrive, the condition looked like this:

users.flags in (1,3)

That is correct while the application knows about exactly two flags. The
possible values where bit 1 is enabled are 1 and 3.

The problem appears when flags are added during a rolling deploy.

The deploy that breaks old queries

Suppose the next version of the app adds a new flag:

class User < ApplicationRecord
  include FlagShihTzu

  has_flags 1 => :warpdrive,
    2 => :shields,
    3 => :premium
end

In the same deploy, a migration or background job sets the new bit for existing
rows:

UPDATE users
SET flags = flags | 4
WHERE created_at < '2026-01-01'

A user that previously had only warpdrive moved from flags = 1 to
flags = 5.

During a rolling deploy, old application processes may still be serving
requests. Those old processes still think only two flags exist, so they still
query warpdrive with:

users.flags in (1,3)

That query no longer returns the flags = 5 row, even though the warpdrive
bit is still set.

That is the bug. Nothing is wrong with the row. The old query is too dependent
on knowing every possible future flag combination.

Bit operators match the model

The next major flag_shih_tzu release changes the default query mode to
:bit_operator.

The same warpdrive query becomes:

users.flags & 1 = 1

That condition asks the database the same question the application asks:
"is this bit set?"

It keeps working if the row is 1, 3, 5, 7, or any future value with
the warpdrive bit enabled.

For negated scopes, the generated SQL becomes:

users.flags & 1 = 0

Chained flag conditions also use bit checks by default, so a query for
warpdrive and shields becomes:

users.flags & 1 = 1 AND users.flags & 2 = 2

This is a breaking change

This changes generated SQL, so it belongs in a major release.

Most application code should not need to change. Calls like
User.warpdrive, User.not_warpdrive, and User.warpdrive_condition keep the
same Ruby API. The SQL string and database query plan may change.

If your application depends on the old SQL shape, you can opt back in globally:

FlagShihTzu.default_flag_query_mode = :in_list

Or per model declaration:

has_flags 1 => :warpdrive,
  2 => :shields,
  flag_query_mode: :in_list

The old mode is still supported. It is just no longer the safest default.

Performance tradeoff

An IN() list can be faster for some databases and indexes when the set of
flags is small and fixed. A bit operation may not use the same index strategy.

That tradeoff is real. But defaults should protect correctness first.

If your app has a fixed set of flags and you have measured that IN() lists
perform better for your workload, keep using :in_list.

If your app may add flags over time, especially during rolling deploys, the new
default avoids a subtle class of production bugs.

Why this matters

Bit flags are attractive because they let applications add boolean features
without changing table schemas. That benefit is only complete if the query
strategy also tolerates new flags appearing while old app processes are still
alive.

flags & bit = bit does that. flags in (known_combinations) does not.

That is why flag_shih_tzu is making :bit_operator the default.

推荐订阅源