ydbi 0.5.7 → 0.5.8

data/doc/DBD_SPEC.rdoc

@@ -1,88 +0,0 @@
-= DBD Specification Version 0.4.0
-By Erik Hollensbe <erik@hollensbe.org>
-
-== FOREWORD
-
-DBI is still in a large state of flux. Previous versions of this
-specification rarely reflected reality, and the 0.4.0 release is an
-attempt to get the code and documentation in touch with each other to
-better reflect said reality.
-
-While this is a goal, nobody's perfect and there is still a lot of
-code to check, sanitize, and otherwise clean up. If you find something
-missing in these specifications while working on a new DBD or a patch
-for DBI, please, do not do what everything else is doing; alert the
-appropriate person to get the spec revised. Doing this will save
-yourself (and the DBI authors) infinite amounts of time.
-
-== WHAT A DBD IS
-
-DBD stands for "DataBase Driver" and is the layer that DBI uses to interface
-with the database. DBDs often employ a low level driver to do the real work
-with the database, leaving the DBD itself to act as a medium between DBI and
-that lower level API.
-
-This allows a great deal of flexibility without having to sacrifice features
-for compatibility. For example, instead of having one PostgreSQL DBD that
-handles all version of PostgreSQL and attempts to limit it's functionality
-based on what version it detects (a error-prone and time/design prohibitive
-process), one can write two PostgreSQL DBD that handle the differences between
-"new" and "old" postgres, all while talking to the same low-level driver (yet
-leveraging different functionality). This method leads to cleaner internals and
-puts the choice of which to use on the end-user, who is probably a lot more
-informed about what features they want than your code.
-
-One traditionally loads a DBD using the DBI.connect method (see DBD LOAD
-PATHS below) which will attempt to load the DBD, connect to the database with
-the arguments supplied and return a DatabaseHandle if successful. However, if
-the DBD is written properly, requiring it directly without DBI's involvement
-(or existence) should not be an issue.
-
-== WHERE DBDs LIVE
-
-DBDs have an expected require path to be loaded by DBI. DBI will attempt to
-load the middle portion of the DBI.connect DSN provided.
-
-Example: DBI.connect("dbi:Mysql:mydb") # requires 'dbd/Mysql'
-
-Since rubygems potentially renders this path virtual, it is not OK to expect
-this path physically exists in one spot on the filesystem. Many assuptions are
-currently made about this and will be pruned in 0.6.0.
-
-If you wish to create submodules for your DBD, create a directory in the 'dbd'
-directory named the same as the DBD. (E.g., "dbd/Mysql" would have a directory
-with files in it relating to the Mysql.rb file that DBI loads).
-
-== HOW DBI INTERFACES WITH YOUR DBD
-
-Your DBD will create classes representing a DBI::BaseDriver, DBI::BaseDatabase,
-and DBI::BaseStatement. DBI will link these to DBI::DriverHandle,
-DBI::DatabaseHandle, and DBI::StatementHandle respectively. Your classes will
-be called by the Handle classes to retreive information to manipulate and send
-to the user. This manipulation can be influenced in a number of ways. 
-
-It is strongly recommended you make the effort to read the RDoc for all six
-of these classes, as they are the meat of this specification, not this
-document.
-
-== BUILDING A DBD FROM SCRATCH
-
-For the purposes of this discussion, we'll call your driver 'Foo'.
-
-Create your module, DBI::DBD::Foo. Store it somewhere in your load path under
-dbd/Foo.rb.
-
-Create classes Driver, Database, and Statement in this new namespace, which
-inherit from DBI::BaseDriver, DBI::BaseDatabase, and DBI::BaseStatement.
-Override (at mininum) the methods that return NotImplementedError in your new
-classes.
-
-Create a method in the root namespace named +driver_name+. This should return a
-string with a short name for your driver, this key will be used in type
-conversion.
-
-Everything else is up to you, up to and including worrying about interacting
-with the database.
-
-At this point, you should be ready to test your driver. See test/DBD_TESTS for
-information on how to configure that.

data/doc/DBI_SPEC.rdoc

