ruby-pg-extras 5.5.1 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03a33801e7bd4bd56cd4b55d3295a97ce3fe96e5fe489641b5c2e5118618c023
-  data.tar.gz: b778857dd526e7b80b286b95be11d4ef6b738c68aab74e9394b57aee4148f1a6
+  metadata.gz: 1348ba4881f0d65e98e76e5224fc830d5c124f9005a66d5b4157da7eb8f7cfd3
+  data.tar.gz: 83803cc3cbb81a80791b74aa8c768d6033f572d71b8074083c96172bc41f364e
 SHA512:
-  metadata.gz: 2642d76755c1c45ddd25cae9e53acbefe4f5083771dd751c9e58f367e580fda33c586d5cb026d220c45f635816db2b81a4f1f07e00a820403cac81279445ac17
-  data.tar.gz: df227a8b82651322a83b3fad613b44d746b89bb68e7b604ac3474b4f430c5fb1633c7b977b2c1b54538d8679d309a0442037ea016c0278da2163df808735d7a2
+  metadata.gz: 27e9cc6ffc9dd82e53bc1511a8338123b2d2c60fb820358955d47412026d9b77660975d32005e829085bd780adf448774f9801507edf2a9844594b0318645779
+  data.tar.gz: d27cd85774ca39e9837c136e006359beb3e88ddf10ca5b5c6b88ea59b3734731a0a0dfb1f97a9e905aff034e67a3cc5e8da250a0cdc6bb18fb5a6dfb2b9b7a95

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.3', '3.2', '3.1', '3.0', '2.7', '2.6']
+        ruby-version: ['3.3', '3.2', '3.1', '3.0', '2.7']
     steps:
       - uses: actions/checkout@v4
       - name: Run PostgreSQL 12

data/README.md

@@ -116,6 +116,30 @@ Keep reading to learn about methods that `diagnose` uses under the hood.
 
 ## Available methods
 
