= SQL Logging plug-in

This SQL Logging plug-in combines three useful SQL debugging tools into
one easy to use plug-in:

* Adam Doppelt's enhancements to the standard logging
* Nathaniel Talbott's QueryTrace plug-in
* silencing the query log or backtrace for code within a block

This plug-in expands and improves on these ideas in some significant ways,
and works on both MySQL and PostgreSQL.

== Usage

Once installed, the out-of-the-box behavior gives you:

* a cleaned-up backtrace after every SQL query, so you know exactly what
  piece of code triggered the query
* a report of the number of rows and rough count of bytes returned after
  each query
* after each request completes, additional summary information telling you
  the number of selects and executes, as well as a rough total number of
  bytes received from the database
* a top 10 list of SQL executions, sorted by total execution time (based on
  the location of the query in code), including the total number of rows
  and bytes returned over all executions

All of this additional information is logged at DEBUG level, so it won't
clutter up your production log files unless you've changed the log level.

== Options

The Top 10 summary provides the most options to customize its behavior.

If you want more or fewer than 10 queries, you can easily change that:

  ActionController::Base.top_sql_queries_shown = 5

If you want the sorted by something other than the total execution time,
you can instead sort by the median execution time, number of executions
or rows/bytes returned over all executions of the query:

  ActionController::Base.show_top_sql_queries = :median_time
  ActionController::Base.show_top_sql_queries = :queries
  ActionController::Base.show_top_sql_queries = :rows
  ActionController::Base.show_top_sql_queries = :bytes

You can also turn the list off entirely:

  ActionController::Base.show_top_sql_queries = false

If you don't want to ever see query backtraces:

  ActiveRecord::Base.log_sql_backtrace = false

If you don't want to ever see queries as they execute or their backtraces:

  ActiveRecord::Base.log_sql_query = false

== Silencing the logging only sometimes

Sometimes, it's useful to silence some of the logging for just a particular
section of code.  There may be useful log statements in the controller or
model that are overshadowed by the sheer number of log statements coming
from ActiveRecord queries.

There are two methods that will silence the logging of a query entirely,
or just the backtrace, for the duration of a block:

  silence_sql do
    # ...
  end

  silence_sql_backtrace do
    # ...
  end

These are available in all controllers and ActiveRecord models.

= Caveats

I'm not yet using ActiveResource, so it may do nothing for you there.

= Acknowledgments

Adam's post describing his logging improvements is at
http://gurge.com/blog/2006/11/09/rails-sql-logging-improvements/.

Nathaniel's QueryTrace is available at
http://terralien.com/projects/querytrace/.

= Contact

Feedback and/or patches to make this plug-in better are greatly
appreciated!

Steve Madsen
Light Year Software, LLC
http://lightyearsoftware.com
steve@lightyearsoftware.com