pboling / flag_shih_tzu

Bit fields for ActiveRecord

FlagShihTzu

Bit fields for ActiveRecord

Project	FlagShihTzu
gem name	flag_shih_tzu
license
expert support
download rank
version
dependencies
code quality
inline documenation
continuous integration
test coverage
homepage	https://github.com/pboling/flag_shih_tzu
documentation	http://rdoc.info/github/pboling/flag_shih_tzu/frames
live chat
Spread ♡ⓛⓞⓥⓔ♡	🌏, 👼, , , 🌹

Table of Contents

• FlagShihTzu
  • Summary
  • Prerequisites
    • Compatibility Matrix
  • Installation
    • Rails 2.x
    • Rails 3
  • Usage
    • Defaults (Important)
    • Database Migration
    • Adding to the Model
    • Bit Fields: How it stores the values
    • Using a custom column name
    • Generated boolean patterned instance methods
    • Callbacks and Validations
    • Generated class methods
    • Generated named scopes
    • Examples for using the generated methods
    • Support for manually building conditions
    • Choosing a query mode
    • Updating flag column by raw sql
    • Skipping flag column check
  • Running the gem tests
  • Authors
  • How you can help!
  • Contributing
  • Versioning
  • 2012 Change of Ownership and 0.3.X Release Notes
  • Alternatives
  • License

Summary

An extension for ActiveRecord to store a collection of boolean attributes in a single integer column as a bit field.

This gem lets you use a single integer column in an ActiveRecord model to store a collection of boolean attributes (flags). Each flag can be used almost in the same way you would use any boolean attribute on an ActiveRecord object.

The benefits:

• No migrations needed for new boolean attributes. This helps a lot if you have very large db-tables, on which you want to avoid ALTER TABLE whenever possible.
• Only the one integer column needs to be indexed.
• Bitwise Operations are fast!

Using FlagShihTzu, you can add new boolean attributes whenever you want, without needing any migration. Just add a new flag to the has_flags call.

What is a "Shih Tzu"?

Prerequisites

The gem is actively being tested against:

• MySQL, PostgreSQL and SQLite3 databases (Both Ruby and JRuby adapters)
• ActiveRecord versions 2.3.x, 3.0.x, 3.1.x, 3.2.x, 4.0.x, 4.1.x, 4.2.x, 5.0.x, 5.1.x, 5.2.x
• Ruby 1.9.3, 2.0.0, 2.1.10, 2.2.10, 2.3.7, 2.4.4, 2.5.1, jruby-1.7.x, jruby-9.1.x
• Travis tests the supported builds. See .travis.yml for the matrix.
• All of the supported builds can also be run locally using the wwtd gem.
• Forthcoming flag_shih_tzu v1.0 will only support Ruby 2.2+, JRuby-9.1+ and Rails 4.2+

Compatibility Matrix

Ruby / Active Record	2.3.x	3.0.x	3.1.x	3.2.x	4.0.x	4.1.x	4.2.x	5.0.x	5.1.x	5.2.x
1.9.3	✓	✓	✓	✓
2.0.0		✓	✓	✓	✓	✓	✓
2.1.x				✓	✓	✓	✓
2.2.0-2.2.1				✓	✓	✓	✓
2.2.2+				✓	✓	✓	✓	✓	✓	✓
2.3.x				✓	✓	✓	✓	✓	✓	✓
2.4.x							✓	✓	✓	✓
2.5.x							✓	✓	✓	✓
jruby-1.7.x	?	?	✓	✓	✓	✓	✓
jruby-9.1		✓	✓	✓	✓	✓	✓	✓	✓	✓
jruby-9.2							✓	✓	✓	✓

• Notes
  • JRuby 1.7.x aims for MRI 1.9.3 compatibility
    • ? indicates incompatible due to 2 failures in the test suite.
  • JRuby 9.1 aims for MRI 2.2 compatibility
  • JRuby 9.2 aims for MRI 2.5 compatibility
  • Forthcoming flag_shih_tzu v1.0 will only support Ruby 2.2+, JRuby-9.1+ and Rails 4.2+

Legacy

• Ruby 1.8.7 compatibility is in the 0.2.X branch and no further releases are expected. If you need a patch submit a pull request.

