<?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>Module: ActiveRecord::ConnectionAdapters::DatabaseStatements</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>Module</strong></td>
<td class="class-name-in-header">ActiveRecord::ConnectionAdapters::DatabaseStatements</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../../files/lib/active_record/connection_adapters/abstract/database_statements_rb.html">
lib/active_record/connection_adapters/abstract/database_statements.rb
</a>
<br />
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000128">add_limit!</a>
<a href="#M000129">add_limit_offset!</a>
<a href="#M000130">add_lock!</a>
<a href="#M000125">begin_db_transaction</a>
<a href="#M000135">case_sensitive_equality_operator</a>
<a href="#M000126">commit_db_transaction</a>
<a href="#M000131">default_sequence_name</a>
<a href="#M000122">delete</a>
<a href="#M000140">delete_sql</a>
<a href="#M000134">empty_insert_statement</a>
<a href="#M000119">execute</a>
<a href="#M000120">insert</a>
<a href="#M000133">insert_fixture</a>
<a href="#M000138">insert_sql</a>
<a href="#M000136">limited_update_conditions</a>
<a href="#M000123">outside_transaction?</a>
<a href="#M000132">reset_sequence!</a>
<a href="#M000127">rollback_db_transaction</a>
<a href="#M000141">sanitize_limit</a>
<a href="#M000137">select</a>
<a href="#M000114">select_all</a>
<a href="#M000115">select_one</a>
<a href="#M000118">select_rows</a>
<a href="#M000116">select_value</a>
<a href="#M000117">select_values</a>
<a href="#M000124">transaction</a>
<a href="#M000121">update</a>
<a href="#M000139">update_sql</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000128" class="method-detail">
<a name="M000128"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000128.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000128.html');return false;">
<span class="method-name">add_limit!</span><span class="method-args">(sql, options)</span>
</a>
</div>
<div class="method-description">
<p>
Alias for <tt><a
href="DatabaseStatements.html#M000129">add_limit_offset!</a></tt>.
</p>
</div>
</div>
<div id="method-M000129" class="method-detail">
<a name="M000129"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000129.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000129.html');return false;">
<span class="method-name">add_limit_offset!</span><span class="method-args">(sql, options)</span>
</a>
</div>
<div class="method-description">
<p>
Appends <tt>LIMIT</tt> and <tt>OFFSET</tt> options to an SQL statement, or
some SQL fragment that has the same semantics as LIMIT and OFFSET.
</p>
<p>
<tt>options</tt> must be a Hash which contains a +:limit+ option (required)
and an +:offset+ option (optional).
</p>
<p>
This method <b>modifies</b> the <tt>sql</tt> parameter.
</p>
<h5>Examples</h5>
<pre>
add_limit_offset!('SELECT * FROM suppliers', {:limit => 10, :offset => 50})
</pre>
<p>
generates
</p>
<pre>
SELECT * FROM suppliers LIMIT 10 OFFSET 50
</pre>
</div>
</div>
<div id="method-M000130" class="method-detail">
<a name="M000130"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000130.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000130.html');return false;">
<span class="method-name">add_lock!</span><span class="method-args">(sql, options)</span>
</a>
</div>
<div class="method-description">
<p>
Appends a locking clause to an SQL statement. This method <b>modifies</b>
the <tt>sql</tt> parameter.
</p>
<pre>
# SELECT * FROM suppliers FOR UPDATE
add_lock! 'SELECT * FROM suppliers', :lock => true
add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'
</pre>
</div>
</div>
<div id="method-M000125" class="method-detail">
<a name="M000125"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000125.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000125.html');return false;">
<span class="method-name">begin_db_transaction</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
Begins the <a href="DatabaseStatements.html#M000124">transaction</a> (and
turns off auto-committing).
</p>
</div>
</div>
<div id="method-M000135" class="method-detail">
<a name="M000135"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000135.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000135.html');return false;">
<span class="method-name">case_sensitive_equality_operator</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000126" class="method-detail">
<a name="M000126"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000126.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000126.html');return false;">
<span class="method-name">commit_db_transaction</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
Commits the <a href="DatabaseStatements.html#M000124">transaction</a> (and
turns on auto-committing).
</p>
</div>
</div>
<div id="method-M000131" class="method-detail">
<a name="M000131"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000131.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000131.html');return false;">
<span class="method-name">default_sequence_name</span><span class="method-args">(table, column)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000122" class="method-detail">
<a name="M000122"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000122.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000122.html');return false;">
<span class="method-name">delete</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Executes the <a href="DatabaseStatements.html#M000122">delete</a> statement
and returns the number of rows affected.
</p>
</div>
</div>
<div id="method-M000134" class="method-detail">
<a name="M000134"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000134.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000134.html');return false;">
<span class="method-name">empty_insert_statement</span><span class="method-args">(table_name)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000119" class="method-detail">
<a name="M000119"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000119.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000119.html');return false;">
<span class="method-name">execute</span><span class="method-args">(sql, name = nil, skip_logging = false)</span>
</a>
</div>
<div class="method-description">
<p>
Executes the SQL statement in the context of this connection.
</p>
</div>
</div>
<div id="method-M000120" class="method-detail">
<a name="M000120"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000120.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000120.html');return false;">
<span class="method-name">insert</span><span class="method-args">(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns the last auto-generated ID from the affected table.
</p>
</div>
</div>
<div id="method-M000133" class="method-detail">
<a name="M000133"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000133.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000133.html');return false;">
<span class="method-name">insert_fixture</span><span class="method-args">(fixture, table_name)</span>
</a>
</div>
<div class="method-description">
<p>
Inserts the given fixture into the table. Overridden in adapters that
require something beyond a simple <a
href="DatabaseStatements.html#M000120">insert</a> (eg. Oracle).
</p>
</div>
</div>
<div id="method-M000136" class="method-detail">
<a name="M000136"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000136.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000136.html');return false;">
<span class="method-name">limited_update_conditions</span><span class="method-args">(where_sql, quoted_table_name, quoted_primary_key)</span>
</a>
</div>
<div class="method-description">
</div>
</div>
<div id="method-M000123" class="method-detail">
<a name="M000123"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000123.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000123.html');return false;">
<span class="method-name">outside_transaction?</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
Checks whether there is currently no <a
href="DatabaseStatements.html#M000124">transaction</a> active. This is done
by querying the database driver, and does not use the <a
href="DatabaseStatements.html#M000124">transaction</a> house-keeping
information recorded by increment_open_transactions and friends.
</p>
<p>
Returns true if there is no <a
href="DatabaseStatements.html#M000124">transaction</a> active, false if
there is a <a href="DatabaseStatements.html#M000124">transaction</a>
active, and nil if this information is unknown.
</p>
<p>
Not all adapters supports <a
href="DatabaseStatements.html#M000124">transaction</a> state introspection.
Currently, only the PostgreSQL adapter supports this.
</p>
</div>
</div>
<div id="method-M000132" class="method-detail">
<a name="M000132"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000132.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000132.html');return false;">
<span class="method-name">reset_sequence!</span><span class="method-args">(table, column, sequence = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Set the sequence to the max value of the table‘s column.
</p>
</div>
</div>
<div id="method-M000127" class="method-detail">
<a name="M000127"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000127.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000127.html');return false;">
<span class="method-name">rollback_db_transaction</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
Rolls back the <a href="DatabaseStatements.html#M000124">transaction</a>
(and turns on auto-committing). Must be done if the <a
href="DatabaseStatements.html#M000124">transaction</a> block raises an
exception or returns false.
</p>
</div>
</div>
<div id="method-M000114" class="method-detail">
<a name="M000114"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000114.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000114.html');return false;">
<span class="method-name">select_all</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns an array of record hashes with the column names as keys and column
values as values.
</p>
</div>
</div>
<div id="method-M000115" class="method-detail">
<a name="M000115"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000115.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000115.html');return false;">
<span class="method-name">select_one</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns a record hash with the column names as keys and column values as
values.
</p>
</div>
</div>
<div id="method-M000118" class="method-detail">
<a name="M000118"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000118.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000118.html');return false;">
<span class="method-name">select_rows</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns an array of arrays containing the field values. Order is the same
as that returned by <tt>columns</tt>.
</p>
</div>
</div>
<div id="method-M000116" class="method-detail">
<a name="M000116"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000116.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000116.html');return false;">
<span class="method-name">select_value</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns a single value from a record
</p>
</div>
</div>
<div id="method-M000117" class="method-detail">
<a name="M000117"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000117.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000117.html');return false;">
<span class="method-name">select_values</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns an array of the values of the first column in a <a
href="DatabaseStatements.html#M000137">select</a>:
</p>
<pre>
select_values("SELECT id FROM companies LIMIT 3") => [1,2,3]
</pre>
</div>
</div>
<div id="method-M000124" class="method-detail">
<a name="M000124"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000124.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000124.html');return false;">
<span class="method-name">transaction</span><span class="method-args">(options = {}) {|| ...}</span>
</a>
</div>
<div class="method-description">
<p>
Runs the given block in a database <a
href="DatabaseStatements.html#M000124">transaction</a>, and returns the
result of the block.
</p>
<h2>Nested transactions support</h2>
<p>
Most databases don‘t support true nested transactions. At the time of
writing, the only database that supports true nested transactions that
we‘re aware of, is MS-SQL.
</p>
<p>
In order to get around this problem, <a
href="DatabaseStatements.html#M000124">transaction</a> will emulate the
effect of nested transactions, by using savepoints: <a
href="http://dev.mysql.com/doc/refman/5.0/en/savepoints.html">dev.mysql.com/doc/refman/5.0/en/savepoints.html</a>
Savepoints are supported by MySQL and PostgreSQL, but not SQLite3.
</p>
<p>
It is safe to call this method if a database <a
href="DatabaseStatements.html#M000124">transaction</a> is already open,
i.e. if <a href="DatabaseStatements.html#M000124">transaction</a> is called
within another <a href="DatabaseStatements.html#M000124">transaction</a>
block. In case of a nested call, <a
href="DatabaseStatements.html#M000124">transaction</a> will behave as
follows:
</p>
<ul>
<li>The block will be run without doing anything. All database statements that
happen within the block are effectively appended to the already open
database <a href="DatabaseStatements.html#M000124">transaction</a>.
</li>
<li>However, if +:requires_new+ is set, the block will be wrapped in a database
savepoint acting as a sub-<a
href="DatabaseStatements.html#M000124">transaction</a>.
</li>
</ul>
<h3>Caveats</h3>
<p>
MySQL doesn‘t support DDL transactions. If you perform a DDL
operation, then any created savepoints will be automatically released. For
example, if you‘ve created a savepoint, then you <a
href="DatabaseStatements.html#M000119">execute</a> a CREATE TABLE
statement, then the savepoint that was created will be automatically
released.
</p>
<p>
This means that, on MySQL, you shouldn‘t <a
href="DatabaseStatements.html#M000119">execute</a> DDL operations inside a
<a href="DatabaseStatements.html#M000124">transaction</a> call that you
know might create a savepoint. Otherwise, <a
href="DatabaseStatements.html#M000124">transaction</a> will raise
exceptions when it tries to release the already-automatically-released
savepoints:
</p>
<pre>
Model.connection.transaction do # BEGIN
Model.connection.transaction(:requires_new => true) do # CREATE SAVEPOINT active_record_1
Model.connection.create_table(...)
# active_record_1 now automatically released
end # RELEASE SAVEPOINT active_record_1 <--- BOOM! database error!
end
</pre>
</div>
</div>
<div id="method-M000121" class="method-detail">
<a name="M000121"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000121.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000121.html');return false;">
<span class="method-name">update</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Executes the <a href="DatabaseStatements.html#M000121">update</a> statement
and returns the number of rows affected.
</p>
</div>
</div>
<h3 class="section-bar">Protected Instance methods</h3>
<div id="method-M000140" class="method-detail">
<a name="M000140"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000140.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000140.html');return false;">
<span class="method-name">delete_sql</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Executes the <a href="DatabaseStatements.html#M000122">delete</a> statement
and returns the number of rows affected.
</p>
</div>
</div>
<div id="method-M000138" class="method-detail">
<a name="M000138"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000138.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000138.html');return false;">
<span class="method-name">insert_sql</span><span class="method-args">(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns the last auto-generated ID from the affected table.
</p>
</div>
</div>
<div id="method-M000141" class="method-detail">
<a name="M000141"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000141.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000141.html');return false;">
<span class="method-name">sanitize_limit</span><span class="method-args">(limit)</span>
</a>
</div>
<div class="method-description">
<p>
Sanitizes the given LIMIT parameter in order to prevent SQL injection.
</p>
<p>
<tt>limit</tt> may be anything that can evaluate to a string via to_s. It
should look like an integer, or a comma-delimited list of integers.
</p>
<p>
Returns the sanitized limit parameter, either as an integer, or as a string
which contains a comma-delimited list of integers.
</p>
</div>
</div>
<div id="method-M000137" class="method-detail">
<a name="M000137"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000137.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000137.html');return false;">
<span class="method-name">select</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Returns an array of record hashes with the column names as keys and column
values as values.
</p>
</div>
</div>
<div id="method-M000139" class="method-detail">
<a name="M000139"></a>
<div class="method-heading">
<a href="DatabaseStatements.src/M000139.html" target="Code" class="method-signature"
onclick="popupCode('DatabaseStatements.src/M000139.html');return false;">
<span class="method-name">update_sql</span><span class="method-args">(sql, name = nil)</span>
</a>
</div>
<div class="method-description">
<p>
Executes the <a href="DatabaseStatements.html#M000121">update</a> statement
and returns the number of rows affected.
</p>
</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
>
349
