ruby-oci8 2.2.0.2 → 2.2.12

data/docs/ldap-auth-and-function-interposition.md

@@ -0,0 +1,123 @@
+# @title LDAP Authentication and Function Interposition
+
+LDAP Authentication and Function Interposition
+==============================================
+
+Problems
+--------
+
+The following code may trigger segmentation faults or unexpected behaviours.
+
+    require 'pg' # or any modules using LDAP such as ActiveLdap
+    require 'oci8'
+    
+    conn = OCI8.new('username/password@dbname.example.com')
+    ...
+
+It happens when all the following conditions are satisfied.
+
+* The platform is Unix
+* The PostgreSQL client library, which `pg` depends, was compiled with LDAP support.
+* LDAP authentication is used to connect to an Oracle server.
+
+It is caused by function interposition as follows:
+
+* The ruby process loads `pq` and its depending libraries such as
+  `libpq.so`(PostgreSQL client library) and `libldap_r.so`(LDAP library).
+* Then it loads `oci8` and its depending libraries such as
+  `libclntsh.so`(Oracle client library).
+* When LDAP authentication is used, `libclntsh.so` tries to use
+  LDAP functions in the library.
+* However it uses LDAP functions in `libldap_r.so` because the function
+  in the firstly loaded library is used when more than one library exports
+  functions whose names are same.
+* It triggers segmentation faults or unexpected behaviours because
+  implementations of LDAP functions are different even though their names
+  are same.
+
+The reverse may cause same results by the following code.
+
+    require 'oci8'
+    require 'pg'
+    
+    ... connect to PostgreSQL using LDAP ...
+
+### Note for macOS
+
+Libraries in two-level namespaces are free from function interposition on macOS.
+See the second paragraph of [this document][mach-o]. If `TWOLEVEL` is
+found in the output of `otool -hV /path/to/library`, it is in a
+two-level namespace. Otherwise it is in a single-level (flat) namespace.
+
+Oracle client library (`libclntsh.dylib.12.1`) is in a flat namespace.
+It suffers from function interposition.
+
+    $ otool -hV libclntsh.dylib.12.1
+    Mach header
+          magic cputype cpusubtype  caps    filetype ncmds sizeofcmds      flags
+    MH_MAGIC_64  X86_64        ALL  0x00       DYLIB    19       2360 DYLDLINK NO_REEXPORTED_DYLIBS MH_HAS_TLV_DESCRIPTORS
+
+PostgreSQL client library (`libpq.5.dylib`) installed by [brew][] depends on an OS-supplied LDAP library.
+
+    $ otool -L libpq.5.dylib 
+    libpq.5.dylib:
+        /usr/local/opt/postgresql/lib/libpq.5.dylib (compatibility version 5.0.0, current version 5.9.0)
+        /usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+        /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+        /System/Library/Frameworks/Kerberos.framework/Versions/A/Kerberos (compatibility version 5.0.0, current version 6.0.0)
+        /System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0)
+        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1238.0.0)
+
+The OS-supplied LDAP library is in a two-level namespace.
+
+    $ otool -hV /System/Library/Frameworks/LDAP.framework/Versions/A/LDAP
+    Mach header
+          magic cputype cpusubtype  caps    filetype ncmds sizeofcmds      flags
+    MH_MAGIC_64  X86_64        ALL  0x00       DYLIB    22       2528   NOUNDEFS DYLDLINK TWOLEVEL NO_REEXPORTED_DYLIBS APP_EXTENSION_SAFE
+
+As a result, the PostgreSQL client library is free from function interposition.
+
+Solution 1
+----------
+
+If you don't connect to PostgreSQL using LDAP, use the following code.
+
+    require 'oci8'  # This must be before "require 'pg'".
+    require 'pg'
+    
+    conn = OCI8.new('username/password@dbname.example.com')
+    ...
+    ... connect to a PostgreSQL server ...
+
+Oracle client library uses LDAP functions in `libclntsh.so` because `libclntsh.so`
+is loaded before `libldap_r.so`.
+
+Don't connect to PostgreSQL using LDAP because `libpq.so` tries to use
+LDAP functions in `libldap_r.so` but faultily uses functions in `libclntsh.so`.
+
+Note for macOS: This fixes all function interposition issues if the LDAP library
+in a two-level namespace.
+
+Solution 2
+----------
+
+If LDAP is used to connect to both Oracle and PostgreSQL and the platform
+is Linux or macOS, use ruby-oci8 2.2.4 or later and use the following code.
+
+    require 'pg'
+    require 'oci8' # This must be after "require 'pg'".
+    
+    conn = OCI8.new('username/password@dbname.example.com')
+    ...
+    ... connect to a PostgreSQL server using LDAP ...
+
+PostgreSQL client library uses LDAP functions in `libldap_r.so` because `libldap_r.so`
+is loaded before `libclntsh.so`.
+
+Oracle client library uses LDAP functions in `libclntsh.so` because ruby-oci8
+forcedly modifies PLT (Procedure Linkage Table) entries to point to
+functions in `libclntsh.so` if they point to functions in other libraries.
+(PLT is equivalent to IAT (Import Address Table) on Windows.)
+
+[mach-o]: https://developer.apple.com/library/content/documentation/DeveloperTools/Conceptual/MachOTopics/1-Articles/executing_files.html
+[brew]: http://brew.sh/

