Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Provides an easy to access database table/column comments from ActiveRecord

branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.rdoc

activerecord-comments

Super-duper simple gem for getting table/column comments defined in the database.

Background

I wanted a way to easily get to the comments defined in the database, via ActiveRecord. While the underlying implementation may change to become faster and more database agnostic, the public API should remain the same.

Documentation

Read the RDoc

Install

$ sudo gem install remi-activerecord-comments -s http://gems.github.com

Usage

>> require 'activerecord-comments'

>> Fox.comment
=> "Represents a Fox, a creature that craves chunky bacon"

>> ActiveRecord::Base.comment :foxes
=> "Represents a Fox, a creature that craves chunky bacon"

>> ActiveRecord::Base.connection.comment :foxes
=> "Represents a Fox, a creature that craves chunky bacon"

>> Fox.columns
=> [#<ActiveRecord::...>, #<ActiveRecord::...>]

>> Fox.columns.first.name
=> "id"

>> Fox.columns.first.comment
=> "Primary Key"

>> Fox.column_comment :id
=> "Primary Key"

>> ActiveRecord::Base.column_comment :id, :foxes
=> "Primary Key"

>> ActiveRecord::Base.connection.column_comment :id, :foxes
=> "Primary Key"

Database Support

For right now, I'm just supporting MySQL as it's the only database I'm currently using that supports database comments.

If you want to extend activerecord-comments to support comments for your favorite database, the gem is coded in such a way that it should be really easy to extend.

See mysql_adapter.rb for an example of the methods your database adapter needs to support (just `#comment(table)` and `#column_comment(column,table)`).

SQL

If you're unsure how to add comments to your MySQL tables/columns, most MySQL GUIs support this, or you can add comments to your `CREATE TABLE` declarations …

CREATE TABLE foo ( 
  id INT COMMENT 'i am the primary key', 
  foo VARCHAR(100) COMMENT 'foo!' 
) COMMENT 'this table rocks'

for more MySQL examples, see spec/mysql_comments_spec.rb

Future Ideas

  • create `db-doc` or (something) that provides a system for documenting your database schema, whether it be via .yml files or as database comments or whatever. then make `activerecord-comments` an extension to that (basically just a different data store for your schema documentation). there should always be a way to easily document your schema, regardless of whether or not your database(s) supports comments. and, with or without database comments, there should be an easy way to see which tables/columns you have and haven't documented!

Something went wrong with that request. Please try again.