activerecord-analyze 0.4.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5163e6745e43205926a1c88a02c4459bd3d9971dde022f5dd64c3368d2c72c13
-  data.tar.gz: f084b56b9a5b9c5ba1e6ae69e6653c01224287b6e0107ca97666cbd695c04b73
+  metadata.gz: b2021239ed9352a040106ce8c1de50503e785fccd9a3093928eeaf5dfa79a0dc
+  data.tar.gz: 8ba00244e759dc1f31091ec4196aded3887c9007902faf867431ea2ef9ae93dc
 SHA512:
-  metadata.gz: 10a11c9983859c51270ae38503e6f751b49f281c85c2f5fd7f28a7709f93d285e6288db8c00741e402f031771b1208c531a142ee28b2bcf5f84d8f14f84c8c18
-  data.tar.gz: 3669dc47d6dc8e4b1b63881d3bf61fa2d6eff4be1264dab55f77a98a6e55d98ebf22cd37e22b731f1d866954c20032f381d3577db168527d7490b88275037f98
+  metadata.gz: ad2874f8422dc7299b8b7b3036fbec8e90f29780862ea3dd192629894905aafede52731314cc569afb6c9ce31f61a379b31ac308af0c304fc9e72bea583e58a7
+  data.tar.gz: 114236b8af394e3f7fad06549e3bc99fa1814e815dd93282c7d3abfc0a0535ee568d90c0360abab021c83a7f1b38d2bfd0bfec31f043720893ab321776fe83fe

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/activerecord-analyze) [![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 ]
+VERBOSE [ boolean ]
+COSTS [ boolean ]
+SETTINGS [ 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

@@ -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

@@ -7,6 +7,8 @@ module ActiveRecord
             case fmt
             when :json
               "FORMAT JSON,"
+            when :hash
+              "FORMAT JSON,"
             when :yaml
               "FORMAT YAML,"
             when :text
@@ -50,6 +52,7 @@ module ActiveRecord
           .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))
@@ -62,7 +65,20 @@ end
 module ActiveRecord
   class Relation
     def analyze(opts = {})
-      exec_analyze(collecting_queries_for_explain { exec_queries }, 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
@@ -71,7 +87,13 @@ module ActiveRecord
   module Explain
     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

data/lib/activerecord-analyze/version.rb

@@ -1,3 +1,3 @@
 module ActiveRecordAnalyze
-  VERSION = "0.4.0"
+  VERSION = "0.7.1"
 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.4.0
+  version: 0.7.1
 platform: ruby
 authors:
 - pawurb
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-12 00:00:00.000000000 Z
+date: 2021-04-09 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,15 +74,21 @@ 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
@@ -64,4 +112,7 @@ 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