active_record_doctor 1.7.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d5091f9668515416b73453756daa5f78598f6d35f0f60073a947719e535110f
-  data.tar.gz: 428450c43db5adb8510debfb9e895efba1f21649355255fe3eb7a2ea16c82642
+  metadata.gz: e69330f83b83c3adcd1397554bc916ee163acf3797b8be5b8f96f1960e2d8a3e
+  data.tar.gz: 8f6e09d3af78bb9aaf01374437653b25070c2c328a0ffeaedc800378a10074f6
 SHA512:
-  metadata.gz: fffc1ffd284a2448ac5c74dae34a3bbe45eda4836b0e22a0af072ab6353f16b1386385254b1cdb2b87e4776372869d8cee67bf0a066f180b85bd45ef7ed3cc33
-  data.tar.gz: 0011f60f1e37542911a72cce23cc8c8430310f8263fe7ba73aba30230ec8ff3f6e7ee9df72f42d8db6ff54e732a86aa49f1e6489a5b44d51bf1bd6c68821ebcd
+  metadata.gz: 4b9d75665c0524cd5ad18c5aa21aaf59b3e7a75b63c88fb332cd3f600de4f2a9fa073b985f5155b81d54f177b25da5fba5dde494fa6eed28e16086a955082012
+  data.tar.gz: 94c14b73d06c92803b196fde5ca0572c9545b2ef8b89bc91e88755c5aed9c4e51087ab59a53a94f1fbcacf3f7a58a25cac38dfb4f81d7096ee4d03c7796632b4

data/README.md

@@ -1,41 +1,147 @@
 # Active Record Doctor
 
 Active Record Doctor helps to keep the database in a good shape. Currently, it
-can:
+can detect:
 