• Ruby 1.9.3, 2.0.0, 2.1.x, and 2.2.x compatibility is still current on master, and the 0.3.x series releases, but those EOL'd Rubies, and any others that become EOL'd in the meantime, will not be supported in the next major release, version 1.0.

Installation

Rails 2.x

In environment.rb:

config.gem 'flag_shih_tzu'

Then:

$ rake gems:install # use sudo if necessary

Rails 3

In Gemfile:

gem 'flag_shih_tzu'

Then:

$ bundle install

Usage

FlagShihTzu assumes that your ActiveRecord model already has an integer field to store the flags, which should be defined to not allow NULL values and should have a default value of 0.

Defaults (Important)

• Due to the default of 0, all flags are initially set to "false").
• For a default of true it will probably be easier in the long run to negate the flag's meaning / name. ** Such as switched_on => switched_off
• If you really want a different, non-zero, default value for a flag column, proceed adroitly with a different sql default for the flag column.

Database Migration

I like to document the intent of the flags column in the migration when I can...

change_table :spaceships do |t|
  t.integer     :flags, :null => false, :default => 0 # flag_shih_tzu-managed bit field
  # Effective booleans which will be stored on the flags column:
  # t.boolean      :warpdrive
  # t.boolean      :shields
  # t.boolean      :electrolytes
end

Adding to the Model

class Spaceship < ActiveRecord::Base
  include FlagShihTzu

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

has_flags takes a hash. The keys must be positive integers and represent the position of the bit being used to enable or disable the flag. The keys must not be changed once in use, or you will get incorrect results. That is why the plugin forces you to set them explicitly. The values are symbols for the flags being created.

Bit Fields: How it stores the values

As said, FlagShihTzu uses a single integer column to store the values for all the defined flags as a [bit field][bitfield].

The bit position of a flag corresponds to the given key.

This way, we can use [bitwise operators][bit_operation] on the stored integer value to set, unset and check individual flags.

              `---+---+---+                +---+---+---`
              |   |   |   |                |   |   |   |
Bit position  | 3 | 2 | 1 |                | 3 | 2 | 1 |
(flag key)    |   |   |   |                |   |   |   |
              `---+---+---+                +---+---+---`
              |   |   |   |                |   |   |   |
Bit value     | 4 | 2 | 1 |                | 4 | 2 | 1 |
              |   |   |   |                |   |   |   |
              `---+---+---+                +---+---+---`
              | e | s | w |                | e | s | w |
              | l | h | a |                | l | h | a |
              | e | i | r |                | e | i | r |
              | c | e | p |                | c | e | p |
              | t | l | d |                | t | l | d |
              | r | d | r |                | r | d | r |
              | o | s | i |                | o | s | i |
              | l |   | v |                | l |   | v |
              | y |   | e |                | y |   | e |
              | t |   |   |                | t |   |   |
              | e |   |   |                | e |   |   |
              | s |   |   |                | s |   |   |
              `---+---+---+                +---+---+---`
              | 1 | 1 | 0 | = 4 ` 2 = 6    | 1 | 0 | 1 | = 4 ` 1 = 5
              `---+---+---+                +---+---+---`

Read more about bit fields here: http://en.wikipedia.org/wiki/Bit_field

Using a custom column name

The default column name to store the flags is flags, but you can provide a custom column name using the :column option. This allows you to use different columns for separate flags:

has_flags 1 => :warpdrive,
          2 => :shields,
          3 => :electrolytes,
          :column => 'features'

has_flags 1 => :spock,
          2 => :scott,
          3 => :kirk,
          :column => 'crew'

Generated boolean patterned instance methods

Calling has_flags, as shown above on the 'features' column, creates the following instance methods on Spaceship:

Spaceship#all_features # [:warpdrive, :shields, :electrolytes]
Spaceship#selected_features
Spaceship#select_all_features
Spaceship#unselect_all_features
Spaceship#selected_features=

Spaceship#warpdrive
Spaceship#warpdrive?
Spaceship#warpdrive=
Spaceship#not_warpdrive
Spaceship#not_warpdrive?
Spaceship#not_warpdrive=
Spaceship#warpdrive_changed?
Spaceship#has_warpdrive?

Spaceship#shields
Spaceship#shields?
Spaceship#shields=
Spaceship#not_shields
Spaceship#not_shields?
Spaceship#not_shields=
Spaceship#shields_changed?
Spaceship#has_shield?

