ydbi 0.5.2 → 0.5.7

data/Gemfile

@@ -0,0 +1,5 @@
+# A sample Gemfile
+source "https://rubygems.org"
+
+gemspec
+gem 'pg'

data/Rakefile

@@ -0,0 +1,10 @@
+$:.unshift 'build'
+if File.exists? 'lib/dbi'
+    require 'Rakefile.dbi'
+elsif File.exists? 'lib/dbd'
+    require 'rake_task_lib'
+    build_dbd_tasks(File.basename(Dir['lib/dbd/*.rb'][0], '.rb').downcase)
+else
+    abort "Well, this is odd; No DBI or DBD found."
+end
+require 'bundler/gem_tasks'

data/TODO

@@ -0,0 +1,44 @@
+0.4.0:
+    x Work
+     x Postgres quoting toggles
+     x Postgres binding toggles
+     x Test for #20489
+    * Release checklist:
+     x Update ChangeLog
+     x rake
+     x remove all related gems, install all DBI/DBD gems (check prereqs)
+     x write a few test scripts to make sure drivers are loading  
+     x Update homepage (irc channel, git, other changes)
+     * tag as 0.4.0
+     * upload rdoc
+     * upload packages
+     * release announcement (rf, ruby-talk, dbi lists, other places?)
+     * rebase master from development
+     * BEER 
+0.6.0:
+    * Cleanup:
+     * Arrays:
+          * Find some way to get the extents of an array type
+           * checked pg_type, pg_attribute and pg_class, can't find anything.
+           * I don't think this is possible, but let's slate it for 0.6.0 anyways.
+     * Tracing
+      * WTH do we want to do with this
+       * Wow, this module has *serious issues*. Crashes DBI without warning. Redo this completely.
+        * 0.6.0
+    * Re-institute drivers
+     * Proxy
+      * Slated for 0.6.0
+    * Finish type management system
+     * Unify ColumnInfo
+      * Should we enforce ColumnInfo requirements at the DBI level?
+       * At least test the result of statement colinfo uniformly
+       * 0.6.0
+    * Cleanup core
+     * Require code is a mess
+      * Just remove the case-sensitivity from the DBDs in general
+       * 0.6.0
+     * Find a good clean way to enumerate drivers in separate gems
+      * Some registration-on-require would be cleaner and safer
+       * 0.6.0
+    * Scripts
+     * bin/dbd_proxy seems to have never worked; slate it for 0.6.0

data/bench/bench.rb

@@ -0,0 +1,79 @@
+require 'rubygems'
+$:.unshift File.dirname(__FILE__) + '/../lib'
+require 'dbi'
+
+class DbiBenchmark
+	attr_reader :db
+
+	def initialize db, quiet=false
+		@db = db
+		@quiet = quiet
+	end
+
+	def puts(*args)
+		super unless @quiet
+	end
+
+	def run
+		times = {}
+		%w[create_test_table selecting_floats selecting_datetimes].each do |name|
+			t = Time.now
+			puts "* #{name.tr('_', ' ').capitalize}"
+			send name
+			took = Time.now - t
+			puts "  (took #{took} seconds)"
+			puts
+			times[name] = took
+		end
+		times
+	ensure
+		db.do 'drop table data'
+	end
+
+	def create_test_table
+		db.do <<-end
+			create table data (
+				date timestamp,
+				value float
+			)
+		end
+		db.do 'begin'
+		today = Date.today
+		5_000.times do
+			db.do "insert into data values ('#{today + rand(100) - 50}', #{10 + rand * 30})"
+		end
+		db.do 'commit'
+	end
+
+	def selecting_floats
+		strs = db.select_all('select value from data').map { |v| v.to_s }
+		puts *strs[0, 5]
+		puts '...'
+	end
+
+	def selecting_datetimes
+		strs = db.select_all('select date from data').map { |v| v.to_s }
+		puts *strs[0, 5]
+		puts '...'
+	end
+end
+
+def bench
+	dbiurls = [
+		'DBI:Mysql:dbitest:localhost',
+		'DBI:ODBC:MYDBITEST',
+	  'DBI:Pg:dbitest:localhost',
+		'DBI:ODBC:PGDBITEST',
+	]
+	order = %w[create_test_table selecting_floats selecting_datetimes]
+	dbiurls.map do |url|
+	  # assume all dbs have the same credentials
+		DBI.connect(url, *ARGV) do |db|
+			[url.first.sub('DBI:', ''), *DbiBenchmark.new(db, true).run.values_at(*order)]
+		end
+	end
+end
+
+puts 'Running benchmark:'
+DBI::Utils::TableFormatter.ascii(%w[db insert float datetime], bench, nil, nil, nil, nil, 30)
+

data/build/rake_task_lib.rb

