Module: RDBI::Type

Defined in:
lib/rdbi/types.rb

Overview

RDBI::Type – manage types going to and coming from your database.

RDBI::Type consists of:

  • Checks and Conversions (facilitated by TypeLib) for ruby -> database and database -> ruby

  • Mappings for Input (Ruby -> DB) and Output (DB -> Ruby) conversions based on type.

  • Convenience methods for TypeLib and creating new mappings.

How does it all work?

RDBI::Type leverages TypeLib which is a filter chaining system, one which you’ll wish to read the documentation for to understand some of the concepts here.

A conversion follows these steps:

  • Metadata on the type (more below) is located and used to reference a TypeLib::FilterList which contains the TypeLib::Filters (which in turn consist of a Check and Conversion proc) which will process your data.

  • Data is passed to the FilterList and it is executed, following each filter in turn and following any conversion passing checks request. This may very well mean that no checks pass and therefore your original data is returned.

  • After processing, the data is yielded back to you for further processing (or a subsystem such as RDBI::Result#fetch and result drivers that take advantage of said data)

How is metadata located?

It’s important first to briefly describe how RDBI terms database I/O:

  • Binds going to the database proper are called ‘input’.

  • Data coming from the database is called ‘output’.

Mappings are keyed by type metadata and thusly are typed as:

  • Input types are the native class of the type.

  • Output types are a symbol that represents the database type. These type names are provided by RDBI::Column via RDBI::Schema in the response from an execution. See RDBI::Statement#new_execution and RDBI::Column#ruby_type.

Note that in the latter case these database types are effectively normalized, e.g., ‘timestamp with timezone’ in postgres is just :timestamp. You will want to read the mappings in the source to get a full listing of what’s supported by default.

Each map will also contain :default, which is what is used when a proper lookup fails, as a fallback.

Ok, so how do I use these maps?

RDBI::Type.create_type_hash is a helper to duplicate the default maps and return them. If you don’t wish to use the default maps at all, just a plain old Hash following the semantics above will work.

To perform conversions, look at RDBI::Type::In::convert and RDBI::Type::Out::convert.

Defined Under Namespace

Modules: Checks, Conversions, Filters, In, Out

Constant Summary collapse

DEFAULT_STRFTIME_FILTER =

A filter format to assist the conversions of DateTime objects.

"%Y-%m-%d %H:%M:%S %z"

Class Method Summary collapse

Class Method Details

.create_type_hash(klass) ⇒ Object

Shorthand to duplicate the DEFAULTS hash from a module. Most frequently used to get a copy of the RDBI::Type::In and RDBI::Type::Out type maps.



125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/rdbi/types.rb', line 125

def self.create_type_hash(klass)
  hash = { }
  orig = klass::DEFAULTS
  orig.keys.each do |key|
    flist = filterlist()
    orig[key].each do |filter|
      flist << filter
    end
    hash[key] = flist
  end

  return hash
end

.filterlist(*ary) ⇒ Object

Shorthand for creating a new TypeLib::FilterList.



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

def self.filterlist(*ary)
  [Filters::NULL, *ary]
end