@@ -1,157 +0,0 @@
-= DBI Interface Spec, for version 0.4.0
-
-by Erik Hollensbe <erik@hollensbe.org>
-
-== Foreword
-
-DBI is still in a large state of flux. Previous versions of this
-specification rarely reflected reality, and the 0.4.0 release is an
-attempt to get the code and documentation more in sync.
-
-While this is the goal, there is still a lot of
-code to check, sanitize, and otherwise clean up. If you find something
-missing in these specifications while working on a new DBD or a patch
-for DBI, please bring it to our attention (in IRC or on the mailing list)
-to get the spec revised. Doing this will save
-yourself (and the DBI authors) a lot of time.
-
-== Design
-
-With DBI, there are the concepts of driver, database, and statement. The core
-functionality for these concepts is provided by a database driver, or
-DBD.  DBI controls one or more drivers at once, a driver has databases, a
-database may have statements.
-
-DBI uses a delegation model to communicate with its DBDs through a
-series of handles.  When a connection to a database is requested, DBI contacts
-the appropriate DBD and builds a handle in
-its name that it aligns with a DBI base class for that concept. The
-handle provided by the DBD is the first-class method of communication,
-otherwise it resorts to calling the base class methods.  This allows
-DBI to provide a level of consistency unless the DBD author finds it
-otherwise unnecessary.
-
-For example: DBI will provide handy methods like fetch_all and
-fetch_scroll which all leverage the fetch method in the base class,
-and the fetch method must be implemented by the DBD. However, the DBD
-may have an internal representation of fetch_scroll (as is the case
-with the ODBC driver) that may be more suited to direct use, and
-therefore DBI will never see the base class method. This is similar to
-inheritance, but there is a distinct disconnect between the handles
-and the base classes, intentionally so. This way the DBDs have no
-access to the base class and DBI does all the delegation work. Also,
-DBI has no idea what the DBD is doing underneath, nor does it need to
-care as long as valid data is returned.
-
-== Classes
-
-These are the classes that make up the core of DBI and provide
-various functionality:
-
-=== DBI
-Core module, responsible for everything underneath it, kickstarting
-connections and loading drivers.
-
-=== DBI::Row
-
-Responsible for representing the result set and managing the type
-conversion of the result set. 
-
-=== DBI::Utils
-
-Utility methods which propogate through the rest of DBI.
-
-=== DBI::SQL
-
-Utility methods for working with SQL queries. Includes a
-driver-independent SQL bind manager.
-
-=== DBI::ColumnInfo
-
-Responsible for representing the information per column for both
-queries and table descriptions.
-
-=== DBI::Type
-
-Namespace for typecasting classes. These classes are provided with a
-parse method which converts them to a native Ruby type from a string.
-
-=== DBI::TypeUtil
-
-The inverse of DBI::Type, this provides functionality to turn native
-Ruby types into a representation suitable for the DBD's queries.
-
-=== DBI::Binary
-
-The representation of a BLOB/CLOB in a Ruby object. This will
-eventually be rolled into DBI::Type::, but remains here currently for
-compatibility purposes.
-
-=== DBI::Base* and DBI::*Handle
-
-Please see the Design section above for the description of these modules.
-
-== Exceptions
-
-DBI has a slew of custom exceptions it uses to control program flow,
-and alert the user to specific classes of problems.
-
-They currently all live in the DBI namespace, although it's expected
-that there will eventually be an exception namespace.
-
-=== DBI::Warning < RuntimeError
-    For important warnings such as data truncation, etc.
-
-=== DBI::Error < RuntimeError
-    Base class of all other error exceptions.
-    Rescue this to rescue all DBI errors.
-
-=== DBI::InterfaceError < DBI::Error
-    Exception for errors related to the DBI interface rather 
-    than the database itself.
-
-=== DBI::NotImplementedError < DBI::InterfaceError
-    Exception raised if the DBD driver has not specified
-    a mandatory method.
-
-=== DBI::DatabaseError < DBI::Error
-    Exception for errors related to the database.
- 
-    Has three attributes: ((|err|)), ((|errstr|)) and ((|state|)).
-
-=== DBI::DataError < DBI::DatabaseError
-    Exception for errors due to problems with the processed 
-    data, such as division by zero, numeric value out of range, etc.
-
-=== DBI::OperationalError < DBI::DatabaseError
-    Exception for errors related to the database's operation which
-    are not necessarily under the control of the programmer.  This would include
-    such things as unexpected disconnection, failure to find a datasource name,
-    failure to process a transaction, memory allocation errors, etc.
-
-=== DBI::IntegrityError < DBI::DatabaseError
-    Exception raised when the relational integrity of the database
-    is affected, such as when a foreign key constraint is violated.
-
-=== DBI::InternalError < DBI::DatabaseError
-    Exception raised when the database encounters an internal error, 
-    such as a cursor not being valid anymore, or a transaction going out of
-    sync.
-
-=== DBI::ProgrammingError < DBI::DatabaseError
-    Exception raised for programming errors, e.g., table not found
-    or already exists, syntax error in SQL statement, wrong number
-    of parameters specified, etc.
-
-=== DBI::NotSupportedError < DBI::DatabaseError
-    Raised if, e.g., ((<commit>)) is called for a database that does not
-    support transactions.
-
-== API
-
-To save my sanity, I have joined the specification and the rdoc for
-DBI. Please review the specification there.
-
-If you wish to author your own DBD, please see DBD_SPEC.rdoc,
-which is a more in-depth view of the communication between DBI and
-DBDs.

