Ruby on Rails

• Introduction
• Installation
• Usage
• Fields
• End-to-end example
  • Results
• References

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:

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'*/

References