data/docs/number-type-mapping.md

@@ -0,0 +1,79 @@
+# @title Number Type Mapping between Oracle and Ruby
+
+Number Type Mapping between Oracle and Ruby
+===========================================
+
+Default mapping
+---------------
+
+Oracle numbers in select statements are fetched as followings by default:
+
+| Oracle Data Type | Ruby Class |
+|---|---|
+| NUMBER(prec) or NUMBER(prec, 0) | Integer |
+| NUMBER(prec, scale) where prec < 15 and scale != 0 | Float |
+| NUMBER(prec, scale) where prec >= 15 and scale != 0 | BigDecimal |
+| FLOAT or FLOAT(prec) | Float |
+| NUMBER without precision and scale | BigDecimal |
+| number type returned by functions or calculated number | BigDecimal |
+| BINARY_FLOAT | Float |
+| BINARY_DOUBLE | Float |
+
+When the data type is within Integer or Float class, it is fetched
+as Integer or Float. Otherwise, BigDecimal.
+
+Note that the mapping is determined by the column definition in
+select statements, not by the actual value fetched.
+For example the column in `select count(*) from table_name` is
+fetched as BigDecimal because it is returned from `count` function.
+
+The mapping is customizable by `OCI8::BindType::Mapping`.
+The default values of Oracle number data type mapping are:
+
+    # NUMBER or FLOAT data type, used for the first six rows in the above table
+    OCI8::BindType::Mapping[:number] = OCI8::BindType::Number
+    # BINARY_FLOAT data type, used for the seventh row in the above table
+    OCI8::BindType::Mapping[:binary_float] = OCI8::BindType::BinaryDouble
+    # BINARY_DOUBLE data type, used for the eighth row in the above table
+    OCI8::BindType::Mapping[:binary_double] = OCI8::BindType::BinaryDouble
+
+`OCI8::BindType::Number` checks precision and scale to determine
+ruby class. The first four rows in the above table are hard-coded.
+The fifth and sixth rows are, however, customizable by
+`OCI8::BindType::Mapping[:number_no_prec_setting]` and
+`OCI8::BindType::Mapping[:number_unknown_prec]` respectively.
+
+The default values are:
+
+    OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::BigDecimal
+    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::BigDecimal
+
+The mapping may be changed as follows in future.
+
+| Oracle Data Type | Ruby Class |
+|---|---|
+| NUMBER(prec) or NUMBER(prec, 0) | Integer |
+| other NUMBER  | OraNumber |
+| BINARY_FLOAT | Float |
+| BINARY_DOUBLE | Float |
+
+Customize mapping
+-----------------
+
+Add the following code to fetch all number or float columns as {OraNumber}.
+
+    OCI8::BindType::Mapping[:number] = OCI8::BindType::OraNumber
+
+Otherwise, add the following code to customize the fifth and sixth rows only
+in the above table.
+
+    OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::OraNumber
+    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::OraNumber
+
+If you want to fetch numbers as Integer or Float by its actual value, use
+the following code:
+
+    # Fetch numbers as Integer when their fractional part is zero.
+    # Otherwise, Float. For example when a column contains 10 and
+    # 10.1, they are fetched as Integer and Float respectively.
+    OCI8::BindType::Mapping[:number] = OCI8::BindType::BasicNumberType