@@ -0,0 +1,186 @@
+$:.unshift 'lib'
+require 'rake'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rake/packagetask'
+require 'rdoc/task'
+
+
+DEFAULT_TASKS = [:clobber_package, :package, :gem]
+
+DBD_GEM_DEP_MAP = {
+    'pg'      => 'pg',
+    'mysql'   => 'mysql',
+    'sqlite'  => 'sqlite-ruby',
+    'sqlite3' => 'sqlite3-ruby'
+}
+
+#
+# Packaging
+#
+
+PACKAGE_FILES = %w(Rakefile build/rake_task_lib.rb setup.rb)
+DOC_FILES  = %w(readme.md LICENSE ChangeLog)
+EXCLUSIONS = %w(test/sql.log)
+DBD_FILES  = %w(test/DBD_TESTS)
+
+#
+# some inlines
+#
+
+def gem_files(code_files)
+    (code_files + DOC_FILES).collect { |x| Dir[x] }.reject { |x| EXCLUSIONS.include? x }.flatten
+end
+
+def package_files(code_files)
+    code_files + DOC_FILES + PACKAGE_FILES
+end
+
+def build_package_tasks(spec, code_files)
+    Gem::PackageTask.new(spec) do |s|
+    end
+
+    Rake::PackageTask.new('y'+spec.name, spec.version) do |p|
+        p.need_tar_gz = true
+        p.need_zip = true
+
+        package_files(code_files).each do |x|
+            p.package_files.include(x)
+        end
+
+        EXCLUSIONS.each do |x|
+            p.package_files.exclude(x)
+        end
+    end
+end
+
+def boilerplate_spec
+    gem = Gem::Specification.new
+    gem.authors     = ['Erik Hollensbe', 'Christopher Maujean']
+    gem.email       = 'zdavatz@ywesee.com'
+    gem.homepage    = 'https://github.com/zdavatz/ydbi'
+    gem.platform    = Gem::Platform::RUBY
+    gem.extra_rdoc_files = DOC_FILES
+    gem.required_ruby_version = '>= 1.8.0'
+    gem.rubyforge_project = 'ydbi'
+    return gem
+end
+
+# builds a dbd namespace from the DBD_PACKAGES hash
+def dbd_namespace(dbd)
+    "ydbd-" + dbd.to_s.downcase
+end
+
+def dbd_code_files(dbd)
+    code_files = [
+                "test/dbd/general/**",
+                File.join("test", "dbd", dbd.downcase == "pg" ? "postgresql" : dbd.downcase, "*"),
+                File.join("lib", "dbd", dbd + ".rb"),
+                "lib/dbd/#{dbd.downcase}/*.rb",
+    ] + DBD_FILES
+end
+
+def dbd_gem_files(code_files)
+    DBD_FILES + gem_files(code_files)
+end
+
+def dbd_package_files(code_files)
+    DBD_FILES + package_files(code_files)
+end
+
+def dbd_gem_spec(dbd, dbd_const, code_files)
+    spec = boilerplate_spec
+    spec.name        = dbd_namespace(dbd)
+    spec.version     = dbd_version(dbd_const)
+    spec.test_file   = 'test/ts_dbd.rb'
+    spec.files       = gem_files(code_files)
+    spec.summary     = dbd_description(dbd_const)
+    spec.description = dbd_description(dbd_const)
+    spec.add_dependency 'ydbi', DBI::VERSION
+
+    dcdbd = dbd.downcase
+
+    if DBD_GEM_DEP_MAP[dcdbd]
+        spec.add_dependency DBD_GEM_DEP_MAP[dcdbd]
+    end
+
+    return spec
+end
+
+def dbd_version(const)
+    DBI::DBD.const_get(const).const_get("VERSION")
+end
+
+def dbd_description(const)
+    DBI::DBD.const_get(const).const_get("DESCRIPTION")
+end
+
+
+def build_dbd_tasks(dbd)
+    task :default => DEFAULT_TASKS
+
+    begin
+        done = false
+        dbd_const = nil
+        Dir["lib/dbd/*.rb"].each do |dbd_file|
+            if File.basename(dbd_file.downcase, '.rb') == dbd.to_s.downcase
+                dbd_const = File.basename(dbd_file, '.rb')
+                require "dbd/#{dbd_const}"
+                done = true
+            end
+        end
+
+        abort "No DBD found even though we asked to make tasks for it" unless done
+
+        code_files = dbd_code_files(dbd_const)
+
+        spec = dbd_gem_spec(dbd, dbd_const, code_files)
+
+        build_package_tasks(spec, code_files)
+
+        # FIXME: convert to a rake_test_loader sooner or later
+        task :test do
+            ENV["DBTYPES"] = dbd
+            ruby "test/ts_dbd.rb"
+        end
+    rescue LoadError => e
+        DEFAULT_TASKS.each do |x|
+            task x do
+            end
+        end
+        warn "Skipping #{dbd_namespace(dbd)} because we can't require DBD"
+    end
+end
+
+def build_dbi_tasks
+end
+
+#
+# basic tasks
+#
+
+task :dist      => [:distclean, :package, :rdoc]
+task :distclean => [:clobber_package, :clobber_rdoc]
+task :clean     => [:distclean]
+task :default   => [:test, :dist]
+
+task :to_blog   => [:clobber_rdoc, :rdoc] do
+    sh "rm -r $git/blog/content/docs/ruby-dbi && mv rdoc $git/blog/content/docs/ruby-dbi"
+end
+
+#
+# Documentation
+#
+
+RDoc::Task.new do |rd|
+    rd.rdoc_dir = "rdoc"
+    rd.main = "readme.md"
+    rd.rdoc_files.include("./readme.md")
+    rd.rdoc_files.include("./ChangeLog")
+    rd.rdoc_files.include("./LICENSE")
+    rd.rdoc_files.include("./doc/**/*.rdoc")
+    rd.rdoc_files.include("./lib/**/*.rb")
+    rd.rdoc_files.include("./ext/**/*.c")
+    rd.options = %w(-a)
+end
+

data/doc/DBD_SPEC.rdoc

@@ -0,0 +1,88 @@
+= 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

@@ -0,0 +1,157 @@
+= 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.