New Features

Add OCI8::Metadata::Base#obj_link.

Fixed Issues


New Features

Support ruby 2.1.0

Support cygwin x86_64

OCI8#describe_synonym and OCI8#describe_any accept 'PUBLIC.XXX' as a public synonym name.

Fixed Issues


New Features


'rubyoci8' is set as the driver name, which is displayed in V$SESSION_CONNECT_INFO.CLIENT_DRIVER when both the client and the server are Oracle 11g or upper.

Fixed Issues


New Features

Fast Application Notification (FAN) support

Look at php.net/manual/en/oci8.connection.php} to know what is FAN. in PHP corresponds to {OCI8.properties OCI8.properties in ruby-oci8.

Note: You need to set OCI8.properties[:events_mode] after "require 'oci8'" and before any methods which call Oracle OCI functions.

Fixed Issues


New Features


It returns the text of the SQL statement prepared in the cursor.

cursor = conn.parse("select * from country where country_code = 'ja'")
cursor.statement # => "select * from country where country_code = 'ja'"

See: github issue #16

Specification changes

License was changed to 2-clause BSD-style license.

The former license was same with old ruby (<= 1.9.2) license.

Oracle object type's DATE field type

Ruby-oci8 had returned a DateTime object when Oracle object type's DATE field type was accessed. Now it returns a Time object.

Fixed Issues


Specification changes

Statement caching in OCI is disabled by default.

This is workaround about a SIGSEGV issue. See: oracle enhanced issue #162

Fixed Issues


New Features

Statement caching in OCI

See http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/oci09adv.htm#i471377. This feature is enabled only when the Oracle client is 9iR2 or upper.

The default cache size is 20. It can be changed as follows.

# change the size to 100.
OCI8.properties[:statement_cache_size] = 100

Note: The default size was changed to zero in 2.1.2.

Specification changes

OCI8::LOB#read() returns an empty string '' when it is an empty lob.

It had been returned nil.

Fixed Issues


New Features

OCI connection pooling

See: OCI8::ConnectionPool

Daylight saving time aware if TZ is set.

You should set the environment variable TZ if your applications run in a time zone with daylight saving time transitions. Otherwise, Oracle session time zone is set with current constant offset from GMT. (reported by Yasuo Honda)

connect as sysasm (Oracle 11g only)

You can connect to the Oracle server as SYSASM privilege as follows:

OCI8.new('username/password as sysasm')


OCI8.new('username', 'password', nil, :SYSASM)

Oracle number is converted to ruby float exactly same as ruby does.

From ruby 1.9.2, a float value converted from Oracle number 15.7 by the Oracle function OCINumberToReal() makes a string representation 15.700000000000001 by Float#to_s. (See: http://redmine.ruby-lang.org/issues/4656) To avoid this issue, any Oracle number is converted to a float as ruby's String#to_f does.

The behavior is customizable by OCI8.properties.

OCI8.properties[:float_conversion_type] = :oracle # => Use OCINumberToReal()
OCI8.properties[:float_conversion_type] = :ruby # => Use String#to_f

The default value is :ruby.

OCISuccessWithInfo exceptions are not raised any more.

Ruby-oci8 2.0 treats OCI_SUCCESS_WITH_INFO in OCI layer as an error and raise an exception OCISuccessWithInfo such as “ORA-24347: Warning of a NULL column in an aggregate function” and “ORA-28002: the password will expire within xx days.”

From 2.1.0, it is treated as a warning and the exception is set to OCI8#last_error.

OCI8#last_error is added.

The last error or warning associated with the session is set to OCI8#last_error. The usecase is to detect OCISuccessWithInfo. It is reset by OCI8#exec and OCI8#parse.

Experimental support of character length semantics

OCI8.properties indicates length semantics of OCI8::Cursor#bind_param. When it is :char, the length is counted by the number of characters. When it is :byte, it is counted by the number of bytes.

OCI8.client_charset_name and OCI8#database_charset_name are added.

They return Oracle charset name such as WE8ISO8859P15.

Specification changes

The parent class OCINoData was changed from OCIException to OCIError.

Oracle 8 and Oracie 8i is not supported anymore.

Fixed Issues


Fixed issues


New Features

Support Rubinius.

OraNumber#has_decimal_part? is added.


OraNumber(10).has_decimal_part?   # => false
OraNumber(10.1).has_decimal_part? # => true

Limitted support for OraNumber's positive and negative infinity.

They are converted to '~' and '-~' respectively as described in http://www.ixora.com.au/notes/infinity.htm.

OCI8.properties is added to control ruby-oci8 behaviour.

It supports :bind_string_as_nchar only for now.

OCI8.properties is added.

You need to set “OCI8.properties[:bind_string_as_nchar] = true” if the database character set is not UTF-8 and 'NCHAR'/'NVARCHAR2' columns contain characters which cannot be converted to the database character set.

See: http://rubyforge.org/forum/forum.php?thread_id=48838&forum_id=1078

Fixed issues


New Features

OCI8.error_message is added.

Gets the Oracle error message specified by message id. Its language depends on 'NLS_LANGUAGE'.

Note: This method is unavailable if the Oracle client version is 8.0.

# => "ORA-00001: unique constraint (%s.%s) violated"

# => "ORA-00001: violation de contrainte unique (%s.%s)"

OraNumber#dump is added.

Returns OraNumber's internal representation whose format is same with the return value of Oracle SQL function DUMP().

OraNumber.new(100).dump #=> "Typ=2 Len=2: 194,2"
OraNumber.new(123).dump #=> "Typ=2 Len=3: 194,2,24"
OraNumber.new(0.1).dump #=> "Typ=2 Len=2: 192,11"

Fixed issues


Incompatible Changes

Number column in a SQL statement

Changes the default data type for number column which fit neither Integer nor Float from OraNumber to BigDecimal.

conn.exec("select 1.0 from dual") do |row|
  p row[0] # => BigDecimal("1") if the ruby-oci8 version is 2.0.3.
           # => OraNumber(1) if the version is 2.0.2.

Priority of OraNumber within numerical types

The return types of basic arithmetic operations with other numerical types are changed.


OraNumber + Integer    => OraNumber  (OraNumber wins.)
OraNumber + Float      => Float      (OraNumber loses.)
OraNumber + Rational   => Rational   (OraNumber loses.)
OraNumber + BigDecimal => BigDecimal (OraNumber loses.)


OraNumber + Integer    => OraNumber  (OraNumber wins always.)
OraNumber + Float      => OraNumber
OraNumber + Rational   => OraNumber
OraNumber + BigDecimal => OraNumber

Interval day to second

The retrived value of Oracle data type “interval day to second” was changed from the number of days as a Rational to the number of seconds as a Float by default. Use 'OCI8::BindType::IntervalDS.unit = :day' to make it compatible with the previous versions.

conn.exec("select to_dsinterval('0 00:00:01') from dual") do |row|
  p row[0] # => 1.0 if the version is 2.0.3 and
           #    OCI8::BindType::IntervalDS.unit is :second.
           # => (1/86400) if the version is 2.0.3 and
           #    OCI8::BindType::IntervalDS.unit is :day or
           #    the version is 2.0.2.

Date, timestamp, timestamp with time zone data types and ruby 1.9.2

These data types are retrived always as Time values when the ruby version is 1.9.2 because the Time class is enhanced to represent any time zone and is free from year 2038 problem.

Prior to ruby 1.9.2, if the time cannot be represented by Unix time or the time zone is neither utc nor local, they are retrived as DateTime values.

Non-blocking mode and ruby 1.9

Non-blocking mode is enabled by default when the ruby is 1.9.

New Features

BigDecimal and Rational are availabe as bind values.

New methods OCI8#module=, OCI8#action= and OCI8#client_info= are added.

These methods change the module name, the action name and the client_info in the current session respectively.

After Oracle 10g client, these don't perform network round trips. The change is reflected to the server by the next round trip such as OCI8#exec, OCI8#ping, etc.

Prior to Oracle 10g client, these call PL/SQL functions such as DBMS_APPLICATION_INFO.SET_MODULE, DBMS_APPLICATION_INFO.SET_ACTION, and DBMS_APPLICATION_INFO.SET_CLIENT_INFO internally. The change is reflected immediately by a network round trip.


The default time zone of Time or DateTime values. This parameter is used only when

Note that if the Oracle client version is 9i or upper, the time zone is determined by the session time zone. The default value is local time zone. You can change it to GMT by executing the following SQL statement for each connection.

alter session set time_zone = '00:00'

Note: The session time zone is set by the environment variable TZ from ruby-oci8 2.1.0.

Other specification changes

Fixed installation issues