Spaceship#electrolytes
Spaceship#electrolytes?
Spaceship#electrolytes=
Spaceship#not_electrolytes
Spaceship#not_electrolytes?
Spaceship#not_electrolytes=
Spaceship#electrolytes_changed?
Spaceship#has_electrolyte?

Callbacks and Validations

Optionally, you can set the :bang_methods option to true to also define the bang methods:

Spaceship#electrolytes!     # will save the bitwise equivalent of electrolytes = true on the record
Spaceship#not_electrolytes! # will save the bitwise equivalent of electrolytes = false on the record

which respectively enables or disables the electrolytes flag.

The :bang_methods does not save the records to the database, meaning it cannot engage validations and callbacks.

Alternatively, if you do want to save a flag to the database, while still avoiding validations and callbacks, use update_flag! which:

• sets a flag on a database record without triggering callbacks or validations
• optionally syncs the ruby instance with new flag value, by default it does not.

Example:

update_flag!(flag_name, flag_value, update_instance = false)

Generated class methods

Calling has_flags as shown above creates the following class methods on Spaceship:

Spaceship.flag_columns      # [:features, :crew]

Generated named scopes

The following named scopes become available:

Spaceship.warpdrive         # :conditions => "(spaceships.flags in (1,3,5,7))"
Spaceship.not_warpdrive     # :conditions => "(spaceships.flags not in (1,3,5,7))"
Spaceship.shields           # :conditions => "(spaceships.flags in (2,3,6,7))"
Spaceship.not_shields       # :conditions => "(spaceships.flags not in (2,3,6,7))"
Spaceship.electrolytes      # :conditions => "(spaceships.flags in (4,5,6,7))"
Spaceship.not_electrolytes  # :conditions => "(spaceships.flags not in (4,5,6,7))"

If you do not want the named scopes to be defined, set the :named_scopes option to false when calling has_flags:

has_flags 1 => :warpdrive, 2 => :shields, 3 => :electrolytes, :named_scopes => false

In a Rails 3+ application, FlagShihTzu will use scope internally to generate the scopes. The option on has_flags is still named :named_scopes however.

Examples for using the generated methods

enterprise = Spaceship.new
enterprise.warpdrive = true
enterprise.shields = true
enterprise.electrolytes = false
enterprise.save

if enterprise.shields?
  # ...
end

Spaceship.warpdrive.find(:all)
Spaceship.not_electrolytes.count

Support for manually building conditions

The following class methods may support you when manually building ActiveRecord conditions:

Spaceship.warpdrive_condition         # "(spaceships.flags in (1,3,5,7))"
Spaceship.not_warpdrive_condition     # "(spaceships.flags not in (1,3,5,7))"
Spaceship.shields_condition           # "(spaceships.flags in (2,3,6,7))"
Spaceship.not_shields_condition       # "(spaceships.flags not in (2,3,6,7))"
Spaceship.electrolytes_condition      # "(spaceships.flags in (4,5,6,7))"
Spaceship.not_electrolytes_condition  # "(spaceships.flags not in (4,5,6,7))"

These methods also accept a :table_alias option that can be used when generating SQL that references the same table more than once:

Spaceship.shields_condition(:table_alias => 'evil_spaceships') # "(evil_spaceships.flags in (2,3,6,7))"

Choosing a query mode

While the default way of building the SQL conditions uses an IN() list (as shown above), this approach will not work well for a high number of flags, as the value list for IN() grows.

For MySQL, depending on your MySQL settings, this can even hit the max_allowed_packet limit with the generated query, or the similar query length maximum for PostgreSQL.

In this case, consider changing the flag query mode to :bit_operator instead of :in_list, like so:

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

This will modify the generated condition and named_scope methods to use bit operators in the SQL instead of an IN() list:

Spaceship.warpdrive_condition     # "(spaceships.flags & 1 = 1)",
Spaceship.not_warpdrive_condition # "(spaceships.flags & 1 = 0)",
Spaceship.shields_condition       # "(spaceships.flags & 2 = 2)",
Spaceship.not_shields_condition   # "(spaceships.flags & 2 = 0)",

Spaceship.warpdrive     # :conditions => "(spaceships.flags & 1 = 1)"
Spaceship.not_warpdrive # :conditions => "(spaceships.flags & 1 = 0)"
Spaceship.shields       # :conditions => "(spaceships.flags & 2 = 2)"
Spaceship.not_shields   # :conditions => "(spaceships.flags & 2 = 0)"

