Module: DBI

Defined in:
lib/dbi.rb,
lib/dbi.rb,
lib/dbi/row.rb,
lib/dbi/sql.rb,
lib/dbd/mssql.rb,
lib/dbi/trace.rb,
lib/dbi/types.rb,
lib/dbi/utils.rb,
lib/dbi/binary.rb,
lib/dbi/handles.rb,
lib/dbi/typeutil.rb,
lib/dbi/columninfo.rb,
lib/dbi/exceptions.rb,
lib/dbi/utils/date.rb,
lib/dbi/utils/time.rb,
lib/dbd/mssql/driver.rb,
lib/dbi/base_classes.rb,
lib/dbd/mssql/database.rb,
lib/dbi/handles/driver.rb,
lib/dbd/mssql/statement.rb,
lib/dbi/utils/timestamp.rb,
lib/dbi/handles/database.rb,
lib/dbi/handles/statement.rb,
lib/dbi/sql_type_constants.rb,
lib/dbi/utils/xmlformatter.rb,
lib/dbi/base_classes/driver.rb,
lib/dbi/utils/tableformatter.rb,
lib/dbi/base_classes/database.rb,
lib/dbi/sql/preparedstatement.rb,
lib/dbi/base_classes/statement.rb

Overview

– Fallback classes for default behavior of DBD driver must be inherited by the DBD driver classes ++

Defined Under Namespace

Modules: DBD, SQL, Type, Utils Classes: Base, BaseDatabase, BaseDriver, BaseStatement, Binary, ColumnInfo, DataError, DatabaseError, DatabaseHandle, Date, DriverHandle, Error, Handle, HandleTracer, IntegrityError, InterfaceError, InternalError, NotImplementedError, NotSupportedError, OperationalError, ProgrammingError, Row, StatementHandle, Time, Timestamp, TypeUtil, Warning

Constant Summary collapse

VERSION = 
"0.4.1"
DEFAULT_TRACE_MODE =

Module functions (of DBI)

2
DEFAULT_TRACE_OUTPUT = 
STDERR
SQL_FETCH_NEXT =

Constants for fetch_scroll

1
SQL_FETCH_PRIOR = 
2
SQL_FETCH_FIRST = 
3
SQL_FETCH_LAST = 
4
SQL_FETCH_ABSOLUTE = 
5
SQL_FETCH_RELATIVE = 
6
SQL_CHAR =

SQL type constants

1
SQL_NUMERIC = 
2
SQL_DECIMAL = 
3
SQL_INTEGER = 
4
SQL_SMALLINT = 
5
SQL_FLOAT = 
6
SQL_REAL = 
7
SQL_DOUBLE = 
8
SQL_DATE =

91

9
SQL_TIME =

92

10
SQL_TIMESTAMP =

93

11
SQL_VARCHAR = 
12
SQL_BOOLEAN = 
13
SQL_LONGVARCHAR = 
-1
SQL_BINARY = 
-2
SQL_VARBINARY = 
-3
SQL_LONGVARBINARY = 
-4
SQL_BIGINT = 
-5
SQL_TINYINT = 
-6
SQL_BIT = 
-7
SQL_BLOB =

TODO Find types for these (XOPEN?) SQL_ARRAY =

-10   # TODO
SQL_CLOB =

TODO

-11   # TODO
#SQL_DISTINCT = 
#SQL_OBJECT = 
#SQL_NULL =
SQL_OTHER =

SQL_DISTINCT = SQL_OBJECT = SQL_NULL =

100
SQL_TYPE_NAMES =

SQL_REF = SQL_STRUCT =

{
    SQL_BIT               => 'BIT',
    SQL_TINYINT           => 'TINYINT',
    SQL_SMALLINT          => 'SMALLINT',
    SQL_INTEGER           => 'INTEGER',
    SQL_BIGINT            => 'BIGINT',
    SQL_FLOAT             => 'FLOAT',
    SQL_REAL              => 'REAL',
    SQL_DOUBLE            => 'DOUBLE',
    SQL_NUMERIC           => 'NUMERIC',
    SQL_DECIMAL           => 'DECIMAL',
    SQL_CHAR              => 'CHAR',
    SQL_VARCHAR           => 'VARCHAR',
    SQL_LONGVARCHAR       => 'LONG VARCHAR',
    SQL_DATE              => 'DATE',
    SQL_TIME              => 'TIME',
    SQL_TIMESTAMP         => 'TIMESTAMP',
    SQL_BINARY            => 'BINARY',
    SQL_VARBINARY         => 'VARBINARY',
    SQL_LONGVARBINARY     => 'LONG VARBINARY',
    SQL_BLOB              => 'BLOB',
    SQL_CLOB              => 'CLOB',
    SQL_OTHER             => nil,
    SQL_BOOLEAN           => 'BOOLEAN',

}
PROVIDERS = 
{
  :odbc => "System.Data.Odbc",
  :oledb => "System.Data.OleDb",
  :oracle => "System.Data.OracleClient",
  :mssql => "System.Data.SqlClient",
  :sqlce => "System.Data.SqlServerCe.3.5",
  :mysql => "MySql.Data.MySqlClient",
  :sqlite => "System.Data.SQLite",
  :postgresql => "Npgsql"
}
@@driver_map =

TODO: Is using class variables within a module such a wise idea? - Dan B.

