Class: ActiveRecord::ConnectionAdapters::TableDefinition

Inherits:
Object
  • Object
show all
Defined in:
lib/active_record/connection_adapters/abstract/schema_definitions.rb

Overview

Represents a SQL table in an abstract way. Columns are stored as a ColumnDefinition in the columns attribute.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base) ⇒ TableDefinition

Returns a new instance of TableDefinition.



280
281
282
283
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 280

def initialize(base)
  @columns = []
  @base = base
end

Instance Attribute Details

#columns ⇒ Object

Returns the value of attribute columns.



278
279
280
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 278

def columns
  @columns
end

Instance Method Details

#[](name) ⇒ Object

Returns a ColumnDefinition for the column with name name.



292
293
294
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 292

def [](name)
  @columns.find {|column| column.name.to_s == name.to_s}
end

#column(name, type, options = {}) ⇒ Object

Instantiates a new column for the table. The type parameter 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 :string and :text columns and number of bytes for :binary and :integer columns.

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

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

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

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

Please be aware of different RDBMS implementations behavior with :decimal columns:

  • 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 :precision and :scale may be used. Internal storage as strings. No default.

  • SQLite3: No restrictions on :precision and :scale, but the maximum supported :precision is 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/:scale for 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)

Short-hand examples

Instead of calling column directly, 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 TableDefinition#timestamps that’ll add created_at and updated_at as datetimes.

TableDefinition#references will add an appropriately-named _id column, plus a corresponding _type column if the :polymorphic option is supplied. If :polymorphic is a hash of options, these will be used when creating the _type column. 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



419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 419

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

#primary_key(name) ⇒ Object

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



287
288
289
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 287

def primary_key(name)
  column(name, :primary_key)
end

#references(*args) ⇒ Object Also known as: belongs_to 



453
454
455
456
457
458
459
460
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 453

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) ⇒ Object

Appends :datetime columns :created_at and :updated_at to the table.



447
448
449
450
451
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 447

def timestamps(*args)
  options = args.extract_options!
  column(:created_at, :datetime, options)
  column(:updated_at, :datetime, options)
end

#to_sql ⇒ Object

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.



466
467
468
 
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 466

def to_sql
  @columns * ', '
end