From 1dc0b2a96095695fabd9210a401484cd5b82146f Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@loudthinking.com>
Date: Wed, 23 Feb 2005 17:03:12 +0000
Subject: Added documentation for database adapters to visible RDoc
git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@771 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
---
.../connection_adapters/mysql_adapter.rb | 17 +++++-
.../connection_adapters/oci_adapter.rb | 63 ++++++++++++----------
.../connection_adapters/postgresql_adapter.rb | 14 ++++-
.../connection_adapters/sqlite_adapter.rb | 13 +++--
.../connection_adapters/sqlserver_adapter.rb | 38 +++++++------
5 files changed, 89 insertions(+), 56 deletions(-)
(limited to 'activerecord/lib')
diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
index 1885a4ca95..cf7c700b66 100755
--- a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
@@ -41,7 +41,22 @@ module ActiveRecord
end
module ConnectionAdapters
- class MysqlAdapter < AbstractAdapter # :nodoc:
+ # The MySQL adapter will work with both Ruby/MySQL, which is a Ruby-based MySQL adapter that comes bundled with Active Record, and with
+ # the faster C-based MySQL/Ruby adapter (available both as a gem and from http://www.tmtm.org/en/mysql/ruby/).
+ #
+ # Options:
+ #
+ # * <tt>:host</tt> -- Defaults to localhost
+ # * <tt>:port</tt> -- Defaults to 3306
+ # * <tt>:socket</tt> -- Defaults to /tmp/mysql.sock
+ # * <tt>:username</tt> -- Defaults to root
+ # * <tt>:password</tt> -- Defaults to nothing
+ # * <tt>:database</tt> -- The name of the database. No default, must be provided.
+ # * <tt>:sslkey</tt> -- Necessary to use MySQL with an SSL connection
+ # * <tt>:sslcert</tt> -- Necessary to use MySQL with an SSL connection
+ # * <tt>:sslcapath</tt> -- Necessary to use MySQL with an SSL connection
+ # * <tt>:sslcipher</tt> -- Necessary to use MySQL with an SSL connection
+ class MysqlAdapter < AbstractAdapter
LOST_CONNECTION_ERROR_MESSAGES = [
"Server shutdown in progress",
"Broken pipe",
diff --git a/activerecord/lib/active_record/connection_adapters/oci_adapter.rb b/activerecord/lib/active_record/connection_adapters/oci_adapter.rb
index eb966fa9bb..8b9b5627e0 100644
--- a/activerecord/lib/active_record/connection_adapters/oci_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/oci_adapter.rb
@@ -1,8 +1,3 @@
-# This is an Oracle adapter for the ActiveRecord persistence framework. It relies upon the OCI8
-# driver, which works with Oracle 8i and above. It was developed on Windows 2000
-# against an 8i database, using ActiveRecord 1.6.0 and OCI8 0.1.9. It has also been tested against
-# a 9i database.
-#
# Implementation notes:
# 1. I had to redefine a method in ActiveRecord to make it possible to implement an autonumbering
# solution for oracle. It's implemented in a way that is intended to not break other adapters.
@@ -17,23 +12,6 @@
# consistency with other adapters I've allowed the LIMIT and OFFSET clauses to be included in
# the sql string and later extracted them by parsing the string.
#
-# Usage notes:
-# 1. Key generation uses a sequence "rails_sequence" for all tables. (I couldn't find a simple
-# and safe way of passing table-specific sequence information to the adapter.)
-# 2. Oracle uses DATE or TIMESTAMP datatypes for both dates and times. Consequently I have had to
-# resort to some hacks to get data converted to Date or Time in Ruby.
-# If the column_name ends in _time it's created as a Ruby Time. Else if the
-# hours/minutes/seconds are 0, I make it a Ruby Date. Else it's a Ruby Time.
-# This is nasty - but if you use Duck Typing you'll probably not care very much.
-# In 9i it's tempting to map DATE to Date and TIMESTAMP to Time but I don't think that is
-# valid - too many databases use DATE for both.
-# Timezones and sub-second precision on timestamps are not supported.
-# 3. Default values that are functions (such as "SYSDATE") are not supported. This is a
-# restriction of the way active record supports default values.
-# 4. Referential integrity constraints are not fully supported. Under at least
-# some circumstances, active record appears to delete parent and child records out of
-# sequence and out of transaction scope. (Or this may just be a problem of test setup.)
-#
# Do what you want with this code, at your own peril, but if any significant portion of my code
# remains then please acknowledge my contribution.
# Copyright 2005 Graham Jenkins
@@ -44,8 +22,8 @@ begin
require_library_or_gem 'oci8' unless self.class.const_defined? :OCI8
module ActiveRecord
- module ConnectionAdapters
- class OCIColumn < Column
+ module ConnectionAdapters #:nodoc:
+ class OCIColumn < Column #:nodoc:
attr_reader :sql_type
def initialize(name, default, limit, sql_type, scale)
@@ -92,6 +70,33 @@ begin
end
end
+ # This is an Oracle adapter for the ActiveRecord persistence framework. It relies upon the OCI8
+ # driver (http://rubyforge.org/projects/ruby-oci8/), which works with Oracle 8i and above.
+ # It was developed on Windows 2000 against an 8i database, using ActiveRecord 1.6.0 and OCI8 0.1.9.
+ # It has also been tested against a 9i database.
+ #
+ # Usage notes:
+ # * Key generation uses a sequence "rails_sequence" for all tables. (I couldn't find a simple
+ # and safe way of passing table-specific sequence information to the adapter.)
+ # * Oracle uses DATE or TIMESTAMP datatypes for both dates and times. Consequently I have had to
+ # resort to some hacks to get data converted to Date or Time in Ruby.
+ # If the column_name ends in _time it's created as a Ruby Time. Else if the
+ # hours/minutes/seconds are 0, I make it a Ruby Date. Else it's a Ruby Time.
+ # This is nasty - but if you use Duck Typing you'll probably not care very much.
+ # In 9i it's tempting to map DATE to Date and TIMESTAMP to Time but I don't think that is
+ # valid - too many databases use DATE for both.
+ # Timezones and sub-second precision on timestamps are not supported.
+ # * Default values that are functions (such as "SYSDATE") are not supported. This is a
+ # restriction of the way active record supports default values.
+ # * Referential integrity constraints are not fully supported. Under at least
+ # some circumstances, active record appears to delete parent and child records out of
+ # sequence and out of transaction scope. (Or this may just be a problem of test setup.)
+ #
+ # Options:
+ #
+ # * <tt>:username</tt> -- Defaults to root
+ # * <tt>:password</tt> -- Defaults to nothing
+ # * <tt>:host</tt> -- Defaults to localhost
class OCIAdapter < AbstractAdapter
def quote_string(s)
s.gsub /'/, "''"
@@ -202,7 +207,7 @@ begin
module ActiveRecord
class Base
- def self.oci_connection(config)
+ def self.oci_connection(config) #:nodoc:
conn = OCI8.new config[:username], config[:password], config[:host]
conn.exec %q{alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'}
conn.exec %q{alter session set nls_timestamp_format = 'YYYY-MM-DD HH24:MI:SS'}
@@ -214,7 +219,7 @@ begin
# Enable the id column to be bound into the sql later, by the adapter's insert method.
# This is preferable to inserting the hard-coded value here, because the insert method
# needs to know the id value explicitly.
- def attributes_with_quotes(creating = true)
+ def attributes_with_quotes(creating = true) #:nodoc:
aq = attributes_with_quotes_pre_oci creating
if connection.class == ConnectionAdapters::OCIAdapter
aq[self.class.primary_key] = ":id" if creating && aq[self.class.primary_key].nil?
@@ -225,7 +230,7 @@ begin
after_save :write_lobs
# After setting large objects to empty, select the OCI8::LOB and write back the data
- def write_lobs()
+ def write_lobs() #:nodoc:
if connection.class == ConnectionAdapters::OCIAdapter
self.class.columns.select { |c| c.type == :binary }.each { |c|
break unless value = self[c.name]
@@ -242,8 +247,8 @@ begin
end
end
- class OCI8
- class Cursor
+ class OCI8 #:nodoc:
+ class Cursor #:nodoc:
alias :define_a_column_pre_ar :define_a_column
def define_a_column(i)
case do_ocicall(@ctx) { @parms[i - 1].attrGet(OCI_ATTR_DATA_TYPE) }
diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
index 934b1e49c9..8b4fb696fc 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -43,8 +43,18 @@ module ActiveRecord
end
module ConnectionAdapters
-
- class PostgreSQLAdapter < AbstractAdapter # :nodoc:
+ # The PostgreSQL adapter works both with the C-based (http://www.postgresql.jp/interfaces/ruby/) and the Ruby-base
+ # (available both as gem and from http://rubyforge.org/frs/?group_id=234&release_id=1145) drivers.
+ #
+ # Options:
+ #
+ # * <tt>:host</tt> -- Defaults to localhost
+ # * <tt>:port</tt> -- Defaults to 5432
+ # * <tt>:username</tt> -- Defaults to nothing
+ # * <tt>:password</tt> -- Defaults to nothing
+ # * <tt>:database</tt> -- The name of the database. No default, must be provided.
+ # * <tt>:schema_order</tt> -- An optional schema order string that is using in a SET search_path TO <schema_order> call on connection.
+ class PostgreSQLAdapter < AbstractAdapter
def select_all(sql, name = nil)
select(sql, name)
end
diff --git a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
index d8f3e04498..4958094ecb 100644
--- a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
@@ -59,9 +59,8 @@ module ActiveRecord
end
end
- module ConnectionAdapters
-
- class SQLiteColumn < Column
+ module ConnectionAdapters #:nodoc:
+ class SQLiteColumn < Column #:nodoc:
def string_to_binary(value)
value.gsub(/(\0|\%)/) do
case $1
@@ -81,7 +80,13 @@ module ActiveRecord
end
end
- class SQLiteAdapter < AbstractAdapter # :nodoc:
+ # The SQLite adapter works with both the 2.x and 3.x series of SQLite with the sqlite-ruby drivers (available both as gems and
+ # from http://rubyforge.org/projects/sqlite-ruby/).
+ #
+ # Options:
+ #
+ # * <tt>:dbfile</tt> -- Path to the database file.
+ class SQLiteAdapter < AbstractAdapter
def execute(sql, name = nil)
log(sql, name) { @connection.execute(sql) }
end
diff --git a/activerecord/lib/active_record/connection_adapters/sqlserver_adapter.rb b/activerecord/lib/active_record/connection_adapters/sqlserver_adapter.rb
index 7bddba9b5b..d221f99be3 100644
--- a/activerecord/lib/active_record/connection_adapters/sqlserver_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/sqlserver_adapter.rb
@@ -5,24 +5,6 @@ require 'active_record/connection_adapters/abstract_adapter'
# Author: Joey Gibson <joey@joeygibson.com>
# Date: 10/14/2004
#
-# REQUIREMENTS:
-#
-# This adapter will ONLY work on Windows systems, since it relies on Win32OLE, which,
-# to my knowledge, is only available on Window.
-#
-# It relies on the ADO support in the DBI module. If you are using the
-# one-click installer of Ruby, then you already have DBI installed, but
-# the ADO module is *NOT* installed. You will need to get the latest
-# source distribution of Ruby-DBI from http://ruby-dbi.sourceforge.net/
-# unzip it, and copy the file src/lib/dbd_ado/ADO.rb to
-# X:/Ruby/lib/ruby/site_ruby/1.8/DBD/ADO/ADO.rb (you will need to create
-# the ADO directory). Once you've installed that file, you are ready to go.
-#
-# This module uses the ADO-style DSNs for connection. For example:
-# "DBI:ADO:Provider=SQLOLEDB;Data Source=(local);Initial Catalog=test;User Id=sa;Password=password;"
-# with User Id replaced with your proper login, and Password with your
-# password.
-#
# I have tested this code on a WindowsXP Pro SP1 system,
# ruby 1.8.2 (2004-07-29) [i386-mswin32], SQL Server 2000.
#
@@ -128,8 +110,24 @@ module ActiveRecord
end
- class SQLServerAdapter < AbstractAdapter # :nodoc:
-
+ # This adapter will ONLY work on Windows systems, since it relies on Win32OLE, which,
+ # to my knowledge, is only available on Window.
+ #
+ # It relies on the ADO support in the DBI module. If you are using the
+ # one-click installer of Ruby, then you already have DBI installed, but
+ # the ADO module is *NOT* installed. You will need to get the latest
+ # source distribution of Ruby-DBI from http://ruby-dbi.sourceforge.net/
+ # unzip it, and copy the file <tt>src/lib/dbd_ado/ADO.rb</tt> to
+ # <tt>X:/Ruby/lib/ruby/site_ruby/1.8/DBD/ADO/ADO.rb</tt> (you will need to create
+ # the ADO directory). Once you've installed that file, you are ready to go.
+ #
+ # Options:
+ #
+ # * <tt>:host</tt> -- Defaults to localhost
+ # * <tt>:username</tt> -- Defaults to sa
+ # * <tt>:password</tt> -- Defaults to nothing
+ # * <tt>:database</tt> -- The name of the database. No default, must be provided.
+ class SQLServerAdapter < AbstractAdapter
def select_all(sql, name = nil)
add_limit!(sql, nil)
select(sql, name)
--
cgit v1.2.3