data/doc/homepage/contact.html

@@ -1,62 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
-    <head>
-        <meta http-equiv="content-type" content="application/xhtml+xml; charset=utf-8"/>
-        <title>Ruby/DBI - Direct database access layer for Ruby</title>
-        <link rel="stylesheet" type="text/css" href="ruby-dbi.css"/>
-    </head>
-    <body>
-        <div class="body-container">
-            <h1>Ruby/DBI - Contact Information</h1>
-            <div class="main-container">
-                <div class="nav-container">
-                    <h1>Links</h1>
-                    <a href="index.html">Home</a>
-                    <a href="http://rubyforge.org/projects/ruby-dbi">RubyForge Project</a>
-                    <a href="http://ruby-dbi.rubyforge.org/rdoc/index.html">RDoc</a>
-                    <a href="development.html">Developer Information</a>
-                    <a href="http://www.kitebird.com/articles/ruby-dbi.html">Ruby/DBI Tutorial</a>
-                    <a href="contact.html">Contact/Reporting Bugs</a>
-                </div>
-                <p>
-                If you'd like to contact us to report a bug or submit a patch,
-                please use the <a
-                    href="http://rubyforge.org/tracker/?group_id=234">tracker</a>
-                on RubyForge.
-                </p>
-
-                <p>
-                If you'd like to ask questions about using Ruby/DBI, there is a
-                <a href="http://rubyforge.org/mailman/listinfo/ruby-dbi-users">ruby-dbi-users</a> email list where those questions
-                can be answered. Likewise, <a
-                    href="http://rubyforge.org/mailman/listinfo/ruby-dbi-bugs">ruby-dbi-bugs</a>
-                is for discussing bug reports in detail, and <a
-                    href="http://rubyforge.org/mailman/listinfo/ruby-dbi-devel-new">ruby-dbi-devel-new</a> is for discussing future
-                development and management of the project.
-                </p>
-
-                <p>
-                    If you're an irc user, the <b>#ruby-dbi</b> irc channel on
-                    <b>freenode</b> will get you in touch with developers and
-                    advanced users.
-                </p>
-
-                <p>
-                If these avenues are not working for you for some reason,
-                please feel free to contact <a
-                    href="mailto:erik-at-hollensbe-dot-org">Erik</a> 
-                directly. He will be glad to help!
-                </p>
-            </div>
-            <br />
-            <br />
-            <div class="copyright">
-                &copy;2008 Erik Hollensbe, all rights reserved. Please see the
-                README file for the full copyright notice.  Please see the
-                LICENSE file in the source package for information on
-                redistributing the source or any of the site content.
-            </div>
-        </div>
-    </body>
-</html>

