activerecord-analyze 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d52550c794a58f382c5e5e1d1b78463bc0766969e5e3d7818b494bbf7027924e
-  data.tar.gz: 2a884a86a595021e5afc2c43083bb51287db83a5ac56da1ff4a9fe985c35870b
+  metadata.gz: bc476a2e8768df2625298f3b8d3ea7ed574fcfa86c85daf7bdc8793c7773a13c
+  data.tar.gz: acec1d6f2dd3fb3862cc7def00e18f3696f7de11060c6ce1ef91d6da67175375
 SHA512:
-  metadata.gz: 7e10b5364ed42150d2c41f49c3378f0f4e44e886e9f6100ccc073500ed5185e2d97c39f74c3922544ad36ec1f52c7d947ec1385e573bcf994e0c96af461913ad
-  data.tar.gz: 7d531a91c688a6c0127cc55b16f253ccbc9ada4a67b382c7dbfa25694b20ce5e0d33e18ed8ba7d81d5745e6a626c8e2b5769f6a4af52231b28187e461cd07bff
+  metadata.gz: 01ec2a670e10f7a44ae251bfd90f5f15f81ad8e1c280d99439a955e7553f30c67309cd3aeecd5e8c6a1bc844831e66f37bd5edbbc8f92aa5f284035eff943c30
+  data.tar.gz: 42f5fd9278bfb98caaf549d064a2d664c7c1d1cb1629fde8568144dbfd79d729ae6f3506915e26634d17fbf57ab1089d59c2f927697f218d0fa091c8976009f0

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,7 +1,13 @@
-# 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:
@@ -12,6 +18,97 @@ 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)):
+
+```
+BUFFERS [ boolean ] (default: true)
+VERBOSE [ boolean ] (default: true)
+COSTS [ boolean ] (default: false)
+SETTINGS [ boolean ] (default: false)
+TIMING [ boolean ] (default: false)
+SUMMARY [ boolean ] (default: false)
+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. As soon as [this pull request](https://github.com/rails/rails/pull/31374/) is merged it will be obsolete.
+It is a bit experimental and can break with new Rails release.

data/activerecord-analyze.gemspec

@@ -16,4 +16,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.license       = "MIT"
   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,67 @@ 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 = {})
+          default_opts = {
+            buffers: true,
+            verbose: true
+          }
+
+          opts = default_opts.merge(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 +71,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("[\n")
+        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.3.0"
+  VERSION = "0.7.0"
 end

data/spec/main_spec.rb

@@ -0,0 +1,57 @@
+# 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
+
+  describe "supports options" do
+    it "works" do
+      result = User.all.limit(10).where.not(email: nil).analyze(
+        format: :hash,
+        costs: true,
+        timing: true,
+        summary: true
+      )
+      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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-analyze
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.7.0
 platform: ruby
 authors:
 - pawurb
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-06-19 00:00:00.000000000 Z
+date: 2021-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,48 @@ dependencies:
     - - ">="
       - !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,8 +108,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
-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