Peter Boling | Flag_shih_tzu

Introducing flag_shih_tzu

2011-03-09T00:00:00+00:00

[![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS or refugee efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS or refugee efforts using Patreon][🖇patreon-img]][🖇patreon]

Getting Started

For more information and detailed examples, please visit the documentation.

Supporting this Project

Maintaining flag_shih_tzu

2013-08-06T19:30:16+00:00

Bit Fields for Active Record

What is a bit field?

https://en.wikipedia.org/wiki/Bit_field

What is a bitwise operation?

https://en.wikipedia.org/wiki/Bitwise_operation

flag_shih_tzu supports both :bit_operator and :in_list query modes, but only :in_list can will utilize a database index.

What does it look like?

class Lead < ActiveRecord::Base
  include FlagShihTzu
  has_flags 1 => :warm_up_email_sent,
            2 => :follow_up_call_made,
            3 => :final_email_sent,
            4 => :appointment_scheduled,
            5 => :not_interested,
            # You can specify use any integer column to use for flags!
            column: 'actions_taken',
            flag_query_mode: :in_list # or :bit_operator
end

# Flag values always default to false
lead = Lead.new(warm_up_email_sent: true)
# Provides accessors with the same API as a regular boolean column:
lead.warm_up_email_sent # => true
lead.actions_taken # => 1
lead.follow_up_call_made? # => false
lead.follow_up_call_made = true
lead.follow_up_call_made? # => true
lead.actions_taken # => 3

Why Should You Use flag_shih_tzu

2015-12-07T07:21:16+00:00

What is it?

See the what is it post.

Why should you use it?

No migrations needed for new boolean attributes
Avoids ALTER TABLE when adding a new boolean field to a model, which can be important for very large tables
Only the one integer column needs to be indexed
The index is actually meaningful, unlike a boolean column index
Bitwise operations are fast, indexes are even faster, and you can use either one
Adds scopes to easily access collections of records with specific fields
- Chained scopes to combine sql for different bit fields for maximum performance
Provides condition builder methods for each bit field so you can construct your own custom SQL with the correct bit field values for the list.
- Table alias option to allow it to work with tables aliased in a query (e.g. custom joins)
Has a set_flag_sql method useful when doing mass updates without initializing object for each row.
Has a update_flag! method useful when you want to set a flag, but avoid validations and callbacks on the record.

Why is it better than the alternative?

The competition is Michael Grosser’s bitfields, and as always, it depends on your needs. Grosser’s library is less than half the size of flag_shih_tzu, and has far fewer features, and a much smaller compatibility matrix. Some of the differences are laid out below.

For some things however, you only have one option. If you are still on legacy Ruby or legacy Rails, or using jRuby, then use flag_shih_tzu. If you need multiple flag columns on a single model, use flag_shih_tzu. If you want to use it with form builders, it is slightly easier with flag_shih_tzu.

comparison	flag_shih_tzu	bitfields
Age	Mar 2009	Mar 2010
Legacy MRI Support	1.8.7, 1.9.2	None
Current MRI Support	1.9.3, 2.0, 2.1, 2.2	1.9.3 2.0
Current jRuby Support	jRuby-1.7, jRuby-9.0	None
Legacy Rails Support	2.3, 3.0, 3.1, 3.2	None
Current Rails Support	2.3, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2	3.2, 4.0, 4.1, 4.2
Stars
Forks
Downloads (All-time)
Downloads (Today)
Code Quality
Build
Documentation
Dependency Status		Unknown
Custom Flag Column Name	Yes	Yes
Multiple Flag Columns per Model	Yes	No
Has analog to `update_column`	Yes	No
Built-in use with `update_all`	Yes	Yes
Built-in use with form builders	Yes	No
Built-in Validator	Yes	No
Change Tracking `_was`	No	Yes
Change Tracking `_changed?`	Yes	Yes
Change Tracking `_change`	No	Yes
Scopes Optional	Yes	Yes

Efficient Boolean Flags with flag_shih_tzu

2024-10-02T13:45:00+00:00

Store multiple boolean flags efficiently in a single integer column with flag_shih_tzu.

Why Use Bit Flags?

Instead of creating multiple boolean columns, store all flags in one integer:

Save database space
Faster queries
Cleaner schema
Better performance

Setup

Add to your Gemfile:

gem 'flag_shih_tzu'

Define Flags

class User < ActiveRecord::Base
  include FlagShihTzu
  
  has_flags 1 => :active,
            2 => :admin,
            3 => :verified,
            4 => :premium,
            column: 'flags'