data/doc/homepage/development.html

@@ -1,124 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
-    <head>
-        <meta http-equiv="content-type" content="application/xhtml+xml; charset=utf-8"/>
-        <title>Ruby/DBI - Direct database access layer for Ruby</title>
-        <link rel="stylesheet" type="text/css" href="ruby-dbi.css"/>
-    </head>
-    <body>
-        <div class="body-container">
-            <h1>Ruby/DBI - Development Information</h1>
-            <div class="main-container">
-                <div class="nav-container">
-                    <h1>Links</h1>
-                    <a href="index.html">Home</a>
-                    <a href="http://rubyforge.org/projects/ruby-dbi">RubyForge Project</a>
-                    <a href="http://ruby-dbi.rubyforge.org/rdoc/index.html">RDoc</a>
-                    <a href="development.html">Developer Information</a>
-                    <a href="http://www.kitebird.com/articles/ruby-dbi.html">Ruby/DBI Tutorial</a>
-                    <a href="contact.html">Contact/Reporting Bugs</a>
-                </div>
-                <p>
-                    Regarding patches, please consider these issues:
-                    <br />
-                    <ul>
-                        <li>
-                            If your patch does not contain tests, it better be
-                            very compelling, as someone else will be forced to
-                            write them.
-                        </li>
-                        <li>
-                            Please ensure your patch addresses the whole
-                            problem space. If it's a patch for DBI, makes sure it
-                            works with <b>all</b> DBDs. Likewise, if it is DBD
-                            scope, it should handle all versions of the database
-                            that DBD supports.
-                        </li>
-                        <li>
-                            Please follow the existing formatting in the
-                            files. Check your diffs to see that you aren't
-                            generating patches with tons of formatting-only
-                            changes.
-                        </li>
-                        <li>
-                            If you plan a series of patches, consider setting
-                            up a git repository, or merging your patches before
-                            you submit them.
-                        </li>
-                    </ul>
-                    <br />
-                </p>
-                <p>
-                    Regarding bug reports, please consider these issues:
-                    <br />
-                    <ul>
-                        <li>
-                            Use the tracker if you can. Posting to the lists or
-                            a private email is ok, but if it's multipart or
-                            significantly complex you may be asked to post it
-                            to the tracker anyways.
-                        </li>
-                        <li>
-                            Please search the tracker first, and have a
-                            repeatable use case that accurately describes your
-                            problem.
-                        </li>
-                        <li>
-                            If you post to the tracker, have a rubyforge
-                            account and ensure you're logged in. If you don't,
-                            and questions to need to be asked, your bug will
-                            likely be quickly round-filed.  Our tracker is not
-                            your cathartic dumping ground.
-                        </li>
-                    </ul>
-                <p>
-                If you'd like to contact us to report a bug or submit a patch,
-                please use the <a
-                    href="http://rubyforge.org/tracker/?group_id=234">tracker</a>
-                on RubyForge. If you plan long term development, consider
-                setting up a git repository other developers can pull from.
-                </p>
-
-                <p>
-                    Please see the <a href="contact.html">contact</a> page
-                    about contacting developers or mailing lists.
-                </p>
-
-                <p>
-                    We now use 'git' for our revision control system. We now push
-                    to several locations:
-
-                    <dl>
-                        <dt>Rubyforge</dt>
-                        <dd>git://rubyforge.org/ruby-dbi.git</dd>
-                        <dt>GitHub</dt>
-                        <dd>git://github.com/erikh/ruby-dbi.git</dd>
-                        <dt>hollensbe.org</dt>
-                        <dd>git://hollensbe.org/git/ruby-dbi.git</dd>
-                    </dl>
-                    <br />
-
-                    Forward development occurs in the 'development' branch,
-                    which is version-tagged and merged into 'master' at release
-                    time. 'master' is used to track release versions and
-                    maintenance to those versions.
-                </p>
-
-                <p>
-                    Ruby/DBI is a BSD-licensed product. As a result, the
-                    licensing on your patches must be the same. Please do
-                    not send patches that are of any other license. Thanks!
-                </p>
-            </div>
-            <br />
-            <br />
-            <div class="copyright">
-                &copy;2008 Erik Hollensbe, all rights reserved. Please see the
-                README file for the full copyright notice.  Please see the
-                LICENSE file in the source package for information on
-                redistributing the source or any of the site content.
-            </div>
-        </div>
-    </body>
-</html>

