Skip to Content Skip to Search

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[7.0]
  def up
    create_table :foo do |t|
      puts t.class  # => "ActiveRecord::ConnectionAdapters::TableDefinition"
    end
  end

  def down
    ...
  end
end
Methods
#
B
C
F
I
N
R
T
Included Modules

Attributes

[R] as
[R] check_constraints
[R] comment
[R] foreign_keys
[R] if_not_exists
[R] indexes
[R] name
[R] options
[R] temporary

Class Public methods

new( conn, name, temporary: false, if_not_exists: false, options: nil, as: nil, comment: nil, ** )

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 306
def initialize(
  conn,
  name,
  temporary: false,
  if_not_exists: false,
  options: nil,
  as: nil,
  comment: nil,
  **
)
  @conn = conn
  @columns_hash = {}
  @indexes = []
  @foreign_keys = []
  @primary_keys = nil
  @check_constraints = []
  @temporary = temporary
  @if_not_exists = if_not_exists
  @options = options
  @as = as
  @name = name
  @comment = comment
end

Instance Public methods

[](name)

Returns a ColumnDefinition for the column with name name.

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 339
def [](name)
  @columns_hash[name.to_s]
end

belongs_to(*args, **options)

Alias for: references

check_constraint(expression, **options)

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 443
def check_constraint(expression, **options)
  check_constraints << new_check_constraint_definition(expression, options)
end

column(name, type, index: nil, **options)

Instantiates a new column for the table. See connection.add_column for available options.

Additional options are:

  • :index - Create an index for the column. Can be either true or an options hash.

This method returns self.

Examples

# Assuming +td+ is an instance of TableDefinition
td.column(:granted, :boolean, index: true)

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.timestamps 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
  t.references :taggable, polymorphic: { default: 'Photo' }, index: false
end

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 410
def column(name, type, index: nil, **options)
  name = name.to_s
  type = type.to_sym if type

  raise_on_duplicate_column(name)
  @columns_hash[name] = new_column_definition(name, type, **options)

  if index
    index_options = index.is_a?(Hash) ? index : {}
    index(name, **index_options)
  end

  self
end

columns()

Returns an array of ColumnDefinition objects for the columns of the table.

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 336
def columns; @columns_hash.values; end

foreign_key(to_table, **options)

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 439
def foreign_key(to_table, **options)
  foreign_keys << new_foreign_key_definition(to_table, options)
end

index(column_name, **options)

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')

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 435
def index(column_name, **options)
  indexes << [column_name, options]
end

references(*args, **options)

Adds a reference.

t.references(:user)
t.belongs_to(:supplier, foreign_key: true)
t.belongs_to(:supplier, foreign_key: true, type: :integer)

See connection.add_reference for details of the options you can use.

Also aliased as: belongs_to

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 469
def references(*args, **options)
  args.each do |ref_name|
    ReferenceDefinition.new(ref_name, **options).add_to(self)
  end
end

remove_column(name)

remove the column name from the table.

remove_column(:account_id)

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 427
def remove_column(name)
  @columns_hash.delete name.to_s
end

timestamps(**options)

Appends :datetime columns :created_at and :updated_at to the table. See connection.add_timestamps

t.timestamps null: false

Source: show | on GitHub 

# File activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 451
def timestamps(**options)
  options[:null] = false if options[:null].nil?

  if !options.key?(:precision) && @conn.supports_datetime_with_precision?
    options[:precision] = 6
  end

  column(:created_at, :datetime, **options)
  column(:updated_at, :datetime, **options)
end