The drawback is that due to the bitwise operation being done on the SQL side, this query can not use an index on the flags column.

Updating flag column by raw sql

If you need to do mass updates without initializing object for each row, you can use #set_flag_sql method on your class. Example:

Spaceship.set_flag_sql(:warpdrive, true) # "flags = flags | 1"
Spaceship.set_flag_sql(:shields, false)  # "flags = flags & ~2"

And then use it in:

Spaceship.update_all Spaceship.set_flag_sql(:shields, false)

Beware that using multiple flag manipulation sql statements in the same query probably will not have the desired effect (at least on sqlite3, not tested on other databases), so you should not do this:

Spaceship.update_all "#{Spaceship.set_flag_sql(:shields, false)},#{
  Spaceship.set_flag_sql(:warpdrive, true)}"

General rule of thumb: issue only one flag update per update statement.

Skipping flag column check

By default when you call has_flags in your code it will automatically check your database to see if you have correct column defined.

Sometimes this may not be a wanted behaviour (e.g. when loading model without database connection established) so you can set :check_for_column option to false to avoid it.

has_flags 1 => :warpdrive,
          2 => :shields,
          :check_for_column => false

Running the gem tests

WARNING: You may want to read bin/test.bash first. Running the test script will switch rubies, create gemsets, install gems, and get a lil' crazy with the hips.

Just:

$ rake test:all

This will internally use rvm and bundler to load specific Rubies and ActiveRecord versions before executing the tests (see gemfiles/), e.g.:

$ NOCOVER=true BUNDLE_GEMFILE='gemfiles/Gemfile.activerecord-4.1.x' bundle exec rake test

All tests will use an in-memory sqlite database by default. If you want to use a different database, see test/database.yml, install the required adapter gem and use the DB environment variable to specify which config from test/database.yml to use, e.g.:

$ NOCOVER=true DB=mysql bundle exec rake

You will also need to create, and configure access to, the test databases for any adapters you want to test, e.g. mysql:

mysql> CREATE USER 'foss'@'localhost';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT ALL PRIVILEGES ON *.* TO 'foss'@'localhost';
Query OK, 0 rows affected (0.00 sec)

mysql> CREATE DATABASE flag_shih_tzu_test;
Query OK, 1 row affected (0.00 sec)

Authors

Peter Boling, Patryk Peszko, Sebastian Roebke, David Anderson, Tim Payton and a helpful group of contributors. Thanks!

Find out more about Peter Boling's work RailsBling.com.

Find out more about XING Devblog.

How you can help!

Take a look at the reek list, which is the file called REEK, and stat fixing things. Once you complete a change, run the tests. See "Running the gem tests".

If the tests pass refresh the reek list:

bundle exec rake reek > REEK

Follow the instructions for "Contributing" below.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
6. Create new Pull Request

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency 'flag_shih_tzu', '~> 0.0'

2012 Change of Ownership and 0.3.X Release Notes

FlagShihTzu was originally a XING AG project. Peter Boling was a long time contributor and watcher of the project. In September 2012 XING transferred ownership of the project to Peter Boling. Peter Boling had been maintaining a fork with extended capabilities. These additional features become a part of the 0.3 line. The 0.2 line of the gem will remain true to XING's original. The 0.3 line aims to maintain complete parity and compatibility with XING's original as well. I will continue to monitor other forks for original ideas and improvements. Pull requests are welcome, but please rebase your work onto the current master to make integration easier.

More information on the changes for 0.3.X: pboling/flag_shih_tzu/wiki/Changes-for-0.3.x

Alternatives

I discovered in October 2015 that Michael Grosser had created a competing tool, bitfields, way back in 2010, exactly a year after this tool was created. It was a very surreal moment, as I had thought this was the only game in town and it was when I began using and hacking on it. Once I got over that moment I became excited, because competition makes things better, right? So, now I am looking forward to a shootout some lazy Saturday. Until then there's this: http://www.railsbling.com/posts/why-use-flag_shih_tzu/

There is little that bitfields does better. The code is less efficient, albeit more readable, not as well tested, has almost zero inline documentation, and simply can't do many of the things I've built into flag_shih_tzu. 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.

