From 173fc1f7beed616adc840e02fef4e7f93e877c69 Mon Sep 17 00:00:00 2001 From: Yves Senn Date: Wed, 21 Oct 2015 09:26:48 +0200 Subject: move documentation of column options to `add_column`. Closes #20400. [ci skip] It's been a source of confusion that the lower-level `add_column` referenced the higher level `column` method for available options. `column` supports additional functionality like `index: true` that is not present on `add_column`. This patch moves common option documentation to `add_column` and only documents the additional options in `column`. --- .../abstract/schema_definitions.rb | 79 ++------------------- .../abstract/schema_statements.rb | 81 ++++++++++++++++++++-- 2 files changed, 81 insertions(+), 79 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb index bceda5abd9..f25f546f1e 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb @@ -238,86 +238,19 @@ module ActiveRecord 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, :bigint, :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 a :string column - # and number of bytes for :text, :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. + # See {connection.add_column}[rdoc-ref:ConnectionAdapters::SchemaStatements#add_column] + # for available options. + # + # Additional options are: # * :index - # Create an index for the column. Can be either true 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 :scale 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 + # # Assuming +td+ is an instance of TableDefinition + # td.column(:granted, :boolean, index: true) # # == Short-hand examples # diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index d3fbc18f97..d5f8dbc8fc 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -446,12 +446,81 @@ module ActiveRecord execute "DROP TABLE#{' IF EXISTS' if options[:if_exists]} #{quote_table_name(table_name)}" end - # Adds a new column to the named table. - # See TableDefinition#column for details of the options you can use. - # - # Note: Not all options will be available, generally this command should - # ignore most of them. In favor of doing a low-level call to simply - # create a column. + # Add a new +type+ column named +column_name+ to +table_name+. + # + # The +type+ parameter is normally one of the migrations native types, + # which is one of the following: + # :primary_key, :string, :text, + # :integer, :bigint, :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 a :string column + # and number of bytes for :text, :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. + # + # 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). + # + # == Examples + # + # add_column(:users, :picture, :binary, limit: 2.megabytes) + # # ALTER TABLE "users" ADD "picture" blob(2097152) + # + # add_column(:articles, :status, :string, limit: 20, default: 'draft', null: false) + # # ALTER TABLE "articles" ADD "status" varchar(20) DEFAULT 'draft' NOT NULL + # + # add_column(:answers, :bill_gates_money, :decimal, precision: 15, scale: 2) + # # ALTER TABLE "answers" ADD "bill_gates_money" decimal(15,2) + # + # add_column(:measurements, :sensor_reading, :decimal, precision: 30, scale: 20) + # # ALTER TABLE "measurements" ADD "sensor_reading" decimal(30,20) + # + # # While :scale defaults to zero on most databases, it + # # probably wouldn't hurt to include it. + # add_column(:measurements, :huge_integer, :decimal, precision: 30) + # # ALTER TABLE "measurements" ADD "huge_integer" decimal(30) + # + # # Defines a column with a database-specific type. + # add_column(:shapes, :triangle, 'polygon') + # # ALTER TABLE "shapes" ADD "triangle" polygon def add_column(table_name, column_name, type, options = {}) at = create_alter_table table_name at.add_column(column_name, type, options) -- cgit v1.2.3