+### `missing_fk_indexes`
+
+This method lists columns likely to be foreign keys (i.e. name ending in `_id`) but don't have a corresponding index. It's a generally recommended to always index foreign key columns because they are used for searching relation objects. 
+
+You can add indexes on the columns returned by this query and later check if they are receiving scans using the [unused_indexes method](#unused_indexes). Please also remember that each index decreases write performance and autovacuuming overhead, so be careful when adding multiple indexes to often updated tables.
+
+```ruby
+RubyPgExtras.missing_fk_indexes(args: { table_name: "users" })
+
+```
+
+`table_name` argument is optional, if omitted, the method will display missing fk indexes for all the tables.
+
+## `missing_fk_constraints`
+
+Similarly to the previous method, this one shows columns likely to be foreign keys (i.e. name ending in `_id`) that don't have a corresponding foreign key constraint. Foreign key constraints improve data integrity in the database by preventing relations with nonexisting objects. You can read more about the benefits of using foreign keys [in this blog post](https://pawelurbanek.com/rails-postgresql-data-integrity).
+
+```ruby
+RubyPgExtras.missing_fk_constraints(args: { table_name: "users" })
+
+```
+
+`table_name` argument is optional, if omitted, method will display missing foreign keys for all the tables.
+
 ### `table_info`
 
 This method displays metadata metrics for all or a selected table. You can use it to check the table's size, its cache hit metrics, and whether it is correctly indexed. Many sequential scans or no index scans are potential indicators of misconfigured indexes. This method aggregates data provided by other methods in an easy to analyze summary format.
@@ -129,6 +153,24 @@ RubyPgExtras.table_info(args: { table_name: "users" })
 
 ```
 
+### `table_schema`
+
+This method displays structure of a selected table, listing its column names, together with types, null constraints, and default values.
+
+```ruby
+RubyPgExtras.table_schema(args: { table_name: "users" })
+
+```
+
+### `table_foreign_keys`
+
+This method displays foreign key constraints for a selected table. It lists foreign key name, source and target columns, and related table name.
+
+```ruby
+RubyPgExtras.table_foreign_keys(args: { table_name: "users" })
+
+```
+
 ### `index_info`
 
 This method returns summary info about database indexes. You can check index size, how often it is used and what percentage of its total size are NULL values. Like the previous method, it aggregates data from other helper methods in an easy-to-digest format.

data/lib/ruby-pg-extras.rb

@@ -6,6 +6,8 @@ require "pg"
 require "ruby_pg_extras/size_parser"
 require "ruby_pg_extras/diagnose_data"
 require "ruby_pg_extras/diagnose_print"
+require "ruby_pg_extras/missing_fk_indexes"
+require "ruby_pg_extras/missing_fk_constraints"
 require "ruby_pg_extras/index_info"
 require "ruby_pg_extras/index_info_print"
 require "ruby_pg_extras/table_info"
@@ -26,10 +28,16 @@ module RubyPgExtras
     unused_indexes duplicate_indexes vacuum_stats kill_all kill_pid
     pg_stat_statements_reset buffercache_stats
     buffercache_usage ssl_used connections
+    table_schema table_foreign_keys
   )
 
   DEFAULT_SCHEMA = ENV["PG_EXTRAS_SCHEMA"] || "public"
 
+  REQUIRED_ARGS = {
+    table_schema: [:table_name],
+    table_foreign_keys: [:table_name],
+  }
+
   DEFAULT_ARGS = Hash.new({}).merge({
     calls: { limit: 10 },
     calls_legacy: { limit: 10 },
@@ -79,7 +87,13 @@ module RubyPgExtras
       end
     end
 
-    sql = if (custom_args = DEFAULT_ARGS[query_name].merge(args)) != {}
+    REQUIRED_ARGS.fetch(query_name) { [] }.each do |arg_name|
+      if args[arg_name].nil?
+        raise ArgumentError, "'#{arg_name}' is required"
+      end
+    end
+
+    sql = if (custom_args = DEFAULT_ARGS.fetch(query_name, {}).merge(args)) != {}
         sql_for(query_name: query_name) % custom_args
       else
         sql_for(query_name: query_name)
@@ -135,6 +149,14 @@ module RubyPgExtras
     end
   end
 
+  def self.missing_fk_indexes(args: {}, in_format: :display_table)
+    RubyPgExtras::MissingFkIndexes.call(args[:table_name])
+  end
+
+  def self.missing_fk_constraints(args: {}, in_format: :display_table)
+    RubyPgExtras::MissingFkContraints.call(args[:table_name])
+  end
+
   def self.display_result(result, title:, in_format:)
     case in_format
     when :array

data/lib/ruby_pg_extras/missing_fk_constraints.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyPgExtras
+  class MissingFkContraints
+    def self.call(table_name)
+      new.call(table_name)
+    end
+
+    def call(table_name)
+      tables = if table_name
+          [table_name]
+        else
+          RubyPgExtras.table_size(in_format: :hash).map { |row| row.fetch("name") }
+        end
+
+      tables.reduce([]) do |agg, table|
+        foreign_keys_info = RubyPgExtras.table_foreign_keys(args: { table_name: table }, in_format: :hash)
+        schema = RubyPgExtras.table_schema(args: { table_name: table }, in_format: :hash)
+
+        fk_columns = schema.filter_map do |row|
+          row.fetch("column_name") if row.fetch("column_name") =~ /_id$/
+        end
+
+        fk_columns.each do |column_name|
+          if foreign_keys_info.none? { |row| row.fetch("column_name") == column_name }
+            agg.push(
+              {
+                table: table,
+                column_name: column_name,
+              }
+            )
+          end
+        end
+
+        agg
+      end
+    end
+  end
+end

data/lib/ruby_pg_extras/missing_fk_indexes.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyPgExtras
+  class MissingFkIndexes
+    def self.call(table_name)
+      new.call(table_name)
+    end
+
+    def call(table_name)
+      tables = if table_name
+          [table_name]
+        else
+          RubyPgExtras.table_size(in_format: :hash).map { |row| row.fetch("name") }
+        end
+
+      tables.reduce([]) do |agg, table|
+        index_info = RubyPgExtras.index_info(args: { table_name: table }, in_format: :hash)
+        schema = RubyPgExtras.table_schema(args: { table_name: table }, in_format: :hash)
+
+        fk_columns = schema.filter_map do |row|
+          row.fetch("column_name") if row.fetch("column_name") =~ /_id$/
+        end
+
+        fk_columns.each do |column_name|
+          if index_info.none? { |row| row.fetch(:columns)[0] == column_name }
+            agg.push(
+              {
+                table: table,
+                column_name: column_name,
+              }
+            )
+          end
+        end
+
+        agg
+      end
+    end
+  end
+end

data/lib/ruby_pg_extras/queries/table_foreign_keys.sql

@@ -0,0 +1,17 @@
+/* Foreign keys info for a specific table  */
+
+SELECT 
+    conrelid::regclass AS table_name,
+    conname AS constraint_name,
+    a.attname AS column_name,
+    confrelid::regclass AS foreign_table_name,
+    af.attname AS foreign_column_name
+FROM 
+    pg_constraint AS c
+JOIN 
+    pg_attribute AS a ON a.attnum = ANY(c.conkey) AND a.attrelid = c.conrelid
+JOIN 
+    pg_attribute AS af ON af.attnum = ANY(c.confkey) AND af.attrelid = c.confrelid
+WHERE 
+    c.contype = 'f'
+    AND c.conrelid = '%{table_name}'::regclass;

data/lib/ruby_pg_extras/queries/table_schema.sql

@@ -0,0 +1,5 @@
+/* Table column names and types */
+
+SELECT column_name, data_type, is_nullable, column_default 
+  FROM information_schema.columns 
+  WHERE table_name = '%{table_name}';

data/lib/ruby_pg_extras/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyPgExtras
-  VERSION = "5.5.1"
+  VERSION = "5.6.0"
 end

data/ruby-pg-extras.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
   s.add_development_dependency "rufo"
+  s.add_development_dependency "dbg-rb"
 
   if s.respond_to?(:metadata=)
     s.metadata = { "rubygems_mfa_required" => "true" }

data/spec/missing_fk_constraints.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ruby-pg-extras"
+
+describe "#missing_fk_constraints" do
+  it "detects missing foreign keys for all tables" do
+    result = RubyPgExtras.missing_fk_constraints(in_format: :hash)
+    expect(result.size).to eq(2)
+    expect(result[0]).to eq({
+                           table: "users", column_name: "company_id",
+                         })
+    expect(result[1]).to eq({
+                           table: "posts", column_name: "topic_id",
+                         })
+  end
+
+  it "detects missing foreign_keys for a specific table" do
+    result = RubyPgExtras.missing_fk_constraints(args: { table_name: "posts" }, in_format: :hash)
+
+    expect(result.size).to eq(1)
+    expect(result[0]).to eq({
+      table: "posts", column_name: "topic_id",
+    })
+  end
+end

data/spec/missing_fk_indexes_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ruby-pg-extras"
+
+describe "missing_fk_indexes" do
+  it "detects missing indexes for all tables" do
+    result = RubyPgExtras.missing_fk_indexes(in_format: :hash)
+    expect(result.size).to eq(2)
+    expect(result[0]).to eq({
+      table: "users", column_name: "company_id",
+    })
+    expect(result[1]).to eq({
+      table: "posts", column_name: "topic_id",
+    })
+  end
+
+  it "detects missing indexes for specific table" do
+    result = RubyPgExtras.missing_fk_indexes(args: { table_name: "posts" }, in_format: :hash)
+    expect(result.size).to eq(1)
+    expect(result[0]).to eq({
+      table: "posts", column_name: "topic_id",
+    })
+  end
+end

data/spec/smoke_spec.rb

@@ -13,7 +13,13 @@ describe RubyPgExtras do
     end
   end
 
-  RubyPgExtras::QUERIES.reject { |q| q == :kill_all }.each do |query_name|
+  SKIP_QUERIES = %i[
+    kill_all
+    table_schema
+    table_foreign_keys
+  ]
+
+  RubyPgExtras::QUERIES.reject { |q| SKIP_QUERIES.include?(q) }.each do |query_name|
     it "#{query_name} query can be executed" do
       expect do
         RubyPgExtras.run_query(
@@ -24,6 +30,34 @@ describe RubyPgExtras do
     end
   end
 
+  describe "table_foreign_keys" do
+    it "returns a correct fk info" do
+      result = RubyPgExtras.table_foreign_keys(args: { table_name: :posts }, in_format: :hash)
+      expect(result.size).to eq(1)
+      expect(result[0].keys).to eq(["table_name", "constraint_name", "column_name", "foreign_table_name", "foreign_column_name"])
+    end
+
+    it "requires table_name arg" do
+      expect {
+        RubyPgExtras.table_foreign_keys(in_format: :hash)
+      }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "table_schema" do
+    it "returns a correct schema" do
+      result = RubyPgExtras.table_schema(args: { table_name: :users }, in_format: :hash)
+      expect(result.size).to eq(3)
+      expect(result[0].keys).to eq(["column_name", "data_type", "is_nullable", "column_default"])
+    end
+
+    it "requires table_name arg" do
+      expect {
+        RubyPgExtras.table_schema(in_format: :hash)
+      }.to raise_error(ArgumentError)
+    end
+  end
+
   describe "#database_url=" do
     it "setting custom database URL works" do
       RubyPgExtras.database_url = ENV.fetch("DATABASE_URL")

data/spec/spec_helper.rb

@@ -6,26 +6,43 @@ require_relative "../lib/ruby-pg-extras"
 
 pg_version = ENV["PG_VERSION"]
 
-port = if pg_version == "12"
-    "5432"
-  elsif pg_version == "13"
-    "5433"
-  elsif pg_version == "14"
-    "5434"
-  elsif pg_version == "15"
-    "5435"
-  elsif pg_version == "16"
-    "5436"
-  elsif pg_version == "17"
-    "5437"
-  else
-    "5432"
-  end
+PG_PORTS = {
+  "12" => "5432",
+  "13" => "5433",
+  "14" => "5434",
+  "15" => "5435",
+  "16" => "5436",
+  "17" => "5437",
+}
+
+port = PG_PORTS.fetch(pg_version, "5432")
 
 ENV["DATABASE_URL"] ||= "postgresql://postgres:secret@localhost:#{port}/ruby-pg-extras-test"
 
 RSpec.configure do |config|
   config.before(:suite) do
+    DB_SCHEMA = <<-SQL
+DROP TABLE IF EXISTS posts;
+DROP TABLE IF EXISTS users;
+
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    email VARCHAR(255),
+    company_id INTEGER
+);
+
+CREATE TABLE posts (
+    id SERIAL PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    topic_id INTEGER,
+    title VARCHAR(255),
+    CONSTRAINT fk_posts_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX index_posts_on_user_id ON posts(user_id);
+SQL
+
+    RubyPgExtras.connection.exec(DB_SCHEMA)
     RubyPgExtras.connection.exec("CREATE EXTENSION IF NOT EXISTS pg_stat_statements;")
     RubyPgExtras.connection.exec("CREATE EXTENSION IF NOT EXISTS pg_buffercache;")
     RubyPgExtras.connection.exec("CREATE EXTENSION IF NOT EXISTS sslinfo;")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pg-extras
 version: !ruby/object:Gem::Version
-  version: 5.5.1
+  version: 5.6.0
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-04 00:00:00.000000000 Z
+date: 2025-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: dbg-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: " Ruby port of Heroku PG Extras. The goal of this project is to provide
   a powerful insights into PostgreSQL database for Ruby on Rails apps that are not
   using the default Heroku PostgreSQL plugin. "
@@ -101,6 +115,8 @@ files:
 - lib/ruby_pg_extras/diagnose_print.rb
 - lib/ruby_pg_extras/index_info.rb
 - lib/ruby_pg_extras/index_info_print.rb
+- lib/ruby_pg_extras/missing_fk_constraints.rb
+- lib/ruby_pg_extras/missing_fk_indexes.rb
 - lib/ruby_pg_extras/queries/add_extensions.sql
 - lib/ruby_pg_extras/queries/all_locks.sql
 - lib/ruby_pg_extras/queries/bloat.sql
@@ -134,8 +150,10 @@ files:
 - lib/ruby_pg_extras/queries/seq_scans.sql
 - lib/ruby_pg_extras/queries/ssl_used.sql
 - lib/ruby_pg_extras/queries/table_cache_hit.sql
+- lib/ruby_pg_extras/queries/table_foreign_keys.sql
 - lib/ruby_pg_extras/queries/table_index_scans.sql
 - lib/ruby_pg_extras/queries/table_indexes_size.sql
+- lib/ruby_pg_extras/queries/table_schema.sql
 - lib/ruby_pg_extras/queries/table_size.sql
 - lib/ruby_pg_extras/queries/tables.sql
 - lib/ruby_pg_extras/queries/total_index_size.sql
@@ -151,6 +169,8 @@ files:
 - spec/diagnose_data_spec.rb
 - spec/diagnose_print_spec.rb
 - spec/index_info_spec.rb
+- spec/missing_fk_constraints.rb
+- spec/missing_fk_indexes_spec.rb
 - spec/size_parser_spec.rb
 - spec/smoke_spec.rb
 - spec/spec_helper.rb
@@ -183,6 +203,8 @@ test_files:
 - spec/diagnose_data_spec.rb
 - spec/diagnose_print_spec.rb
 - spec/index_info_spec.rb
+- spec/missing_fk_constraints.rb
+- spec/missing_fk_indexes_spec.rb
 - spec/size_parser_spec.rb
 - spec/smoke_spec.rb
 - spec/spec_helper.rb