data/docs/platform-specific-issues.md

@@ -1,10 +1,12 @@
 # @title Platform Specific Issues
 
+Platform Specific Issues
+========================
+
 Linux
-=====
+-----
 
-Ubuntu 11.10 (Oneiric Ocelot)
------------------------------
+### Ubuntu 11.10 (Oneiric Ocelot)
 
 If the following error occurs even though libc6-dev is installed,
 
@@ -15,8 +17,7 @@ You need to use ruby-oci8 2.1.0 or upper. Otherwise, run the following command a
 
     $ sudo ln -s /usr/include/linux/ /usr/include/sys
 
-General Linux
--------------
+### General Linux
 
 Use the same bit-width of libraries with ruby. For example, x86\_64
 instant client for x86\_64 ruby and 32-bit instant client for 32-bit
@@ -32,21 +33,18 @@ To check which type of ruby do you use:
 Note: "`" is a back quote.
 
 Mac OS X
-========
+--------
 
-OS X 10.7+
-----------
+### OS X 10.7+
 
 Use the latest 64-bit instant client. The older 64-bit (10.2.0.4) instant client [doesn't work](https://forums.oracle.com/forums/thread.jspa?threadID=2187558). The older 32-bit instant client will work but only with 32-bit ruby or jruby (using JDBC).
 
-Intel Mac (64-bit)
-------------------
+### Intel Mac (64-bit)
 
 See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/).
 Note that setting the environment variable RC\_ARCHS=x86\_64 instead of ARCHFLAGS="-arch x86\_64" will work fine also.
 
-Intel Mac (32-bit)
-------------------
+### Intel Mac (32-bit)
 
 See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/). Note that you need to replace x86\_64 with i386 in the blog.
 
@@ -57,13 +55,12 @@ use one of the following workarounds.
 * use [ruby-odbc](http://www.ch-werner.de/rubyodbc/) and a third party ODBC driver ([Actual Technologies](http://www.actualtechnologies.com) or [OpenLink Software](http://uda.openlinksw.com/)).
 * use JRuby and Oracle JDBC driver.
 
-PowerPC Mac
------------
+### PowerPC Mac
 
 See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/). Note that you need to replace x86\_64 with ppc in the blog.
 
 Solaris
-=======
+-------
 
 You need a same compiler which is used to make ruby itself.
 For example, if the ruby is compiled by gcc, you need gcc. If it is compiled by Oracle Solaris Studio
@@ -83,15 +80,10 @@ as follows:
     to:   CONFIG["LDFLAGS"] = "-L. "
 
 FreeBSD
-=======
-
-There are two ways.
+-------
 
-* use ruby and instant client on linux emulator
-* use oracle8-client port
-
-linux emulator
---------------
+Oracle8-client port isn't available because it is too old.
+You need to use linux emulator.
 
 I have not run ruby-oci8 on linux emulator, but I guess it will
 run as follows. If it works, please tell me.
@@ -129,33 +121,8 @@ On freebsd:
     cd /compat/linux/usr/local
     tar xvfz ruby-1.8.x-linux.tar.gz
 
-oracle8-client port
--------------------
-
-I don't recommend this because of the following two reasons.
-
-* The oracle8-client port is made from Oracle 8.1.7.1 static library for Linux. Oracle have not supported the connectivity between 8.1.7.1 and Oracle 10g.
-* It is very unstable. When it fails to connect to an Oracle server, it is down by segmentation fault on FreeBSD 7.0 not only when using ruby-oci8, but also by a very simple test code written by C.
-
-If you try to use oracle8-client port, compile and install as follows.
-
-* install oracle8-client
-
-    cd /usr/ports/databases/oracle8-client
-    make
-    make install
-
-* set an environment variable ORACLE\_HOME
-
-    export ORACLE_HOME=/usr/local/oracle8-client
-
-The rest steps are described at {file:docs/install-full-client.md}.
-
-note: You have no need to set LD\_LIBRARY\_PATH because 
-Oracle libraries in oracle8-client port are static ones.
-
 HP-UX
