<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Class: ActiveRecord::ConnectionAdapters::TableDefinition</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Class</strong></td>
<td class="class-name-in-header">ActiveRecord::ConnectionAdapters::TableDefinition</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../../files/lib/active_record/connection_adapters/postgresql_adapter_rb.html">
lib/active_record/connection_adapters/postgresql_adapter.rb
</a>
<br />
<a href="../../../files/lib/active_record/connection_adapters/abstract/schema_definitions_rb.html">
lib/active_record/connection_adapters/abstract/schema_definitions.rb
</a>
<br />
</td>
</tr>
<tr class="top-aligned-row">
<td><strong>Parent:</strong></td>
<td>
Object
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<p>
Represents the schema of an SQL table in an abstract way. This class
provides methods for manipulating the schema representation.
</p>
<p>
Inside migration files, the <tt>t</tt> object in <tt>create_table</tt> and
<tt>change_table</tt> is actually of this type:
</p>
<pre>
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
</pre>
<p>
The table definitions The Columns are stored as a ColumnDefinition in the
<tt>columns</tt> attribute.
</p>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000210">[]</a>
<a href="#M000214">belongs_to</a>
<a href="#M000211">column</a>
<a href="#M000207">method_missing</a>
<a href="#M000206">new</a>
<a href="#M000209">primary_key</a>
<a href="#M000213">references</a>
<a href="#M000212">timestamps</a>
<a href="#M000215">to_sql</a>
<a href="#M000205">xml</a>
<a href="#M000208">xml_column_fallback</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<div id="attribute-list">
<h3 class="section-bar">Attributes</h3>
<div class="name-list">
<table>
<tr class="top-aligned-row context-row">
<td class="context-item-name">columns</td>
<td class="context-item-value"> [RW] </td>
<td class="context-item-desc">
An array of ColumnDefinition objects, representing the <a
href="TableDefinition.html#M000211">column</a> changes that have been
defined.
</td>
</tr>
</table>
</div>
</div>
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Class methods</h3>
<div id="method-M000206" class="method-detail">
<a name="M000206"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000206.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000206.html');return false;">
<span class="method-name">new</span><span class="method-args">(base)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000210" class="method-detail">
<a name="M000210"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000210.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000210.html');return false;">
<span class="method-name">[]</span><span class="method-args">(name)</span>
</a>
</div>
<div class="method-description">
<p>
Returns a ColumnDefinition for the <a
href="TableDefinition.html#M000211">column</a> with name <tt>name</tt>.
</p>
</div>
</div>
<div id="method-M000214" class="method-detail">
<a name="M000214"></a>
<div class="method-heading">
<span class="method-name">belongs_to</span><span class="method-args">(*args)</span>
</div>
<div class="method-description">
<p>
Alias for <a href="TableDefinition.html#M000213">references</a>
</p>
</div>
</div>
<div id="method-M000211" class="method-detail">
<a name="M000211"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000211.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000211.html');return false;">
<span class="method-name">column</span><span class="method-args">(name, type, options = {})</span>
</a>
</div>
<div class="method-description">
<p>
Instantiates a <a href="TableDefinition.html#M000206">new</a> <a
href="TableDefinition.html#M000211">column</a> for the table. The
<tt>type</tt> parameter is normally one of the migrations native types,
which is one of the following: <tt>:<a
href="TableDefinition.html#M000209">primary_key</a></tt>, <tt>:string</tt>,
<tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>,
<tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>, <tt>:date</tt>,
<tt>:binary</tt>, <tt>:boolean</tt>.
</p>
<p>
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.
</p>
<p>
Available options are (none of these exists by default):
</p>
<ul>
<li><tt>:limit</tt> - Requests a maximum <a
href="TableDefinition.html#M000211">column</a> length. This is number of
characters for <tt>:string</tt> and <tt>:text</tt> columns and number of
bytes for :binary and :integer columns.
</li>
<li><tt>:default</tt> - The <a
href="TableDefinition.html#M000211">column</a>‘s default value. Use
nil for NULL.
</li>
<li><tt>:null</tt> - Allows or disallows <tt>NULL</tt> values in the <a
href="TableDefinition.html#M000211">column</a>. This option could have been
named <tt>:null_allowed</tt>.
</li>
<li><tt>:precision</tt> - Specifies the precision for a <tt>:decimal</tt> <a
href="TableDefinition.html#M000211">column</a>.
</li>
<li><tt>:scale</tt> - Specifies the scale for a <tt>:decimal</tt> <a
href="TableDefinition.html#M000211">column</a>.
</li>
</ul>
<p>
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.
</p>
<p>
Please be aware of different RDBMS implementations behavior with
<tt>:decimal</tt> columns:
</p>
<ul>
<li>The SQL standard says the default scale should be 0, <tt>:scale</tt> <=
<tt>:precision</tt>, and makes no comments about the requirements of
<tt>:precision</tt>.
</li>
<li>MySQL: <tt>:precision</tt> [1..63], <tt>:scale</tt> [0..30]. Default is
(10,0).
</li>
<li>PostgreSQL: <tt>:precision</tt> [1..infinity], <tt>:scale</tt>
[0..infinity]. No default.
</li>
<li>SQLite2: Any <tt>:precision</tt> and <tt>:scale</tt> may be used. Internal
storage as strings. No default.
</li>
<li>SQLite3: No restrictions on <tt>:precision</tt> and <tt>:scale</tt>, but
the maximum supported <tt>:precision</tt> is 16. No default.
</li>
<li>Oracle: <tt>:precision</tt> [1..38], <tt>:scale</tt> [-84..127]. Default is
(38,0).
</li>
<li>DB2: <tt>:precision</tt> [1..63], <tt>:scale</tt> [0..62]. Default unknown.
</li>
<li>Firebird: <tt>:precision</tt> [1..18], <tt>:scale</tt> [0..18]. Default
(9,0). Internal types NUMERIC and DECIMAL have different storage rules,
decimal being better.
</li>
<li>FrontBase?: <tt>:precision</tt> [1..38], <tt>:scale</tt> [0..38]. Default
(38,0). WARNING Max <tt>:precision</tt>/<tt>:scale</tt> for NUMERIC is 19,
and DECIMAL is 38.
</li>
<li>SqlServer?: <tt>:precision</tt> [1..38], <tt>:scale</tt> [0..38]. Default
(38,0).
</li>
<li>Sybase: <tt>:precision</tt> [1..38], <tt>:scale</tt> [0..38]. Default
(38,0).
</li>
<li>OpenBase?: Documentation unclear. Claims storage in <tt>double</tt>.
</li>
</ul>
<p>
This method returns <tt>self</tt>.
</p>
<h2>Examples</h2>
<pre>
# 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
</pre>
<h2>Short-hand examples</h2>
<p>
Instead of calling <tt><a
href="TableDefinition.html#M000211">column</a></tt> 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.
</p>
<p>
What can be written like this with the regular calls to <a
href="TableDefinition.html#M000211">column</a>:
</p>
<pre>
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
</pre>
<p>
Can also be written as follows using the short-hand:
</p>
<pre>
create_table :products do |t|
t.integer :shop_id, :creator_id
t.string :name, :value, :default => "Untitled"
t.timestamps
end
</pre>
<p>
There‘s a short-hand method for each of the type values declared at
the top. And then there‘s <a
href="TableDefinition.html#M000212">TableDefinition#timestamps</a>
that‘ll add created_at and <tt>updated_at</tt> as datetimes.
</p>
<p>
<a href="TableDefinition.html#M000213">TableDefinition#references</a> will
add an appropriately-named _id <a
href="TableDefinition.html#M000211">column</a>, plus a corresponding _type
<a href="TableDefinition.html#M000211">column</a> if the
<tt>:polymorphic</tt> option is supplied. If <tt>:polymorphic</tt> is a
hash of options, these will be used when creating the <tt>_type</tt> <a
href="TableDefinition.html#M000211">column</a>. So what can be written like
this:
</p>
<pre>
create_table :taggings do |t|
t.integer :tag_id, :tagger_id, :taggable_id
t.string :tagger_type
t.string :taggable_type, :default => 'Photo'
end
</pre>
<p>
Can also be written as follows using <a
href="TableDefinition.html#M000213">references</a>:
</p>
<pre>
create_table :taggings do |t|
t.references :tag
t.references :tagger, :polymorphic => true
t.references :taggable, :polymorphic => { :default => 'Photo' }
end
</pre>
</div>
</div>
<div id="method-M000207" class="method-detail">
<a name="M000207"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000207.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000207.html');return false;">
<span class="method-name">method_missing</span><span class="method-args">(symbol, *args)</span>
</a>
</div>
<div class="method-description">
<p>
Handles non supported datatypes - e.g. XML
</p>
</div>
</div>
<div id="method-M000209" class="method-detail">
<a name="M000209"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000209.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000209.html');return false;">
<span class="method-name">primary_key</span><span class="method-args">(name)</span>
</a>
</div>
<div class="method-description">
<p>
Appends a primary key definition to the table definition. Can be called
multiple times, but this is probably not a good idea.
</p>
</div>
</div>
<div id="method-M000213" class="method-detail">
<a name="M000213"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000213.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000213.html');return false;">
<span class="method-name">references</span><span class="method-args">(*args)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000212" class="method-detail">
<a name="M000212"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000212.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000212.html');return false;">
<span class="method-name">timestamps</span><span class="method-args">(*args)</span>
</a>
</div>
<div class="method-description">
<p>
Appends <tt>:datetime</tt> columns <tt>:created_at</tt> and
<tt>:updated_at</tt> to the table.
</p>
</div>
</div>
<div id="method-M000215" class="method-detail">
<a name="M000215"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000215.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000215.html');return false;">
<span class="method-name">to_sql</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
Returns a String whose contents are the <a
href="TableDefinition.html#M000211">column</a> definitions concatenated
together. This string can then be prepended and appended to to generate the
final SQL to create the table.
</p>
</div>
</div>
<div id="method-M000205" class="method-detail">
<a name="M000205"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000205.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000205.html');return false;">
<span class="method-name">xml</span><span class="method-args">(*args)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000208" class="method-detail">
<a name="M000208"></a>
<div class="method-heading">
<a href="TableDefinition.src/M000208.html" target="Code" class="method-signature"
onclick="popupCode('TableDefinition.src/M000208.html');return false;">
<span class="method-name">xml_column_fallback</span><span class="method-args">(*args)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d51872cc0e1fdee944d71993f94ac764
>
files
>
532