end

Usage

user = User.new
user.active = true
user.admin = true
user.save

# Query users
User.active
User.admin
User.not_verified

# Check flags
user.active?      # => true
user.verified?    # => false

# Set multiple flags
user.flags = [:active, :verified, :premium]

Database Migration

class AddFlagsToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :flags, :integer, default: 0, null: false
  end
end

Advanced Features

Named scopes for each flag
Flag combinations
Default values
SQL optimizations

Perfect for managing user permissions and settings!

flag_shih_tzu v0.3.19 released!

2025-06-01T00:41:30+00:00

Full Changelog: https://github.com/pboling/flag_shih_tzu/compare/v0.3.18…v0.3.19

flag_shih_tzu 1.0.0: Tri-state and multi-bit flags

2026-05-26T00:00:00+00:00

Version 1.0.0 adds tri-state values and configurable bit widths and encoders, extending flags beyond true and false. Array and hash assignment also let callers update named flags without calculating packed integers themselves.

Read the upstream release notes for the complete changes and see the project repository for usage and installation.

flag_shih_tzu v1.0.6 released!

2026-09-12T01:55:47+00:00

1.0.6 - 2026-09-12

TAG: v1.0.6
COVERAGE: N/A
BRANCH COVERAGE: N/A
0.00% documented

Changed

kettle-jem-template-20260801-001 - Generated README gem dashboard links now use ClickGems instead of BestGems.
[kc] kettle-jem/prepare: updated 8 project files:
- dependencies (8)
[kc] kettle-jem/template: updated 4 project files:
- code and tests (1)
- dependencies (2)
- other (1)

Fixed

kettle-jem-template-20260801-002 - Generated RSpec helpers now normalize managed configuration block bindings structurally, preventing mixed block parameter names from producing invalid configuration after a merge.
kettle-jem-template-20260801-003 - Generated project metadata and documentation now normalize configured underscore hostnames to valid hyphenated hostnames.
kettle-jem-template-20260801-004 - Generated organization README logos now use GitHub’s stable organization avatar endpoint instead of assuming a matching Galtzo-hosted asset exists.
kettle-jem-template-20260802-001 - Devcontainer JSON files now merge as JSONC, preserving comments and trailing commas during template updates.
Restore the ActiveRecord test dependencies required by the default development bundle.
Restore README link definitions required by the pre-release Markdown reference validator.
Restore the ActiveRecord test bundle removed by an earlier template pass. 1.0.6: https://github.com/galtzo-floss/flag_shih_tzu/compare/v1.0.5…v1.0.6 1.0.6t: https://github.com/galtzo-floss/flag_shih_tzu/releases/tag/v1.0.6 Community support 👉️ [![Ruby Users Forum][✉️ruby-forum-img]][✉️ruby-forum] Many paths lead to being a sponsor or a backer of this project. Are you on such a path? ⛳liberapay-img: https://img.shields.io/liberapay/goal/pboling.svg?logo=liberapay&color=a51611&style=flat ⛳liberapay: https://liberapay.com/pboling/donate 🖇osc-backers: https://opencollective.com/galtzo-floss#backer 🖇osc-backers-i: https://opencollective.com/galtzo-floss/backers/badge.svg?style=flat 🖇osc-sponsors: https://opencollective.com/galtzo-floss#sponsor 🖇osc-sponsors-i: https://opencollective.com/galtzo-floss/sponsors/badge.svg?style=flat 🖇sponsor-img: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github 🖇sponsor: https://github.com/sponsors/pboling 🖇kofi-img: https://img.shields.io/badge/ko–fi-%E2%9C%93-a51611.svg?style=flat 🖇kofi: https://ko-fi.com/pboling 🖇buyme-small-img: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat 🖇buyme: https://www.buymeacoffee.com/pboling 🖇paypal-img: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal 🖇paypal: https://www.paypal.com/paypalme/peterboling ✉️discord-invite: https://discord.gg/3qme4XHNKN ✉️discord-invite-img: https://img.shields.io/discord/1373797679469170758?style=flat [✉️ruby-forum]: https://www.rubyforum.org/tag/flag-shih-tzu [✉️ruby-forum-img]: https://img.shields.io/discourse/topics?server=https%3A%2F%2Fwww.rubyforum.org&style=flat&logo=discourse&label=Ruby%20Users%20Forum

Official Discord 👉️

Many paths lead to being a sponsor or a backer of this project. Are you on such a path?