README.md in rails-pg-extras-0.3.0 vs README.md in rails-pg-extras-0.4.0
- old
+ new
@@ -1,8 +1,8 @@
-# Rails PG Extras
+# Rails PG Extras [](https://badge.fury.io/rb/rails-pg-extras)
-Inspired by (a shameless ripoff of) [Heroku PG Extras](https://github.com/heroku/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.
+Rails port of [Heroku PG Extras](https://github.com/heroku/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.
Included rake tasks and Ruby methods can be used to obtain information about a Postgres instance, that may be useful when analyzing performance issues. This includes information about locks, index usage, buffer cache hit ratios and vacuum statistics. Ruby API enables developers to easily integrate the tool into e.g. automatic monitoring tasks.
### Installation
@@ -14,10 +14,47 @@
### Usage
Each command can be used as a rake task, or a directly from the Ruby code.
+```bash
+rake pg_extras:cache_hit
+```
+
+```ruby
+RailsPGExtras.cache_hit
+```
+```bash
++----------------+------------------------+
+| Index and table hit rate |
++----------------+------------------------+
+| name | ratio |
++----------------+------------------------+
+| index hit rate | 0.97796610169491525424 |
+| table hit rate | 0.96724294813466787989 |
++----------------+------------------------+
+```
+
+
+By default the ASCII table is displayed, to change to format you need to specify the `in_format` parameter (`[:display_table, :hash, :array, :raw]` options are available):
+
+```ruby
+RailsPGExtras.cache_hit(in_format: :hash) =>
+
+ [{"name"=>"index hit rate", "ratio"=>"0.97796610169491525424"}, {"name"=>"table hit rate", "ratio"=>"0.96724294813466787989"}]
+
+RailsPGExtras.cache_hit(in_format: :array) =>
+
+ [["index hit rate", "0.97796610169491525424"], ["table hit rate", "0.96724294813466787989"]]
+
+RailsPGExtras.cache_hit(in_format: :raw) =>
+
+ #<PG::Result:0x00007f75777f7328 status=PGRES_TUPLES_OK ntuples=2 nfields=2 cmd_tuples=2>
+```
+
+### Available methods
+
#### `cache_hit`
```bash
$ rake pg_extras:cache_hit
name | ratio
@@ -60,13 +97,21 @@
(4 rows)
```
This command displays queries that have taken out an exlusive lock on a relation. Exclusive locks typically prevent other operations on that relation from taking place, and can be a cause of "hung" queries that are waiting for a lock to be granted.
-### `pg:outliers`
+### `all_locks`
```
+$ rake pg_extras:all_locks
+```
+
+This command displays all the current locks, regardless of their type.
+
+### `outliers`
+
+```
$ rake pg_extras:outliers
qry | exec_time | prop_exec_time | ncalls | sync_io_time
-----------------------------------------+------------------+----------------+-------------+--------------
SELECT * FROM archivable_usage_events.. | 154:39:26.431466 | 72.2% | 34,211,877 | 00:00:00
COPY public.archivable_usage_events (.. | 50:38:33.198418 | 23.6% | 13 | 13:34:21.00108
@@ -307,11 +352,11 @@
public | picnic_table | | | 13 | 0 | 53 |
```
This command displays statistics related to vacuum operations for each table, including an estiamtion of dead rows, last autovacuum and the current autovacuum threshold. This command can be useful when determining if current vacuum thresholds require adjustments, and to determine when the table was last vacuumed.
-### pg:mandelbrot
+### mandelbrot
```
$ rake pg_extras:mandelbrot
```
@@ -320,5 +365,9 @@
## FAQ
* Does is not violate the Heroku PG Extras license?
The original plugin is [MIT based](https://github.com/heroku/heroku-pg-extras/blob/master/LICENSE) so it means that copying and redistribution in any format is permitted.
+
+## Disclaimer
+
+This tool is in beta state.