Represents the schema of an SQL table in an abstract way. This class provides methods for manipulating the schema representation.

Inside migration files, the tobject in create_tableand change_tableis actually of this type:

class SomeMigration < ActiveRecord::Migration
  def self.up
    create_table :foo do |t|
      puts t.class  # => "ActiveRecord::ConnectionAdapters::TableDefinition"
    end
  end
  def self.down
    ...
  end
end

The table definitions The Columns are stored as a ColumnDefinition in the columnsattribute.

Methods
#
B
C
M
N
P
R
T
X
Attributes
[RW] columns

An array of ColumnDefinition objects, representing the column changes that have been defined.

Class Public methods
new(base)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 313
def initialize(base)
  @columns = []
  @base = base
end
Instance Public methods
[](name)

Returns a ColumnDefinition for the column with name name.

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 339
def [](name)
  @columns.find {|column| column.name.to_s == name.to_s}
end
belongs_to(*args)
column(name, type, options = {})

Instantiates a new column for the table. The typeparameter is normally one of the migrations native types, which is one of the following: :primary_key, :string, :text, :integer, :float, :decimal, :datetime, :timestamp, :time, :date, :binary, :boolean.

You may use a type not in this list as long as it is supported by your database (for example, “polygon” in MySQL), but this will not be database agnostic and should usually be avoided.

Available options are (none of these exists by default):

  • :limit- Requests a maximum column length. This is number of characters for :stringand :textcolumns and number of bytes for :binary and :integer columns.

  • :default- The column's default value. Use nil for NULL.

  • :null- Allows or disallows NULLvalues in the column. This option could have been named :null_allowed.

  • :precision- Specifies the precision for a :decimalcolumn.

  • :scale- Specifies the scale for a :decimal column.

For clarity's sake: the precision is the number of significant digits, while the scale is the number of digits that can be stored following the decimal point. For example, the number 123.45 has a precision of 5 and a scale of 2. A decimal with a precision of 5 and a scale of 2 can range from -999.99 to 999.99.

Please be aware of different RDBMS implementations behavior with :decimalcolumns:

  • The SQL standard says the default scale should be 0, :scale <= :precision, and makes no comments about the requirements of :precision.

  • MySQL: :precision[1..63], :scale[0..30]. Default is (10,0).

  • PostgreSQL: :precision[1..infinity], :scale [0..infinity]. No default.

  • SQLite2: Any :precisionand :scalemay be used. Internal storage as strings. No default.

  • SQLite3: No restrictions on :precisionand :scale, but the maximum supported :precisionis 16. No default.

  • Oracle: :precision[1..38], :scale[-84..127]. Default is (38,0).

  • DB2: :precision[1..63], :scale[0..62]. Default unknown.

  • Firebird: :precision[1..18], :scale[0..18]. Default (9,0). Internal types NUMERIC and DECIMAL have different storage rules, decimal being better.

  • FrontBase?: :precision[1..38], :scale[0..38]. Default (38,0). WARNING Max :precision/ :scalefor NUMERIC is 19, and DECIMAL is 38.

  • SqlServer?: :precision[1..38], :scale[0..38]. Default (38,0).

  • Sybase: :precision[1..38], :scale[0..38]. Default (38,0).

  • OpenBase?: Documentation unclear. Claims storage in double.

This method returns self.

Examples

# Assuming td is an instance of TableDefinition
td.column(:granted, :boolean)
# granted BOOLEAN
td.column(:picture, :binary, :limit => 2.megabytes)
# => picture BLOB(2097152)
td.column(:sales_stage, :string, :limit => 20, :default => 'new', :null => false)
# => sales_stage VARCHAR(20) DEFAULT 'new' NOT NULL
td.column(:bill_gates_money, :decimal, :precision => 15, :scale => 2)
# => bill_gates_money DECIMAL(15,2)
td.column(:sensor_reading, :decimal, :precision => 30, :scale => 20)
# => sensor_reading DECIMAL(30,20)
# While <tt>:scale</tt> defaults to zero on most databases, it
# probably wouldn't hurt to include it.
td.column(:huge_integer, :decimal, :precision => 30)
# => huge_integer DECIMAL(30)
# Defines a column with a database-specific type.
td.column(:foo, 'polygon')
# => foo polygon

Short-hand examples

Instead of calling columndirectly, you can also work with the short-hand definitions for the default types. They use the type as the method name instead of as a parameter and allow for multiple columns to be defined in a single statement.

What can be written like this with the regular calls to column:

create_table "products", :force => true do |t|
  t.column "shop_id",    :integer
  t.column "creator_id", :integer
  t.column "name",       :string,   :default => "Untitled"
  t.column "value",      :string,   :default => "Untitled"
  t.column "created_at", :datetime
  t.column "updated_at", :datetime
end

Can also be written as follows using the short-hand:

create_table :products do |t|
  t.integer :shop_id, :creator_id
  t.string  :name, :value, :default => "Untitled"
  t.timestamps
end

There's a short-hand method for each of the type values declared at the top. And then there's #timestamps that'll add created_at and updated_atas datetimes.

#references will add an appropriately-named _id column, plus a corresponding _type column if the :polymorphicoption is supplied. If :polymorphic is a hash of options, these will be used when creating the _typecolumn. So what can be written like this:

create_table :taggings do |t|
  t.integer :tag_id, :tagger_id, :taggable_id
  t.string  :tagger_type
  t.string  :taggable_type, :default => 'Photo'
end

Can also be written as follows using references:

create_table :taggings do |t|
  t.references :tag
  t.references :tagger, :polymorphic => true
  t.references :taggable, :polymorphic => { :default => 'Photo' }
end
# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 476
def column(name, type, options = {})
  column = self[name] || ColumnDefinition.new(@base, name, type)
  if options[:limit]
    column.limit = options[:limit]
  elsif native[type.to_sym].is_a?(Hash)
    column.limit = native[type.to_sym][:limit]
  end
  column.precision = options[:precision]
  column.scale = options[:scale]
  column.default = options[:default]
  column.null = options[:null]
  @columns << column unless @columns.include? column
  self
end
method_missing(symbol, *args)

Handles non supported datatypes - e.g. XML

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 319
def method_missing(symbol, *args)
  if symbol.to_s == 'xml'
    xml_column_fallback(args)
  end
end
primary_key(name)

Appends a primary key definition to the table definition. Can be called multiple times, but this is probably not a good idea.

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 334
def primary_key(name)
  column(name, :primary_key)
end
references(*args)
Also aliased as: belongs_to
# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 510
def references(*args)
  options = args.extract_options!
  polymorphic = options.delete(:polymorphic)
  args.each do |col|
    column("#{col}_id", :integer, options)
    column("#{col}_type", :string, polymorphic.is_a?(Hash) ? polymorphic : options) unless polymorphic.nil?
  end
end
timestamps(*args)

Appends :datetimecolumns :created_atand :updated_atto the table.

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 504
def timestamps(*args)
  options = args.extract_options!
  column(:created_at, :datetime, options)
  column(:updated_at, :datetime, options)
end
to_sql()

Returns a String whose contents are the column definitions concatenated together. This string can then be prepended and appended to to generate the final SQL to create the table.

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 523
def to_sql
  @columns.map(&:to_sql) * ', '
end
xml(*args)
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 43
def xml(*args)
  options = args.extract_options!
  column(args[0], 'xml', options)
end
xml_column_fallback(*args)
# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 325
def xml_column_fallback(*args)
  case @base.adapter_name.downcase
    when 'sqlite', 'mysql'
      options = args.extract_options!
      column(args[0], :text, options)
    end
  end