-* index unindexed foreign keys
-* detect extraneous indexes
-* detect unindexed `deleted_at` columns
-* detect missing foreign key constraints
-* detect models referencing undefined tables
-* detect uniqueness validations not backed by an unique index
-* detect missing non-`NULL` constraints
-* detect missing presence validations
-* detect incorrect presence validations on boolean columns
+* extraneous indexes - [`active_record_doctor:extraneous_indexes`](#removing-extraneous-indexes)
+* unindexed `deleted_at` columns - [`active_record_doctor:unindexed_deleted_at`](#detecting-unindexed-deleted_at-columns)
+* missing foreign key constraints - [`active_record_doctor:missing_foreign_keys`](#detecting-missing-foreign-key-constraints)
+* models referencing undefined tables - [`active_record_doctor:undefined_table_references`](#detecting-models-referencing-undefined-tables)
+* uniqueness validations not backed by an unique index - [`active_record_doctor:missing_unique_indexes`](#detecting-uniqueness-validations-not-backed-by-an-index)
+* missing non-`NULL` constraints - [`active_record_doctor:missing_non_null_constraint`](#detecting-missing-non-null-constraints)
+* missing presence validations - [`active_record_doctor:missing_presence_validation`](#detecting-missing-presence-validations)
+* incorrect presence validations on boolean columns - [`active_record_doctor:incorrect_boolean_presence_validation`](#detecting-incorrect-presence-validations-on-boolean-columns)
+* incorrect values of `dependent` on associations - [`active_record_doctor:incorrect_dependent_option`](#detecting-incorrect-dependent-option-on-associations)
+* primary keys having short integer types - [`active_record_doctor:short_primary_key_type`](#detecting-primary-keys-having-short-integer-types)
+* mismatched foreign key types - [`active_record_doctor:mismatched_foreign_key_type`](#detecting-mismatched-foreign-key-types)
 
-More features coming soon!
+It can also:
 
-Want to suggest a feature? Just shoot me [an email](mailto:contact@gregnavis.com).
+* index unindexed foreign keys - [`active_record_doctor:unindexed_foreign_keys`](#indexing-unindexed-foreign-keys)
 
-[<img src="https://travis-ci.org/gregnavis/active_record_doctor.svg?branch=master" alt="Build Status" />](https://travis-ci.org/gregnavis/active_record_doctor)
+[![Build Status](https://github.com/gregnavis/active_record_doctor/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/gregnavis/active_record_doctor/actions/workflows/test.yml)
 
 ## Installation
 
-The preferred installation method is adding `active_record_doctor` to your
-`Gemfile`:
+In order to use the latest production release, please add the following to
+your `Gemfile`:
 
 ```ruby
 gem 'active_record_doctor', group: :development
 ```
 
-Then run:
+and run `bundle install`. If you'd like to use the most recent development
+version then use this instead:
 
-```bash
-bundle install
+```ruby
+gem 'active_record_doctor', github: 'gregnavis/active_record_doctor'
 ```
 
+That's it when it comes to Rails projects. If your project doesn't use Rails
+then you can use `active_record_doctor` via `Rakefile`.
+
+### Additional Installation Steps for non-Rails Projects
+
+If your project uses Rake then you can add the following to `Rakefile` in order
+to use `active_record_doctor`:
+
+```ruby
+require "active_record_doctor"
+
+ActiveRecordDoctor::Rake::Task.new do |task|
+  # Add project-specific Rake dependencies that should be run before running
+  # active_record_doctor.
+  task.deps = []
+
+  # A path to your active_record_doctor configuration file.
+  task.config_path = ::Rails.root.join(".active_record_doctor")
+
+  # A Proc called right before running detectors that should ensure your Active
+  # Record models are preloaded and a database connection is ready.
+  task.setup = -> { ::Rails.application.eager_load! }
+end
+```
+
+**IMPORTANT**. `active_record_doctor` expects that after running `deps` and
+calling `setup` your Active Record models are loaded and a database connection
+is established.
+
 ## Usage
 
+`active_record_doctor` can be used via `rake` or `rails`.
+
+You can run all available detectors via:
+
+```
+bundle exec rake active_record_doctor
+```
+
+You can run a specific detector via:
+
+```
+bundle exec rake active_record_doctor:extraneous_indexes
+```
+
+### Continuous Integration
+
+If you want to use `active_record_doctor` in a Continuous Integration setting
+then ensure the configuration file is committed and run the tool as one of your
+build steps -- it returns a non-zero exit status if any errors were reported.
+
+### Obtaining Help
+
+If you'd like to obtain help on a specific detector then use the `help` sub-task:
+
+```
+bundle exec rake active_record_doctor:extraneous_indexes:help
+```
+
+This will show the detector help text in the terminal, along with supported
+configuration options, their meaning, and whether they're global or local.
+
+### Configuration
+
+`active_record_doctor` can be configured to better suite your project's needs.
+For example, if it complains about a model that you want ignored then you can
+add that model to the configuration file.
+
+If you want to use the default configuration then you don't have to do anything.
+Just run `active_record_doctor` in your project directory.
+
+If you want to customize the tool you should create a file named
+`.active_record_doctor` in your project root directory with content like:
+
+```ruby
+ActiveRecordDoctor.configure do
+  # Global settings affect all detectors.
+  global :ignore_tables, [
+    # Ignore internal Rails-related tables.
+    "ar_internal_metadata",
+    "schema_migrations",
+    "active_storage_blobs",
+    "active_storage_attachments",
+    "action_text_rich_texts",
+
+    # Add project-specific tables here.
+    "legacy_users"
+  ]
+
+  # Detector-specific settings affect only one specific detector.
+  detector :extraneous_indexes,
+    ignore_tables: ["users"],
+    ignore_indexes: ["accounts_on_email_organization_id"]
+end
+```
+
+The configuration file above will make `active_record_doctor` ignore internal
+Rails tables (which are ignored by default) and also the `legacy_users` table.
+It'll also make the `extraneous_indexes` detector skip the `users` table
+entirely and will not report the index named `accounts_on_email_organization_id`
+as extraneous.
+
+Configuration options for each detector are listed below. They can also be
+obtained via the help mechanism described in the previous section.
+
 ### Indexing Unindexed Foreign Keys
 
 Foreign keys should be indexed unless it's proven ineffective. However, Rails
@@ -65,6 +171,11 @@ three-step process:
   bundle exec rake db:migrate
   ```
 
+Supported configuration options:
+
+- `ignore_tables` - tables whose foreign keys should not be checked
+- `ignore_columns` - columns, written as table.column, that should not be checked.
+
 ### Removing Extraneous Indexes
 
 Let me illustrate with an example. Consider a `users` table with columns
@@ -106,6 +217,11 @@ example, if there's a unique index on `users.login` and a non-unique index on
 `users.login, users.domain` then the tool will _not_ suggest dropping
 `users.login` as it could violate the uniqueness assumption.
 
+Supported configuration options:
+
+- `ignore_tables` - tables whose indexes should never be reported as extraneous.
+- `ignore_columns` - indexes that should never be reported as extraneous.
+
 ### Detecting Unindexed `deleted_at` Columns
 
 If you soft-delete some models (e.g. with `paranoia`) then you need to modify
@@ -124,6 +240,13 @@ This will print a list of indexes that don't have the `deleted_at IS NULL`
 clause. Currently, `active_record_doctor` cannot automatically generate
 appropriate migrations. You need to do that manually.
 
+Supported configuration options:
+
+- `ignore_tables` - tables whose indexes should not be checked.
+- `ignore_columns` - specific columns, written as table.column, that should not be reported as unindexed.
+- `ignore_indexes` - specific indexes that should not be reported as excluding a timestamp column.
+- `column_names` - deletion timestamp column names.
+
 ### Detecting Missing Foreign Key Constraints
 
 If `users.profile_id` references a row in `profiles` then this can be expressed
@@ -141,20 +264,8 @@ keys with the following command:
 bundle exec rake active_record_doctor:missing_foreign_keys
 ```
 
-The output will look like:
-
-```
-users profile_id
-comments user_id article_id
-```
-
-Tables are listed one per line. Each line starts with a table name followed by
-column names that should have a foreign key constraint. In the example above,
-`users.profile_id`, `comments.user_id`, and `comments.article_id` lack a foreign
-key constraint.
-
-In order to add a foreign key constraint to `users.profile_id` use the following
-migration:
+In order to add a foreign key constraint to `users.profile_id` use a migration
+like:
 
 ```ruby
 class AddForeignKeyConstraintToUsersProfileId < ActiveRecord::Migration
@@ -164,6 +275,11 @@ class AddForeignKeyConstraintToUsersProfileId < ActiveRecord::Migration
 end
 ```
 
+Supported configuration options:
+
+- `ignore_tables` - tables whose columns should not be checked.
+- `ignore_columns` - columns, written as table.column, that should not be checked.
+
 ### Detecting Models Referencing Undefined Tables
 
 Active Record guesses the table name based on the class name. There are a few
@@ -186,13 +302,16 @@ If there a model references an undefined table then you'll see a message like
 this:
 
 ```
-The following models reference undefined tables:
-  Contract (the table contract_records is undefined)
+Contract references a non-existent table or view named contract_records
 ```
 
 On top of that `rake` will exit with status code of 1. This allows you to use
 this check as part of your Continuous Integration pipeline.
 
+Supported configuration options:
+
+- `ignore_models` - models whose underlying tables should not be checked for existence.
+
 ### Detecting Uniqueness Validations not Backed by an Index
 
 A model-level uniqueness validations should be backed by a database index in
@@ -208,12 +327,16 @@ bundle exec rake active_record_doctor:missing_unique_indexes
 If there are such indexes then the command will print:
 
 ```
-The following indexes should be created to back model-level uniqueness validations:
-  users: email
+add a unique index on users(email) - validating uniqueness in the model without an index can lead to duplicates
 ```
 
 This means that you should create a unique index on `users.email`.
 
+Supported configuration options:
+
+- `ignore_models` - models whose uniqueness validators should not be checked.
+- `ignore_columns` - specific validators, written as Model(column1, column2, ...), that should not be checked.
+
 ### Detecting Missing Non-`NULL` Constraints
 
 If there's an unconditional presence validation on a column then it should be
@@ -229,14 +352,19 @@ bundle exec rake active_record_doctor:missing_non_null_constraint
 The output of the command is similar to:
 
 ```
-The following columns should be marked as `null: false`:
-  users: name
-
+add `NOT NULL` to users.name - models validates its presence but it's not non-NULL in the database
 ```
 
 You can mark the columns mentioned in the output as `null: false` by creating a
 migration and calling `change_column_null`.
 
+This validator skips models whose corresponding database tables don't exist.
+
+Supported configuration options:
+
+- `ignore_tables` - tables whose columns should not be checked.
+- `ignore_columns` - columns, written as table.column, that should not be checked.
+
 ### Detecting Missing Presence Validations
 
 If a column is marked as `null: false` then it's likely it should have the
@@ -251,12 +379,19 @@ bundle exec rake active_record_doctor:missing_presence_validation
 The output of the command looks like this:
 
 ```
-The following models and columns should have presence validations:
-  User: email, name
+add a `presence` validator to User.email - it's NOT NULL but lacks a validator
+add a `presence` validator to User.name - it's NOT NULL but lacks a validator
 ```
 
 This means `User` should have a presence validator on `email` and `name`.
 
+This validator skips models whose corresponding database tables don't exist.
+
+Supported configuration options:
+
+- `ignore_models` - models whose underlying tables' columns should not be checked.
+- `ignore_columns` - specific attributes, written as Model.attribute, that should not be checked.
+
 ### Detecting Incorrect Presence Validations on Boolean Columns
 
 A boolean column's presence should be validated using inclusion or exclusion
@@ -271,13 +406,122 @@ bundle exec rake active_record_doctor:incorrect_boolean_presence_validation
 The output of the command looks like this:
 
 ```
-The presence of the following boolean columns is validated incorrectly:
-  User: active
+replace the `presence` validator on User.active with `inclusion` - `presence` can't be used on booleans
 ```
 
 This means `active` is validated with `presence: true` instead of
 `inclusion: { in: [true, false] }` or `exclusion: { in: [nil] }`.
 
+This validator skips models whose corresponding database tables don't exist.
+
+Supported configuration options:
+
+- `ignore_models` - models whose validators should not be checked.
+- `ignore_columns` - attributes, written as Model.attribute, whose validators should not be checked.
+
+### Detecting Incorrect `dependent` Option on Associations
+
+Cascading model deletions can be sped up with `dependent: :delete_all` (to
+delete all dependent models with one SQL query) but only if the deleted models
+have no callbacks as they're skipped.
+
+This can lead to two types of errors:
+
+- Using `delete_all` when dependent models define callbacks - they will NOT be
+  invoked.
+- Using `destroy` when dependent models define no callbacks - dependent models
+  will be loaded one-by-one with no reason
+
+In order to detect associations affected by the two aforementioned problems run
+the following command:
+
+```
+bundle exec rake active_record_doctor:incorrect_dependent_option
+```
+
+The output of the command looks like this:
+
+```
+use `dependent: :delete_all` or similar on Company.users - associated models have no validations and can be deleted in bulk
+use `dependent: :destroy` or similar on Post.comments - the associated model has callbacks that are currently skipped
+```
+
+Supported configuration options:
+
+- `ignore_models` - models whose associations should not be checked.
+- `ignore_columns` - associations, written as Model.association, that should not be checked.
+
+### Detecting Primary Keys Having Short Integer Types
+
+Active Record 5.1 changed the default primary and foreign key type from INTEGER
+to BIGINT. The reason is to reduce the risk of running out of IDs on inserts.
+
+In order to detect primary keys using shorter integer types, for example created
+before migrating to 5.1, you can run the following command:
+
+```
+bundle exec rake active_record_doctor:short_primary_key_type
+```
+
+The output of the command looks like this:
+
+```
+change the type of companies.id to bigint
+```
+
+The above means `comanies.id` should be migrated to a wider integer type. An
+example migration to accomplish this looks likes this:
+
+```ruby
+class ChangeCompaniesPrimaryKeyType < ActiveRecord::Migration[5.1]
+  def change
+    change_column :companies, :id, :bigint
+  end
+end
+```
+
+**IMPORTANT**. Running the above migration on a large table can cause downtime
+as all rows need to be rewritten.
+
+Supported configuration options:
+
+- `ignore_tables` - tables whose primary keys should not be checked.
+
+### Detecting Mismatched Foreign Key Types
+
+Foreign keys should be of the same type as the referenced primary key.
+Otherwise, there's a risk of bugs caused by IDs representable by one type but
+not the other.
+
+Running the command below will list all foreign keys whose type is different
+from the referenced primary key:
+
+```
+bundle exec rake active_record_doctor:mismatched_foreign_key_type
+```
+
+The output of the command looks like this:
+
+```
+companies.user_id references a column of different type - foreign keys should be of the same type as the referenced column
+```
+
+Supported configuration options:
+
+- `ignore_tables` - tables whose foreign keys should not be checked.
+- `ignore_columns` - foreign keys, written as table.column, that should not be checked.
+
+## Ruby and Rails Compatibility Policy
+
+The goal of the policy is to ensure proper functioning in reasonable
+combinations of Ruby and Rails versions. Specifically:
+
+1. If a Rails version is officially supported by the Rails Core Team then it's
+   supported by `active_record_doctor`.
+2. If a Ruby version is compatible with a supported Rails version then it's
+   also supported by `active_record_doctor`.
+3. Only most recent teeny Ruby versions and patch Rails versions are supported.
+
 ## Author
 
 This gem is developed and maintained by [Greg Navis](http://www.gregnavis.com).

data/lib/active_record_doctor/config/default.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+ActiveRecordDoctor.configure do
+  global :ignore_tables, [
+    "ar_internal_metadata",
+    "schema_migrations",
+    "active_storage_blobs",
+    "active_storage_attachments",
+    "action_text_rich_texts"
+  ]
+
+  detector :extraneous_indexes,
+    ignore_tables: [],
+    ignore_indexes: []
+
+  detector :incorrect_boolean_presence_validation,
+    ignore_models: [],
+    ignore_attributes: []
+
+  detector :incorrect_dependent_option,
+    ignore_models: [],
+    ignore_associations: []
+
+  detector :mismatched_foreign_key_type,
+    ignore_tables: [],
+    ignore_columns: []
+
+  detector :missing_foreign_keys,
+    ignore_tables: [],
+    ignore_columns: []
+
+  detector :missing_non_null_constraint,
+    ignore_tables: [],
+    ignore_columns: []
+
+  detector :missing_presence_validation,
+    ignore_models: [],
+    ignore_attributes: []
+
+  detector :missing_unique_indexes,
+    ignore_models: [],
+    ignore_columns: []
+
+  detector :short_primary_key_type,
+    ignore_tables: []
+
+  detector :undefined_table_references,
+    ignore_models: []
+
+  detector :unindexed_deleted_at,
+    ignore_tables: [],
+    ignore_columns: [],
+    ignore_indexes: [],
+    column_names: ["deleted_at", "discarded_at"]
+
+  detector :unindexed_foreign_keys,
+    ignore_tables: [],
+    ignore_columns: []
+end

data/lib/active_record_doctor/config/loader.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ActiveRecordDoctor # :nodoc:
+  class << self
+    # The config file that's currently being processed by .load_config.
+    attr_reader :current_config
+
+    # This method is part of the public API that is intended for use by
+    # active_record_doctor users. The remaining methods are considered to be
+    # public-not-published.
+    def configure(&block)
+      # If current_config is set it means that .configure was already called
+      # so we must raise an error.
+      raise ActiveRecordDoctor::Error::ConfigureCalledTwice if current_config
+
+      # Determine the recognized global and detector settings based on detector
+      # metadata. recognizedd_detectors maps detector names to setting names.
+      # recognized_globals contains global setting names.
+      recognized_detectors = {}
+      recognized_globals = []
+
+      ActiveRecordDoctor.detectors.each do |name, detector|
+        locals, globals = detector.locals_and_globals
+
+        recognized_detectors[name] = locals
+        recognized_globals.concat(globals)
+      end
+
+      # The same global can be used by multiple detectors so we must remove
+      # duplicates to ensure they aren't reported mutliple times via the user
+      # interface (e.g. in error messages).
+      recognized_globals.uniq!
+
+      # Prepare an empty configuration and call the loader. After .new returns
+      # @current_config will contain the configuration provided by the block.
+      @current_config = Config.new({}, {})
+      Loader.new(current_config, recognized_globals, recognized_detectors, &block)
+
+      # This method is part of the public API expected to be called by users.
+      # In order to avoid leaking internal objects, we return an explicit nil.
+      nil
+    end
+
+    def load_config(path)
+      begin
+        load(path)
+      rescue ActiveRecordDoctor::Error
+        raise
+      rescue LoadError
+        raise ActiveRecordDoctor::Error::ConfigurationFileMissing
+      rescue StandardError => e
+        raise ActiveRecordDoctor::Error::ConfigurationError[e]
+      end
+      raise ActiveRecordDoctor::Error::ConfigureNotCalled if current_config.nil?
+
+      # Store the configuration and reset @current_config. We cannot reset
+      # @current_config in .configure because that would prevent us from
+      # detecting multiple calls to that method.
+      config = @current_config
+      @current_config = nil
+
+      config
+    rescue ActiveRecordDoctor::Error => e
+      e.config_path = path
+      raise e
+    end
+
+    DEFAULT_CONFIG_PATH = File.join(__dir__, "default.rb").freeze
+    private_constant :DEFAULT_CONFIG_PATH
+
+    def load_config_with_defaults(path)
+      default_config = load_config(DEFAULT_CONFIG_PATH)
+      return default_config if path.nil?
+
+      config = load_config(path)
+      default_config.merge(config)
+    end
+  end
+
+  # A class used for loading user-provided configuration files.
+  class Loader
+    def initialize(config, recognized_globals, recognized_detectors, &block)
+      @config = config
+      @recognized_globals = recognized_globals
+      @recognized_detectors = recognized_detectors
+      instance_eval(&block)
+    end
+
+    def global(name, value)
+      name = name.to_sym
+
+      unless recognized_globals.include?(name)
+        raise ActiveRecordDoctor::Error::UnrecognizedGlobalSetting[
+          name,
+          recognized_globals
+        ]
+      end
+
+      if config.globals.include?(name)
+        raise ActiveRecordDoctor::Error::DuplicateGlobalSetting[name]
+      end
+
+      config.globals[name] = value
+    end
+
+    def detector(name, settings)
+      name = name.to_sym
+
+      recognized_settings = recognized_detectors[name]
+      if recognized_settings.nil?
+        raise ActiveRecordDoctor::Error::UnrecognizedDetectorName[
+          name,
+          recognized_detectors.keys
+        ]
+      end
+
+      if config.detectors.include?(name)
+        raise ActiveRecordDoctor::Error::DetectorConfiguredTwice[name]
+      end
+
+      unrecognized_settings = settings.keys - recognized_settings
+      unless unrecognized_settings.empty?
+        raise ActiveRecordDoctor::Error::UnrecognizedDetectorSettings[
+          name,
+          unrecognized_settings,
+          recognized_settings
+        ]
+      end
+
+      config.detectors[name] = settings
+    end
+
+    private
+
+    attr_reader :config, :recognized_globals, :recognized_detectors
+  end
+end

data/lib/active_record_doctor/config.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActiveRecordDoctor # :nodoc:
+  Config = Struct.new(:globals, :detectors) do
+    def merge(config)
+      globals = self.globals.merge(config.globals)
+      detectors = self.detectors.merge(config.detectors) do |_name, self_settings, config_settings|
+        self_settings.merge(config_settings)
+      end
+
+      Config.new(globals, detectors)
+    end
+  end
+end