Will there ever be a merb/rails-like love fest between the projects? It would be interesting. I like his name better. I like my features better. I like some of his code better, and some of my code better. I've been wanting to do a full re-write of flag_shih_tzu ever since I inherited the project from XING, but I haven't had time. So I don't know.

License

MIT License

Copyright (c) 2011 XING AG

Copyright (c) 2012 - 2018 Peter Boling of RailsBling.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

flag_shih_tzu's Issues

Since 0.3.0 flags no longer work in a class using an alternative database connection

We use flag_shih_tzu in a number of classes. One of those is a class that uses a tabled shared between two applications. We use "establish_connection" to connect that class with a table in a secondary database.

Since 0.3.0 #check_flag_column method uses ActiveRecord::Base.connection to look for the table - i.e. the "local" database. Previously is just used #connection (i.e. MyClass.connection) which correctly found the "remote" database.

As a result flag_shih_tzu cannot find the expected table and fails to defined the flag methods.

Two Questions

given the following scenario.

has_flags 1 => :admin,
2 => :super_admin,
3 => :regional_manager ,
:column => :roles

has_flags 1=> :active, 2=>:inactive, :column => :status

How do I get a list of all set flags as an array of symbols? something like this User.first.role_list

Also how to I select inactive regional managers?

Update travis-ci build

Hi Peter,

now that flag_shih_tzu lives under your GitHub account, you should enable the build for it on
https://travis-ci.org.

Our existing .travis.yml does not need to be changed.

But you would need to update the build status image url in the README.rdoc from

