# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 340 def primary_key(name) column(name, :primary_key) end
Represents the schema of an SQL table in an abstract way. This class provides methods for manipulating the schema representation.
Inside migration files, the t
object in
create_table
and change_table
is 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
columns
attribute.
An array of ColumnDefinition objects, representing the column changes that have been defined.
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 316 def initialize(base) @columns = [] @base = base end
Returns a ColumnDefinition for the column with name name
.
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 345 def [](name) @columns.find {|column| column.name.to_s == name.to_s} end
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.
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
: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
.
# 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
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 #timestamps that’ll
add created_at and updated_at
as datetimes.
#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
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 483 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
Handles non supported datatypes - e.g. XML
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 322 def method_missing(symbol, *args) if symbol.to_s == 'xml' xml_column_fallback(args) else super end end
Appends a primary key definition to the table definition. Can be called multiple times, but this is probably not a good idea.
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 340 def primary_key(name) column(name, :primary_key) end
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 517 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
Appends :datetime
columns :created_at
and
:updated_at
to the table.
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 511 def timestamps(*args) options = args.extract_options! column(:created_at, :datetime, options) column(:updated_at, :datetime, options) end
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 lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 530 def to_sql @columns.map { |c| c.to_sql } * ', ' end
# File lib/active_record/connection_adapters/postgresql_adapter.rb, line 31 def xml(*args) options = args.extract_options! column(args[0], 'xml', options) end
# File lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 330 def xml_column_fallback(*args) case @base.adapter_name.downcase when 'sqlite', 'mysql' options = args.extract_options! column(args[0], :text, options) end end