data/doc/homepage/index.html

@@ -1,83 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
-    <head>
-        <meta http-equiv="content-type" content="application/xhtml+xml; charset=utf-8"/>
-        <title>Ruby/DBI - Direct database access layer for Ruby</title>
-        <link rel="stylesheet" type="text/css" href="ruby-dbi.css"/>
-    </head>
-    <body>
-        <div class="body-container">
-            <h1>Ruby/DBI - Direct database access layer for Ruby</h1>
-            <div class="main-container">
-                <div class="nav-container">
-                    <h1>Links</h1>
-                    <a href="index.html">Home</a>
-                    <a href="http://rubyforge.org/projects/ruby-dbi">RubyForge Project</a>
-                    <a href="http://ruby-dbi.rubyforge.org/rdoc/index.html">RDoc</a>
-                    <a href="development.html">Developer Information</a>
-                    <a href="http://www.kitebird.com/articles/ruby-dbi.html">Ruby/DBI Tutorial</a>
-                    <a href="contact.html">Contact/Reporting Bugs</a>
-                </div>
-
-                <p>
-                Ruby/DBI is a database interface in the spirit of Perl's prolific
-                <a href="http://search.cpan.org/~timb/DBI/DBI.pm">DBI</a> authored
-                by Tim Bunce.
-                </p>
-
-                <p>
-                Ruby/DBI differs in quite a few ways, however. It incorporates
-                many "rubyisms" while maintaining the core DBI interface, and a
-                suite of commonly used DBD's are maintained with the
-                application.
-                </p>
-
-                <p>
-                Ruby/DBI is <i>not</i> an ORM, like <a
-                    href="http://ar.rubyonrails.com">ActiveRecord</a> or <a
-                    href="http://datamapper.rubyforge.org">DataMapper</a>. It is a
-                lightweight, centralized API to database manipulation. An ORM may
-                or may not be what you want for a given situation, due to weight,
-                ease-of-use or other issues. Our goal with Ruby/DBI is to provide a
-                compelling, lightweight interface that you can use for things where
-                an ORM is too much or too cumbersome.
-                </p>
-
-                <p>
-                Getting started with Ruby/DBI is very easy if you have a working
-                knowledge of SQL and your target database. Read the <a
-                    href="http://ruby-dbi.rubyforge.org/rdoc/index.html">Documentation</a>
-                to get on your way!
-                </p>
-
-                <p>
-                The maintainer, Erik Hollensbe, has made a commitment to
-                keeping Ruby/DBI compatible with future Ruby releases. There is
-                also a significant interest in enhancing the suite by further
-                clarifying and enforcing the interface, and further tailoring DBI
-                for the specific needs of Ruby users (as opposed to many of the
-                Perlisms maintained) without impacting the goal of the project.
-                There is also significant effort applied to clarifying the
-                underpinnings, making debugging and development simpler.
-                </p>
-
-                <p>
-                Ruby/DBI is a very old project as far as the ruby community is
-                concerned, tracing back to at least 2001. There are plenty of
-                people who <a
-                    href="http://ruby-dbi.rubyforge.org/rdoc/index.html">have
-                    contributed</a> to this effort. Big thanks to the original
-                project lead, Michael Neumann, and Francis Hwang and Daniel Berger, who held the
-                project in escrow for such a long time. 
-                </p>
-            </div>
-            <div class="copyright">
-                &copy;2008 Erik Hollensbe, all rights reserved. Please see the
-                README file for the full copyright notice.  Please see the
-                LICENSE file in the source package for information on
-                redistributing the source or any of the site content.
-            </div>
-        </div>
-    </body>
-</html>