{<img src="https://secure.travis-ci.org/xing/flag_shih_tzu.png" />}[http://travis-ci.org/xing/flag_shih_tzu]

to

{<img src="https://secure.travis-ci.org/pboling/flag_shih_tzu.png" />}[http://travis-ci.org/pboling/flag_shih_tzu]

can't run migrations when flags column is missing

When has_flags is used in a model and the corresponding column does not exist yet the plugin raises an exception.

This prevents migrations from running and therefore the required database column can't be created unless the has_flags call is removed or disabled.

this commt solves this issue. Please consider merging it.

Field values got corrupted after a while somehow

Hello, currently have this kind of problem, i have similar setup:

has_flags 1 => :warpdrive,
          2 => :shields,
          3 => :electrolytes,
          :column => 'features'

has_flags 1 => :spock,
          2 => :scott,
          :column => 'crew'

Here crew column can have 3 values: 0, 1, 2, 3 is it correct ?
But at some moment i notice that field not working as expected anymore, and when i check field value in database it has value of 6. So i then diable all flags and expect it to be 0

enterprise = Spaceship.new
enterprise.spock = false
enterprise.scott = false
enterprise.save!

And crew column now contains 4, so this column now 4,5,6,7, which is happened at some moment for unknown reason.

Querying DB for same flags state as an instance

I'm currently doing something like this to check the DB for an instance with the same flag state:

flags_state = shipping_item.unknown_origin? ? :unknown_origin : :not_unknown_origin
shipment.shipping_items.chained_flags_with('flags', flags_state)

It's quite ugly and doesn't scale well if I need to do it for more than one flag. Is there currently a better way to get a complete array of flag states (either flag or not_flag) for each flag so we can push it to chained_flags_with?

Upgrading to 0.3.15 -> 0.3.22

After upgrading, it seems like there may have been a major change in the flag retrieval because models that were returning "true" for this particular flag were now all uniformly returning "false" for that flag.

Here is the flag setup on the model:

has_flags 1 => :cje,
    2 => :apq,
    3 => :pje,
    4 => :ums,
    5 => :esp,
    6 => :avl,
    7 => :mpop,
    8 => :cvb,
    9 => :cob,
    10 => :cje,
    11 => :sue,
    12 => :lpl,
    13 => :ppl,
    14 => :lsms,
    15 => :lfwp,
    16 => :lfwop,
    17 => :ftp,
    18 => :plu,
    19 => :mpl,
    20 => :mat,
    21 => :skq,
    22 => :tma,
    23 => :rnw,
    flag_query_mode: :bit_operator,
    check_for_column: false

The flag in question is the last one, :rnw - all the others seem to be in the correct state.

Rails 3.1 DEPRECATION WARNING

DEPRECATION WARNING: class_inheritable_attribute is deprecated, please use class_attribute method instead. Notice their behavior are slightly different, so refer to class_attribute documentation first.

Scope SQL extremely clumsy for large number of flags; suggest using bitwise operators

The way the generated scopes currently work is by generating an array of all possible values of flags where the desired flag is set, and then checking array membership in SQL. For example:

has_flags 1 => :foo,
          2 => :bar,
          3 => :baz

User.bar
#=> SELECT "users".* FROM "users" WHERE users.flags in (2, 3, 6, 7)

Here 2, 3, 6, 7 are all the possible values for flags in which bar is set.

This is fine for a small number of flags. However, my application currently uses 19 (!) flags on a single model. You don't want to see the query it generates... (It's long enough to overflow my terminal buffer.)

I wonder whether it wouldn't be faster to use bitwise operators in the generated SQL. Something like this:

User.bar
#=> SELECT "users".* FROM "users" WHERE users.flags & 2 = 2

Not only is this a hell of a lot more readable, it stays true to the spirit of the gem (after all, "Bitwise Operations are fast!"), and it uses a syntax which does not grow in length or complexity as the number of flags on the model increases.

Testing documentation missing

I am using RSpec to test my app and when I used the gem, the tests starts failing. It tells me that the methods generated by this gem are undefined.

To make it work, I added the following lines in my spec/rails_helper.rb file:

RSpec.configure do |config|
  config.include FlagShihTzu
end

I would be glad to open a PR for this if you're interested.

NoMethodError: undefined method `keys' for nil:NilClass

class User < ActiveRecord::Base

  include FlagShihTzu

  has_flags 1 => :admin,
            2 => :super_admin,
            3 => :regional_manager ,
            :column => :roles

end

u = User.first
u.flags
=> 0
u.all_flags(:roles)
NoMethodError: undefined method `keys' for nil:NilClass
from /Users/tim/.rvm/gems/ree-1.8.7-2012.02/gems/flag_shih_tzu-0.3.2/lib/flag_shih_tzu.rb:299:in `all_flags'

Get array/hash of flags

It would be neat to be able to access the defined flags.

has_flags 1 => :duty_tax, 2 => :check_price, 3 => :customs_description,
            4 => :selling_price, 5 => :container_allocation, 6 => :freight_charge,
            7 => :handling_charge, 8 => :submitted, #, 9 => :completed,
            :column => 'processing_flags'

To get all the flags, I need to do this

Shipment.flag_mapping['processing_flags'].keys

Which is dangerous because it relies on the fact that implementation do not change.

The best would be to have a method shih_tzu_flags('processing_flags') => [:duty_tax, ..., :submitted]. Even better a method to get a hash => [:duty_tax => true, ... :submitted => false]

What do you think?

I'll try to make a pull request but I'm a bit new to Rails...

does not do anything when colum does not exists

has_flags 1=>:xxx, :column=>'asdadsasd' -> no warning/error, but when i try to use xxx it raises, a bit to late ?

Rails 5 warning - #tables

Managed to get this gem up and running under a new rails 5 app I am working on without any troubles. Thanks for all the hard work on it!

I am however seeing a warning that is worth reporting:

DEPRECATION WARNING: #tables currently returns both tables and views. This behavior is deprecated and will be changed with Rails 5.1 to only return tables. Use #data_sources instead.

This occurs within the has_flags call (in my specific case with a custom column name if that helps).

Do let me know if I can offer any more detail.

Allow updates similar to Rails enums

I swapped out some enums I was using for some flags. Especially in tests where I had to set up specific models, I was changing code like this: model.update(enum_field: :enum_value) to model.update(flags: [:flag1, :flag2]) which causes a null value to get sent to the db.

Instead, I ended up doing something like model.update(flags: 3) with a magic number.

It looks like it might be possible to do something similar to enums (https://github.com/rails/rails/blob/a9dc45459abcd9437085f4dd0aa3c9d0e64e062f/activerecord/lib/active_record/enum.rb#L165). Is there any interest in that?

Or any other recommendations to avoid magic numbers when setting multiple flags at once (without having to have one line of code per flag)?

Errors should inherit from StandardError, not Exception

  # TODO: Inherit from StandardError
  class IncorrectFlagColumnException < Exception; end
  class NoSuchFlagQueryModeException < Exception; end
  class NoSuchFlagException < Exception; end
  class DuplicateFlagColumnException < Exception; end

Allow updating single flag

I think having instanсe method that will allow updating single flag in a table without callbacks and validation, similar to AR update_column.

Currently I use

  def update_flag(flag, value)
    self.class.update_all(self.class.set_flag_sql(flag.to_sym, FlagShihTzu::TRUE_VALUES.include?(value)), self.class.primary_key => id) == 1
  end

Probably I should call something to update the state of my model

https://github.com/rails/rails/blob/68307a1ae5fc9e454230629f5cbbbeaf79fd7cec/activerecord/lib/active_record/persistence.rb#L192

include?(custom_table_name) missing?

Hey, guys, i think in this row there is a mistake
https://github.com/pboling/flag_shih_tzu/blob/master/lib/flag_shih_tzu.rb#L340
connection.data_sources
It should be
connection.data_sources.include?(custom_table_name)
otherwise has_table will be always true

Removing flags

Removing existing flags leads to an issue with the class methods. Here is a minimal example ...

Initial state ..

class Spaceship < ActiveRecord::Base
  include FlagShihTzu

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

s = Spaceship.create!
s.warpdrive = true
s.shields = true
s.save
s.flags # => 3

Spaceship.warpdrive.count # => 1, all is well

Now we change the flags to just ..

class Spaceship < ActiveRecord::Base
  include FlagShihTzu

  has_flags 
            1 => :warpdrive
end

s = Spaceship.first
s.flags # => 3
s.warpdrive? # => true

# Here is the problem
Spaceship.warpdrive.count # => 0

Change flag column check to be opt-in

Let's say I have a flag in User model. When running rake db:migrate or rake db:setup for the first time.
You'll get this error and migration
Also rake db:seed after that would fail !!

Even running test using rspec cause sometimes the same result !

FlagShihTzu#has_flags: Table "users" doesn't exist.  Have all migrations been run?
FlagShihTzu says: Flag column roles appears to be missing!

Suggestion flag_query_mode: bit_operator by default

Thanks for the awesome gem!

Anyway, after using it in production for a few months I would like to suggest (with a PR afterwards) to change the default query mode from :in_list to :bit_operator. Even though performance-wise it seems like :in_list is best for MySQL (haven't measured it with Postgres), I would like to argue that :bit_operator is safer.

The reason is that the :in_list query only works if the number of flags is fixed.

# reference state
class User < ApplicationRecord
  has_flags 1 => :warpdrive,
            2 => :shields
end

User.warprive.to_sql
=> "SELECT users.* FROM users WHERE users.flags in (1,3)

However, consider the case where a new flag is added:

# new state
class User < ApplicationRecord
  has_flags 1 => :warpdrive,
            2 => :shields,
            3 => :premium
            :flag_query_mode => :bit_operator
end

And in the same deploy a migration sets the flag for some records:

# db/migrate/...
class AddNewFlagToUsersTable < ApplicationRecord
  def up
    execute <<~SQL
      UPDATE users
        SET flags = flags | 4
        WHERE created_at < '...'
    SQL
  end

  def down
    # noop
  end
end

During the deploy the following query done in the old version of the app becomes invalid:

User.warprive.to_sql
=> "SELECT users.* FROM users WHERE users.flags in (1,3)

However, if the default query mode would be :bit_operator instead of :in_list, this problem wouldn't happen:

User.warprive.to_sql
=> "SELECT users.* FROM users WHERE users.flags & 1 = 1

The :bit_operator works regardless of the number of flags, so there would be no issue during a deploy setting a new flag.

Anyway, I decided to open this issue today because in my company we have been bitten by this a couple of times, and now we try to remember to always add :flag_query_mode => :bit_operator when using has_flags. I wonder if other users have been bitten by that, too. I'm a fan of the principle of least surprise, and think that safety should come before performance. If someone needs more performance he/she can always add the option later.

Breaks db:create rake task

given a rails app which uses flag_shih_tzu.
given an uninitialized db.
when you run rake db:create
then flag_shih_tzu attempts to connect the db that has not yet been created.

flags_as_attributes method?

I'm not sure what a good name for this really is, or the best way for it to work, but I was just writing some tests, and expecting model.attributes to return all my flags as individual Boolean attribute values, which of course, it did not :)

My flag field is called setup_steps so I figured out I could rewrite the test to use selected_setup_steps, but I still think a method to retrieve the flag values in the format of regular attributes (the same way you can set them) would be useful (i.e. { flag1: true, flag2: true, flag3: false })

What I'm not sure about is whether it makes more sense for that to be a model-wide method, like model.attributes_with_flags which would return all the normal attributes, plus additional attributes for each defined flag (regardless of how many flag fields are defined), or to make one method per flag field, like model.setup_steps_as_attributes or something to that effect... that one would be marginally easier to implement at least. Any opinion?

column should also accept symbols

we just had strange errros until we figured out that the :column => :bits must be a string ('bits')

migrations fail when using flag conditions in an association

If we have models Pizza and Topping, where
Topping.has_flag :is_a_veg

and

Pizza.has_many :veggies, :class_name => 'Topping', :conditions => "#{Topping.is_a_veg_condition}"

If a migration prior to the migration which adds column flags to table toppings references a #pizza, that migration will fail with:

undefined method 'is_a_veg_condition' for #<Class:0x4364ecc>

The workaround I am using is to add to the Topping model:
unless Topping.respond_to?(:is_a_veg_condition)
def Topping.is_a_veg_condition
""
end
end

Not all that elegant i know =). I will fork and look for a better way to fix within flag_shih_tzu, Just wanted to drop a note about it.

Getting the flag column value for a set of flags (useful for testing)

Using FactoryGirl, I would like to be able to set flags in a constructor, this way:

s = FactoryGirl.create :spaceship, 
    flags: Spaceship.flags_value(:shields, :warpdrive)

This would create an Spaceship instance with shields and wrapdrive set to true.
Is it already possible and I'm not seeing the method?

Issue with precompile?

I'm running into an issue where if I try to compile production assets on my local machine this throws an error. I believe this is due to has_flags referencing the connect.

Have you run into this before? Is there a known work-around?

migrations fail in test environment

from flag_shih_tzu.rb:105
# BJM: added test env check. self.columns bombs when !has_ar && Rails.env = 'test'
#if !has_ar || (has_ar && has_table)
if (Rails.env != 'test' && !has_ar) || (has_ar && has_table)

Query bit names on record

Hi I was using the gem today and thought it would be nice if possible to add a functionality like:

Record.flag_names and return an array of strings containing flag names. It would be really useful to iterate over the flag names without having to hard code the names.

Not sure if the feature exists and I haven't seen it but thanks in advance :D

Suggestion: don't assume Rails logger is present; make logger configurable

I'm joining a non-Rails project that uses this gem. I just ran the tests and got a backtrace that included this:

...../gems/flag_shih_tzu-0.3.2/lib/flag_shih_tzu.rb:209:in `check_flag_column': 
private method `warn' called for nil:NilClass (NoMethodError)

That goes to a line like this (on master):
https://github.com/pboling/flag_shih_tzu/blob/master/lib/flag_shih_tzu.rb#L269

Turns out that you're trying to give me a helpful error, but I actually got a very confusing one. 😆

This line assumes that the Rails logger is present (right?).

An approach I've seen that gets around that is to have a configurable logger. Eg, when you want to log, call FlagShihTzu.logger.warn('whatever'). That would be a method like:

module FlagShihTzu
  def self.logger
    @logger ||= configuration.logger
  end
end

Then users could configure your log messages to point wherever they want in a configuration file. Eg, configuration.logger = Rails.logger in a Rails app, or configuration.logger = Logger.new(my_location), where my_location could be 'some_file.log' or STDOUT or '/dev/null'.

This is a trick @adamhunter showed me, which we used in Authority: https://github.com/nathanl/authority/blob/c4e55d89389904cda888cbc01a0864728cfde950/lib/authority.rb#L61

Just an idea.

Add support for dirty fields

Would be great if we could get methods like published_changed? where published is a flag (inline with http://api.rubyonrails.org/v2.3.8/classes/ActiveRecord/Dirty.html)

Why default column doesn't get the fancy new flags selection methods?

Because of this line, the nice new methods are not defined for the default column name:
https://github.com/pboling/flag_shih_tzu/blob/master/lib/flag_shih_tzu.rb#L98
resulting in all_flags, selected_flags, etc.. not to be defined.

Is there a good reason for it?