-=====
+-----
 
 You need a ruby which is linked with ''libpthread'' and ''libcl''.
 
@@ -174,7 +141,7 @@ and `make install`.
 The rest steps are described at {file:docs/install-full-client.md}.
 
 Windows
-=======
+-------
 
 On some machines using a slow disk, you may get the following error.
 

data/docs/report-installation-issue.md

@@ -1,5 +1,8 @@
 # @title Report Installation Issues
 
+Report Installation Issues
+==========================
+
 Look at {file:docs/platform-specific-issues.md} and [the issues page on github][github] to check whether your issue is fixed or not.
 
 If it is a new one, post the following information to [github][].
@@ -20,14 +23,14 @@ If it is a new one, post the following information to [github][].
 
          file `which ruby`
          ruby --version
-         ruby -r rbconfig -e "p Config::CONFIG['host']"
-         ruby -r rbconfig -e "p Config::CONFIG['CC']"
-         ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
-         ruby -r rbconfig -e "p Config::CONFIG['LDSHARED']"
-         ruby -r rbconfig -e "p Config::CONFIG['LDFLAGS']"
-         ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
-         ruby -r rbconfig -e "p Config::CONFIG['LIBS']"
-         ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['host']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['CC']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['CFLAGS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['LDSHARED']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['LDFLAGS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['DLDLAGS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['LIBS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['GNU_LD']"
          
          # if you use gcc,
          gcc --print-prog-name=ld

data/docs/timeout-parameters.md

@@ -0,0 +1,94 @@
+# @title Timeout Parameters
+
+Timeout Parameters
+==================
+
+The following timeout parameters are available since ruby-oci8 2.2.2.
+
+* tcp_connect_timeout
+* connect_timeout
+* send_timeout
+* recv_timeout
+
+For example:
+
+    OCI8.properties[:tcp_connect_timeout] = 10
+    OCI8.properties[:connect_timeout] = 15
+    OCI8.properties[:send_timeout] = 60
+    OCI8.properties[:recv_timeout] = 60
+
+These parameters are applied only to TCP/IP connections.
+
+The first two parameters `tcp_connect_timeout` and `connect_timeout`
+are applied only to [connect descriptors][connect descriptor] using [Easy Connect Naming Method][EZCONNECT].
+If you use a net service name, you should set [TRANSPORT_CONNECT_TIMEOUT][] and/or
+[CONNECT_TIMEOUT][] in the address descriptor in `tnsnames.ora` instead of these parameters.
+If you use easy connect naming method without any of `port`, `service_name`, `server` and `instance_name`,
+you need to use `//host` to distinguish it from a net service name.
+
+The next two parameters `send_timeout` and `recv_timeout` are available on Oracle 11g client
+or upper. Use these parameters to prevent a ruby process from being blocked by poor quality network.
+Otherwise, the ruby process may be blocked until TCP keepalive time (2 hours).
+
+See {file:docs/hanging-after-inactivity.md Hanging After a Long Period of Inactivity}
+for TCP keepalive time.
+
+tcp_connect_timeout
+-------------------
+
+`tcp_connect_timeout` is equivalent to [TCP.CONNECT_TIMEOUT][] in the client-side `sqlnet.ora` and
+[TRANSPORT_CONNECT_TIMEOUT][] in the address descriptor.
+See description about [TCP.CONNECT_TIMEOUT][] and [TRANSPORT_CONNECT_TIMEOUT][].
+
+connect_timeout
+---------------
+
+`connect_timeout` is equivalent to [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] in the client-side `sqlnet.ora`
+and [CONNECT_TIMEOUT][] in the address description.
+See description about [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] and [CONNECT_TIMEOUT][].
+
+Note: this parameter isn't equivalent to login timeout. It needs the following three
+steps to establish a database connection.
+
+1. Establish a TCP/IP connection.
+2. Establish an [Oracle Net][] connection on the TCP/IP connection.
+3. Authenticate and authorize the database user.
+
+`tcp_connect_timeout` sets the timeout of the first step.
+`connect_timeout` sets the total timeout of the first and the second steps.
+There is no timeout parameter to limit the maximum time of all three steps.
+
+Use `send_timeout` and `recv_timeout` in case that a TCP/IP connection stalls
+in the third step.
+
+send_timeout
+------------
+
+`send_timeout` is equivalent to [SQLNET.SEND_TIMEOUT][] in the client-side `sqlnet.ora`.
+See description about [SQLNET.SEND_TIMEOUT][].
+
+Note that the connection becomes unusable on timeout.
+
+See also {OCI8#send_timeout=}.
+
+recv_timeout
+------------
+
+`recv_timeout` is equivalent to [SQLNET.RECV_TIMEOUT][] in the client-side `sqlnet.ora`.
+See description about [SQLNET.RECV_TIMEOUT][].
+
+Note that the connection becomes unusable on timeout.
+
+See also {OCI8#recv_timeout=}.
+
+Note: This parameter must be larger than the longest SQL execution time in your applications. 
+
+[TCP.CONNECT_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#BIIDDACA
+[SQLNET.OUTBOUND_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF427
+[SQLNET.SEND_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF228
+[SQLNET.RECV_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF227
+[connect descriptor]: https://docs.oracle.com/database/121/NETRF/glossary.htm#BGBEDFBF
+[EZCONNECT]: https://docs.oracle.com/database/121/NETAG/naming.htm#NETAG255
+[CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#NETRF666
+[TRANSPORT_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#NETRF1982
+[Oracle Net]: https://en.wikipedia.org/wiki/Oracle_Net_Services#Oracle_Net

data/ext/oci8/apiwrap.c.tmpl

@@ -4,7 +4,6 @@
 %>
 #define API_WRAP_C 1
 #include "apiwrap.h"
-#define BLOCKING_FUNCTION_EPILOGUE(svcctx) do { (svcctx)->executing_thread = Qnil; } while (0)
 
 <%
 prev_name = ''
@@ -59,11 +58,9 @@ static void *oci8_<%=f.name%>_cb(void *user_data)
 %>    data->rv = <%=f.name%>(<%= f.args.collect do |a| 'data->' + a.name; end.join(', ') %>);
 <% end %>
 <% if f.ret == 'sword'
-%>    BLOCKING_FUNCTION_EPILOGUE(data->svcctx);
-    return (void*)(VALUE)data->rv;
+%>    return (void*)(VALUE)data->rv;
 <% else
-%>    BLOCKING_FUNCTION_EPILOGUE(data->svcctx);
-    return NULL;
+%>    return NULL;
 <% end %>
 }
 #else

data/ext/oci8/apiwrap.rb

@@ -35,7 +35,11 @@ class FuncDef
     ver_major = (ver / 100)
     ver_minor = (ver / 10) % 10
     ver_update = ver % 10
-    @version = ((ver_major << 24) | (ver_minor << 20) | (ver_update << 12))
+    @version = if ver_major >= 18
+                 ((ver_major << 24) | (ver_minor << 16) | (ver_update << 12))
+               else
+                 ((ver_major << 24) | (ver_minor << 20) | (ver_update << 12))
+               end
     case @version
     when 0x08000000; @version_num = 'ORAVER_8_0'
     when 0x08100000; @version_num = 'ORAVER_8_1'
@@ -44,6 +48,7 @@ class FuncDef
     when 0x0a100000; @version_num = 'ORAVER_10_1'
     when 0x0a200000; @version_num = 'ORAVER_10_2'
     when 0x0b100000; @version_num = 'ORAVER_11_1'
+    when 0x12000000; @version_num = 'ORAVER_18'
     end
     @version_str = "#{ver_major}.#{ver_minor}.#{ver_update}"
     @ret = val[:ret] || 'sword'