activerecord-analyze 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 226e12a1f8d3b7be66168f555950dff9fb7f1ab8
-  data.tar.gz: 53feb1e87fb720e691586f13cf01963d2eec8ac6
+SHA256:
+  metadata.gz: ef55b677ccdab275d0b76db680c55e8c8534b7e03245dc76f622eca81cb3b244
+  data.tar.gz: 3ee9e2dc7ce0251cab913d79ee3c5b5760b571d27bdf98b132cb8d8751c7c7da
 SHA512:
-  metadata.gz: dde5e026fc7e5e26ca627157078666dc62dbd15bbae2ed517a6060129a1bcb13d344da26de108cf1344068d6ba4ce37892e4ca98062121c517d068a063ffba47
-  data.tar.gz: effb4506e5be439b594f536a4bb30e57133e28445d63b78abef153c3f9386a8e5a669e58e9f6a238caad8b73eb3dd6697c953d3cfd88d7e689aa303496c37f61
+  metadata.gz: 5a1057165667e384853cc9fc83e98b4c98377c2af41057cbe52427cd7a25b8fff99f50321435e4bab1645be97e2d989e026fe3ba85d0d825e53992d1d373ac3b
+  data.tar.gz: 43019fbfa8dff77b956e62eba3750f63b4925eb179876348750414a77c91c0406892a12a3eb719d51e100b8e00e7274a7b41db0054c06d9a061a8887b4be807a

data/.circleci/config.yml

@@ -0,0 +1,30 @@
+version: 2
+jobs:
+  test:
+    docker:
+      - image: circleci/ruby:2.6.5
+        environment:
+          DATABASE_URL: postgresql://postgres:secret@localhost:5432/activerecord-analyze-test
+      - image: circleci/postgres:11.5
+        environment:
+          POSTGRES_USER: postgres
+          POSTGRES_DB: activerecord-analyze-test
+          POSTGRES_PASSWORD: secret
+    parallelism: 1
+    steps:
+      - checkout
+      - run: gem update --system
+      - run: gem install bundler
+      - run: bundle install --path vendor/bundle
+      - run: sudo apt-get update
+      - run: sudo apt install postgresql-client-11
+      - run: dockerize -wait tcp://localhost:5432 -timeout 1m
+      - run:
+          name: Run specs
+          command: |
+            bundle exec rspec spec/
+workflows:
+  version: 2
+  test:
+    jobs:
+      - test

data/README.md

@@ -1,2 +1,114 @@
-# ActiveRecord Analyze
+# ActiveRecord Analyze [![Gem Version](https://badge.fury.io/rb/activerecord-analyze.svg)](https://badge.fury.io/rb/ruby-pg-extras) [![CircleCI](https://circleci.com/gh/pawurb/activerecord-analyze.svg?style=svg)](https://circleci.com/gh/pawurb/activerecord-analyze)
 