Hash.new
@@driver_monitor = 
::Monitor.new()
@@trace_mode = 
DEFAULT_TRACE_MODE
@@trace_output = 
DEFAULT_TRACE_OUTPUT
@@caseless_driver_name_map = 
nil
@@convert_types = 
true
@@tracer_driver = 
HandleTracer.new(DBI::DriverHandle)
@@tracer_database = 
HandleTracer.new(DBI::DatabaseHandle)
@@tracer_statement = 
HandleTracer.new(DBI::StatementHandle)

Class Method Summary collapse

Class Method Details

._get_full_driver(driver_url) ⇒ Object

Extracts the db_args from driver_url and returns the correspondeing entry of the @@driver_map.



152
153
154
155
156
157
 
# File 'lib/dbi.rb', line 152

def _get_full_driver(driver_url) #:nodoc:
    db_driver, db_args = parse_url(driver_url)
    db_driver = load_driver(db_driver)
    dr = @@driver_map[db_driver]
    [dr, db_args]
end

.available_drivers ⇒ Object

Returns a list (of String) of the currently available drivers on your system in ‘dbi:driver:’ format.

This currently does not work for rubygems installations, please see DBI.collect_drivers for reasons.



197
198
199
200
201
202
203
 
# File 'lib/dbi.rb', line 197

def available_drivers
    drivers = []
    collect_drivers.each do |key, value|
        drivers.push("dbi:#{key}:")
    end 
    return drivers
end

.collect_drivers ⇒ Object

Return a list (of String) of the available drivers.

NOTE

This is non-functional for gem installations, due to the nature of how it currently works. A better solution for this will be provided in DBI 0.6.0.



178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/dbi.rb', line 178

def collect_drivers
    drivers = { }
    # FIXME rewrite this to leverage require and be more intelligent
    path = File.join(File.dirname(__FILE__), "dbd", "*.rb")
    Dir[path].each do |f|
        if File.file?(f)
            driver = File.basename(f, ".rb")
            drivers[driver] = f
        end
    end

    return drivers
end

.connect(driver_url, user = nil, auth = nil, params = nil, &p) ⇒ Object

Establish a database connection.

Format goes as such: “dbi:Driver:database_conn_args”

  • “dbi” is the literal string “dbi”. Case is unimportant.

  • “Driver” is the case-dependent name of your database driver class. The file “dbd/#Driver” will be required. If you are using rubygems to control your DBDs and DBI, you must make the gem’s file path available via the “gem” command before this will work.

  • database_conn_args can be:

    • The database name.

    • A more complex key/value association (to indicate host, etc). This is driver dependent; you should consult your DBD documentation.



138
139
140
141
142
143
 
# File 'lib/dbi.rb', line 138

def connect(driver_url, user=nil, auth=nil, params=nil, &p)
    dr, db_args = _get_full_driver(driver_url)
    dh = dr[0] # driver-handle
    dh.convert_types = @@convert_types
    dh.connect(db_args, user, auth, params, &p)
end

.convert_types ⇒ Object

Return the current status of type conversion at this level. This status will be propogated to any new DatabaseHandles created.



113
114
115
 
# File 'lib/dbi.rb', line 113

def self.convert_types
    @@convert_types
end

.convert_types=(bool) ⇒ Object

Set the current status of type conversion at this level. This status will be propogated to any new DatabaseHandles created.



119
120
121
 
# File 'lib/dbi.rb', line 119

def self.convert_types=(bool)
    @@convert_types = bool
end

.data_sources(driver) ⇒ Object

Attempt to collect the available data sources to the driver, specified in DBI.connect format.

The result is heavily dependent on the driver’s ability to enumerate these sources, and results will vary.



210
211
212
213
214
215
 
# File 'lib/dbi.rb', line 210

def data_sources(driver)
    db_driver, = parse_url(driver)
    db_driver = load_driver(db_driver)
    dh = @@driver_map[db_driver][0]
    dh.data_sources
end

.disconnect_all(driver = nil) ⇒ Object

Attempt to disconnect all database handles. If a driver is provided, disconnections will happen under that scope. Otherwise, all loaded drivers (and their handles) will be attempted.



222
223
224
225
226
227
228
229
 
# File 'lib/dbi.rb', line 222

def disconnect_all( driver = nil )
    if driver.nil?
        @@driver_map.each {|k,v| v[0].disconnect_all}
    else
        db_driver, = parse_url(driver)
        @@driver_map[db_driver][0].disconnect_all
    end
end

.get_driver(driver_url) ⇒ Object

Load a DBD and returns the DriverHandle object



146
147
148
 
# File 'lib/dbi.rb', line 146

def get_driver(driver_url) #:nodoc:
    _get_full_driver(driver_url)[0][0]  # return DriverHandle
end

.trace(mode = nil, output = nil) ⇒ Object

Enable tracing mode. Requires that ‘dbi/trace’ be required before it does anything.

As of 0.4.0, this mode does not do anything either way, so this currently just throws an InterfaceError. This issue is expected to be resolved in the next release.

Raises:



165
166
167
168
169
170
 
# File 'lib/dbi.rb', line 165

def trace(mode=nil, output=nil)
    # FIXME trace
    raise InterfaceError, "the trace module has been removed until it actually works."
    @@trace_mode   = mode   || @@trace_mode   || DBI::DEFAULT_TRACE_MODE
    @@trace_output = output || @@trace_output || DBI::DEFAULT_TRACE_OUTPUT
end