sqlcommenterRuby on Rails
Introduction
sqlcommenter_rails adds comments to your SQL statements.
It is powered by marginalia and also adds OpenCensus information to the comments if you use the opencensus gem.
sqlcommenter_rails configures marginalia and marginalia-opencensus to match the SQLCommenter format.
Installation
Add this line to your application’s Gemfile
gem 'sqlcommenter_rails' Then run bundle and restart your Rails server.
To enable OpenCensus support, add the opencensus gem to your Gemfile, and add the following line in the beginning of config/application.rb:
require 'opencensus/trace/integrations/rails' Usage
All of the SQL queries initiated by the application will now come with comments!
Fields
The following fields will be added to your SQL statements as comments:
| Field | Included by default? | Description | Provided by |
|---|---|---|---|
action | ✔ | Controller action name | marginalia |
application | ✔ | Application name | marginalia |
controller | ✔ | Controller name | marginalia |
controller_with_namespace | ❌ | Full classname (including namespace) of the controller | marginalia |
database | ❌ | Database name | marginalia |
db_driver | ✔ | Database adapter class name | sqlcommenter_rails |
db_host | ❌ | Database hostname | marginalia |
framework | ✔ | rails_v followed by Rails::VERSION | sqlcommenter_rails |
hostname | ❌ | Socket.gethostname | marginalia |
job | ❌ | Classname of the ActiveJob being performed | marginalia |
line | ❌ | File and line number calling query | marginalia |
pid | ❌ | Current process id | marginalia |
route | ✔ | Request’s full path | sqlcommenter_rails |
socket | ❌ | Database socket | marginalia |
traceparent | ❌ | The W3C TraceContext.Traceparent field of the OpenCensus trace | marginalia-opencensus |
To include the traceparent field, install the marginalia-opencensus gem and it will be automatically included by default.
To change which fields are included, set Marginalia::Comment.components = [ :field1, :field2, ... ] in config/initializers/marginalia.rb as described in the marginalia documentation.
End to end example
A Rails 6 sqlcommenter_rails demo is available at: https://github.com/google/sqlcommenter/tree/master/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo
The demo is a vanilla Rails API application with sqlcommenter_rails and OpenCensus enabled.
First, we create a vanilla Rails application with the following command:
gem install rails -v 6.0.0.rc1 rails _6.0.0.rc1_ new sqlcommenter_rails_demo --api Then, we add and implement a basic Post model and controller:
bin/rails g model Post title:text bin/rails g controller Posts index create Implement the controller:
# app/controllers/posts_controller.rb class PostsController < ApplicationController def index render json: Post.all end def create title = params[:title].to_s.strip head :bad_request if title.empty? render json: Post.create!(title: title) end end Configure the routes:
# config/routes.rb Rails.application.routes.draw do resources :posts, only: %i[index create] end Then, we add sqlcommenter_rails and OpenCensus:
# Gemfile gem 'opencensus' gem 'sqlcommenter_rails' # config/application.rb require "opencensus/trace/integrations/rails" Finally, we run bundle to install the newly added gems:
bundle Now, we can start the server:
bin/rails s In a separate terminal, you can monitor the relevant SQL statements in the server log with the following command:
tail -f log/development.log | grep 'Post ' Results
The demo application has 2 endpoints: GET /posts and POST /posts.
GET /posts
curl localhost:3000/posts Post Load (0.1ms) SELECT "posts".* FROM "posts" /* action='index',application='SqlcommenterRailsDemo',controller='posts', db_driver='ActiveRecord::ConnectionAdapters::SQLite3Adapter', framework='rails_v6.0.0.rc1',route='/posts', traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/ POST /posts
curl -X POST localhost:3000/posts -d 'title=my-post' Post Create (0.2ms) INSERT INTO "posts" ("title", "created_at", "updated_at") VALUES (?, ?, ?) /*action='create',application='SqlcommenterRailsDemo', controller='posts',db_driver='ActiveRecord::ConnectionAdapters::SQLite3Adapter', framework='rails_v6.0.0.rc1',route='/posts', traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/