+This gem adds an `analyze` method to Active Record query objects. It executes `EXPLAIN ANALYZE` on a query SQL.
+
+You can check out this blog post for more info on how to [debug and fix slow queries in Rails apps](https://pawelurbanek.com/slow-rails-queries).
+
+The following `format` options are supported `:json, :hash, :yaml, :text, :xml`. Especially the `:json` format is useful because it let's you visualize a query plan using [a visualizer tool](https://tatiyants.com/pev/#/plans/new).
+
+![PG Query visualizer plan](https://raw.githubusercontent.com/pawurb/activerecord-analyze/master/query-plan.png)
+
+## Installation
+
+In your Gemfile:
+
+```ruby
+
+gem 'activerecord-analyze'
+
+```
+
+## Options
+
+The `analyze` method supports the following EXPLAIN query options ([PostgreSQL docs reference](https://www.postgresql.org/docs/12/sql-explain.html)):
+
+```
+VERBOSE [ boolean ]
+COSTS [ boolean ]
+SETTINGS [ boolean ]
+BUFFERS [ boolean ]
+TIMING [ boolean ]
+SUMMARY [ boolean ]
+FORMAT { TEXT | XML | JSON | YAML }
+```
+
+You can execute it like that:
+
+```ruby
+
+User.all.analyze(
+  format: :json,
+  verbose: true,
+  costs: true,
+  settings: true,
+  buffers: true,
+  timing: true,
+  summary: true
+)
+
+# EXPLAIN (FORMAT JSON, ANALYZE, VERBOSE, COSTS, SETTINGS, BUFFERS, TIMING, SUMMARY)
+# SELECT "users".* FROM "users"
+# [
+#   {
+#     "Plan": {
+#       "Node Type": "Seq Scan",
+#       "Parallel Aware": false,
+#       "Relation Name": "users",
+#       "Schema": "public",
+#       "Alias": "users",
+#       "Startup Cost": 0.00,
+#       "Total Cost": 11.56,
+#       "Plan Rows": 520,
+#       "Plan Width": 127,
+#       "Actual Startup Time": 0.006,
+#       "Actual Total Time": 0.007,
+#       "Actual Rows": 2,
+#       "Actual Loops": 1,
+#       "Output": ["id", "team_id", "email"],
+#       "Shared Hit Blocks": 1,
+#       "Shared Read Blocks": 0,
+#       "Shared Dirtied Blocks": 0,
+#       "Shared Written Blocks": 0,
+#       "Local Hit Blocks": 0,
+#       "Local Read Blocks": 0,
+#       "Local Dirtied Blocks": 0,
+#       "Local Written Blocks": 0,
+#       "Temp Read Blocks": 0,
+#       "Temp Written Blocks": 0,
+#       "I/O Read Time": 0.000,
+#       "I/O Write Time": 0.000
+#     },
+#     "Settings": {
+#       "cpu_index_tuple_cost": "0.001",
+#       "cpu_operator_cost": "0.0005",
+#       "cpu_tuple_cost": "0.003",
+#       "effective_cache_size": "10800000kB",
+#       "max_parallel_workers_per_gather": "1",
+#       "random_page_cost": "2",
+#       "work_mem": "100MB"
+#     },
+#     "Planning Time": 0.033,
+#     "Triggers": [
+#     ],
+#     "Execution Time": 0.018
+#   }
+# ]
+
+```
+
+Optionally you can disable running the `ANALYZE` query and only generate the plan:
+
+```ruby
+
+User.all.analyze(analyze: false)
+
+# EXPLAIN ANALYZE for: SELECT "users".* FROM "users"
+#                         QUERY PLAN
+# ----------------------------------------------------------
+#  Seq Scan on users  (cost=0.00..15.20 rows=520 width=127)
+
+```
+
+### Disclaimer
+
+It is a bit experimental and can break with new Rails release.

data/activerecord-analyze.gemspec

@@ -15,5 +15,8 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(spec)/})
   gem.require_paths = ["lib"]
   gem.license       = "MIT"
-  gem.add_dependency "rails", "~> 5.1.0"
+  gem.add_dependency "rails", ">= 5.1.0"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "pg"
+  gem.add_development_dependency "rspec"
 end

data/docker-compose.yml.sample

@@ -0,0 +1,11 @@
+version: '3'
+
+services:
+  postgres:
+    image: postgres:11.5-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_DB: ruby-pg-extras-test
+      POSTGRES_PASSWORD: secret
+    ports:
+      - '5432:5432'

data/lib/activerecord-analyze/main.rb

@@ -2,9 +2,60 @@ module ActiveRecord
   module ConnectionAdapters
     module PostgreSQL
       module DatabaseStatements
-        def analyze(arel, binds = [])
-          sql = "EXPLAIN ANALYZE #{to_sql(arel, binds)}"
-          PostgreSQL::ExplainPrettyPrinter.new.pp(exec_query(sql, "EXPLAIN ANALYZE", binds))
+        def analyze(arel, binds = [], opts = {})
+          format_sql = if fmt = opts[:format].presence
+            case fmt
+            when :json
+              "FORMAT JSON,"
+            when :hash
+              "FORMAT JSON,"
+            when :yaml
+              "FORMAT YAML,"
+            when :text
+              "FORMAT TEXT,"
+            when :xml
+              "FORMAT XML,"
+            end
+          end
+
+          verbose_sql = if opts[:verbose] == true
+            ", VERBOSE"
+          end
+
+          costs_sql = if opts[:costs] == true
+            ", COSTS"
+          end
+
+          settings_sql = if opts[:settings] == true
+            ", SETTINGS"
+          end
+
+          buffers_sql = if opts[:buffers] == true
+            ", BUFFERS"
+          end
+
+          timing_sql = if opts[:timing] == true
+            ", TIMING"
+          end
+
+          summary_sql = if opts[:summary] == true
+            ", SUMMARY"
+          end
+
+          analyze_sql = if opts[:analyze] == false
+            ""
+          else
+            "ANALYZE"
+          end
+
+          opts_sql = "(#{format_sql} #{analyze_sql}#{verbose_sql}#{costs_sql}#{settings_sql}#{buffers_sql}#{timing_sql}#{summary_sql})"
+          .strip.gsub(/\s+/, " ")
+          .gsub(/\(\s?\s?\s?,/, "(")
+          .gsub(/\s,\s/, " ")
+          .gsub(/\(\s?\)/, "")
+
+          sql = "EXPLAIN #{opts_sql} #{to_sql(arel, binds)}"
+          PostgreSQL::ExplainPrettyPrinter.new.pp(exec_query(sql, "EXPLAIN #{opts_sql}".strip, binds))
         end
       end
     end
@@ -13,23 +64,42 @@ end
 
 module ActiveRecord
   class Relation
-    def analyze
-      exec_analyze(collecting_queries_for_explain { exec_queries })
+    def analyze(opts = {})
+      res = exec_analyze(collecting_queries_for_explain { exec_queries }, opts)
+      if [:json, :hash].include?(opts[:format])
+        start = res.index("[")
+        finish = res.rindex("]")
+        raw_json = res.slice(start, finish - start + 1)
+
+        if opts[:format] == :json
+          JSON.parse(raw_json).to_json
+        elsif opts[:format] == :hash
+          JSON.parse(raw_json)
+        end
+      else
+        res
+      end
     end
   end
 end
 
 module ActiveRecord
   module Explain
-    def exec_analyze(queries) # :nodoc:
+    def exec_analyze(queries, opts = {}) # :nodoc:
       str = queries.map do |sql, binds|
-        msg = "EXPLAIN ANALYZE for: #{sql}".dup
+        analyze_msg = if opts[:analyze] == false
+          ""
+        else
+          " ANALYZE"
+        end
+
+        msg = "EXPLAIN#{analyze_msg} for: #{sql}".dup
         unless binds.empty?
           msg << " "
           msg << binds.map { |attr| render_bind(attr) }.inspect
         end
         msg << "\n"
-        msg << connection.analyze(sql, binds)
+        msg << connection.analyze(sql, binds, opts)
       end.join("\n")
 
       # Overriding inspect to be more human readable, especially in the console.

data/lib/activerecord-analyze/version.rb

@@ -1,3 +1,3 @@
 module ActiveRecordAnalyze
-  VERSION = "0.2.0"
+  VERSION = "0.6.0"
 end

data/spec/main_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require "migrations/create_users_migration.rb"
+
+class User < ActiveRecord::Base; end
+
+describe "ActiveRecord analyze" do
+  before(:all) do
+    ActiveRecord::Base.establish_connection(
+      ENV.fetch("DATABASE_URL")
+    )
+
+    @schema_migration = ActiveRecord::Base.connection.schema_migration
+    ActiveRecord::Migrator.new(:up, [CreateUsers.new], @schema_migration).migrate
+  end
+
+  describe "no opts" do
+    it "works" do
+      expect do
+        User.all.analyze
+      end.not_to raise_error
+    end
+  end
+
+  describe "format json" do
+    it "works" do
+      result = User.all.analyze(format: :json)
+      expect(JSON.parse(result)[0].keys.sort).to eq [
+        "Execution Time", "Plan", "Planning Time", "Triggers"
+      ]
+    end
+  end
+
+  describe "format hash" do
+    it "works" do
+      result = User.all.analyze(format: :hash)
+      expect(result[0].keys.sort).to eq [
+        "Execution Time", "Plan", "Planning Time", "Triggers"
+      ]
+    end
+  end
+end

data/spec/migrations/create_users_migration.rb

@@ -0,0 +1,10 @@
+class CreateUsers < ActiveRecord::Migration::Current
+  def change
+    create_table :users do |t|
+      t.string :name
+      t.string :email
+
+      t.timestamps
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require "active_record/railtie"
+require 'bundler/setup'
+require_relative '../lib/activerecord-analyze'
+
+ENV["DATABASE_URL"] ||= "postgresql://postgres:secret@localhost:5432/activerecord-analyze-test"

metadata

@@ -1,29 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-analyze
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.6.0
 platform: ruby
 authors:
 - pawurb
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-03-11 00:00:00.000000000 Z
+date: 2021-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.1.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: pg
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: ' Gem adds an "analyze" method to all Active Record query objects. Compatible
   with PostgreSQL database. '
 email:
@@ -32,20 +74,26 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - activerecord-analyze.gemspec
+- docker-compose.yml.sample
 - lib/activerecord-analyze.rb
 - lib/activerecord-analyze/main.rb
 - lib/activerecord-analyze/version.rb
+- query-plan.png
+- spec/main_spec.rb
+- spec/migrations/create_users_migration.rb
+- spec/spec_helper.rb
 homepage: http://github.com/pawurb/activerecord-analyze
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -60,9 +108,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: Add EXPLAIN ANALYZE to Active Record query objects
-test_files: []
+test_files:
+- spec/main_spec.rb
+- spec/migrations/create_users_migration.rb
+- spec/spec_helper.rb