Class: ActiveRecord::ConnectionAdapters::TableDefinition
- Inherits:
-
Object
- Object
- ActiveRecord::ConnectionAdapters::TableDefinition
- Includes:
- TimestampDefaultDeprecation
- Defined in:
- lib/active_record/connection_adapters/abstract/schema_definitions.rb
Overview
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
is actually of this type:
class SomeMigration < ActiveRecord::Migration
def up
create_table :foo do |t|
puts t.class # => "ActiveRecord::ConnectionAdapters::TableDefinition"
end
end
def down
...
end
end
The table definitions The Columns are stored as a ColumnDefinition in the columns
attribute.
Direct Known Subclasses
Instance Attribute Summary collapse
-
#as ⇒ Object
readonly
Returns the value of attribute as.
-
#foreign_keys ⇒ Object
readonly
Returns the value of attribute foreign_keys.
-
#indexes ⇒ Object
An array of ColumnDefinition objects, representing the column changes that have been defined.
-
#name ⇒ Object
readonly
Returns the value of attribute name.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
-
#temporary ⇒ Object
readonly
Returns the value of attribute temporary.
Instance Method Summary collapse
-
#[](name) ⇒ Object
Returns a ColumnDefinition for the column with name
name
. -
#column(name, type, options = {}) ⇒ Object
Instantiates a new column for the table.
- #columns ⇒ Object
-
#foreign_key(table_name, options = {}) ⇒ Object
:nodoc:.
-
#index(column_name, options = {}) ⇒ Object
Adds index options to the indexes hash, keyed by column name This is primarily used to track indexes that need to be created after the table.
-
#initialize(types, name, temporary, options, as = nil) ⇒ TableDefinition
constructor
A new instance of TableDefinition.
-
#new_column_definition(name, type, options) ⇒ Object
:nodoc:.
-
#primary_key(name, type = :primary_key, options = {}) ⇒ Object
Appends a primary key definition to the table definition.
-
#references(*args) ⇒ Object
(also: #belongs_to)
Adds a reference.
- #remove_column(name) ⇒ Object
-
#timestamps(*args) ⇒ Object
Appends
:datetime
columns:created_at
and:updated_at
to the table.
Methods included from TimestampDefaultDeprecation
#emit_warning_if_null_unspecified
Constructor Details
#initialize(types, name, temporary, options, as = nil) ⇒ TableDefinition
Returns a new instance of TableDefinition.
99 100 101 102 103 104 105 106 107 108 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 99 def initialize(types, name, temporary, , as = nil) @columns_hash = {} @indexes = {} @foreign_keys = {} @native = types @temporary = temporary @options = @as = as @name = name end |
Instance Attribute Details
#as ⇒ Object (readonly)
Returns the value of attribute as.
97 98 99 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 97 def as @as end |
#foreign_keys ⇒ Object (readonly)
Returns the value of attribute foreign_keys.
97 98 99 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 97 def foreign_keys @foreign_keys end |
#indexes ⇒ Object
An array of ColumnDefinition objects, representing the column changes that have been defined.
96 97 98 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 96 def indexes @indexes end |
#name ⇒ Object (readonly)
Returns the value of attribute name.
97 98 99 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 97 def name @name end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
97 98 99 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 97 def @options end |
#temporary ⇒ Object (readonly)
Returns the value of attribute temporary.
97 98 99 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 97 def temporary @temporary end |
Instance Method Details
#[](name) ⇒ Object
Returns a ColumnDefinition for the column with name name
.
119 120 121 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 119 def [](name) @columns_hash[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
, :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 disallowsNULL
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. -
:index
- Create an index for the column. Can be eithertrue
or an options hash.
Note: The precision is the total number of significant digits and 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. -
SqlServer?:
:precision
[1..38],:scale
[0..38]. Default (38,0).
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 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 do |t|
t.column :shop_id, :integer
t.column :creator_id, :integer
t.column :item_number, :string
t.column :name, :string, default: "Untitled"
t.column :value, :string, default: "Untitled"
t.column :created_at, :datetime
t.column :updated_at, :datetime
end
add_index :products, :item_number
can also be written as follows using the short-hand:
create_table :products do |t|
t.integer :shop_id, :creator_id
t.string :item_number, index: true
t.string :name, :value, default: "Untitled"
t. null: false
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. The :index
option will also create an index, similar to calling add_index
. 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
add_index :taggings, :tag_id, name: 'index_taggings_on_tag_id'
add_index :taggings, [:tagger_id, :tagger_type]
Can also be written as follows using references:
create_table :taggings do |t|
t.references :tag, index: { name: 'index_taggings_on_tag_id' }
t.references :tagger, polymorphic: true, index: true
t.references :taggable, polymorphic: { default: 'Photo' }
end
256 257 258 259 260 261 262 263 264 265 266 267 268 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 256 def column(name, type, = {}) name = name.to_s type = type.to_sym if @columns_hash[name] && @columns_hash[name].primary_key? raise ArgumentError, "you can't redefine the primary key column '#{name}'. To define a custom primary key, pass { id: false } to create_table." end = .delete(:index) index(name, .is_a?(Hash) ? : {}) if @columns_hash[name] = new_column_definition(name, type, ) self end |
#columns ⇒ Object
110 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 110 def columns; @columns_hash.values; end |
#foreign_key(table_name, options = {}) ⇒ Object
:nodoc:
290 291 292 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 290 def foreign_key(table_name, = {}) # :nodoc: foreign_keys[table_name] = end |
#index(column_name, options = {}) ⇒ Object
Adds index options to the indexes hash, keyed by column name This is primarily used to track indexes that need to be created after the table
index(:account_id, name: 'index_projects_on_account_id')
286 287 288 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 286 def index(column_name, = {}) indexes[column_name] = end |
#new_column_definition(name, type, options) ⇒ Object
:nodoc:
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 337 def new_column_definition(name, type, ) # :nodoc: type = aliased_types(type.to_s, type) column = create_column_definition name, type limit = .fetch(:limit) do native[type][:limit] if native[type].is_a?(Hash) end column.limit = limit column.precision = [:precision] column.scale = [:scale] column.default = [:default] column.null = [:null] column.first = [:first] column.after = [:after] column.primary_key = type == :primary_key || [:primary_key] column end |
#primary_key(name, type = :primary_key, options = {}) ⇒ Object
Appends a primary key definition to the table definition. Can be called multiple times, but this is probably not a good idea.
114 115 116 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 114 def primary_key(name, type = :primary_key, = {}) column(name, type, .merge(:primary_key => true)) end |
#references(*args) ⇒ Object Also known as: belongs_to
Adds a reference. Optionally adds a type
column, if :polymorphic
option is provided. references
and belongs_to
are acceptable. The reference column will be an integer
by default, the :type
option can be used to specify a different type. A foreign key will be created if a foreign_key
option is passed.
t.references(:user)
t.references(:user, type: "string")
t.belongs_to(:supplier, polymorphic: true)
See SchemaStatements#add_reference
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 317 def references(*args) = args. polymorphic = .delete(:polymorphic) = .delete(:index) = .delete(:foreign_key) type = .delete(:type) || :integer if polymorphic && raise ArgumentError, "Cannot add a foreign key on a polymorphic relation" end args.each do |col| column("#{col}_id", type, ) column("#{col}_type", :string, polymorphic.is_a?(Hash) ? polymorphic : ) if polymorphic index(polymorphic ? %w(type id).map { |t| "#{col}_#{t}" } : "#{col}_id", .is_a?(Hash) ? : {}) if foreign_key(col.to_s.pluralize, .is_a?(Hash) ? : {}) if end end |
#remove_column(name) ⇒ Object
270 271 272 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 270 def remove_column(name) @columns_hash.delete name.to_s end |
#timestamps(*args) ⇒ Object
Appends :datetime
columns :created_at
and :updated_at
to the table. See SchemaStatements#add_timestamps
t. null: false
298 299 300 301 302 303 |
# File 'lib/active_record/connection_adapters/abstract/schema_definitions.rb', line 298 def (*args) = args. emit_warning_if_null_unspecified() column(:created_at, :datetime, ) column(:updated_at, :datetime, ) end |