ruby-oci8 2.2.4.1 → 2.2.11

data/docs/install-on-osx.md

@@ -1,133 +1,46 @@
-# @title Install ruby-oci8 on OS X
+# @title Install ruby-oci8 on macOS
 
-Install ruby-oci8 on OS X
+Install ruby-oci8 on macOS
 =========================
 
-This page explains the way to install ruby-oci8 os OS X.
+**Note: Ruby-oci8 doesn't run on Apple Silicon because Oracle instant client
+for Apple Silicon has not been released yet.**
 
-Look at {file:docs/install-full-client.md}, {file:docs/install-instant-client.md}
-or {file:docs/install-binary-package.md} for other platforms.
-
-Install C compiler
-------------------
-
-You need to install the command line developer tools or the Xcode.
-(The latter includes the former.)
-
-Run `"cc --version"` in a terminal to check whether they are installed.
-
-If the cc version is printed, the tools are installed.
-
-If the follwoing dialog is displayed, click its Install button to
-install the tools.
-You have no need to install the Xcode to compile ruby-oci8.
-It requires command line tools, not an IDE such as the Xcode.
-
-![dialog](osx-install-dev-tools.png)
+Prerequisite
+------------
 
-If `"Agreeing to the Xcode/iOS license requires admin privileges,
-please re-run as root via sudo."` is printed, you need to run
-`"sudo cc --version"`, enter your password, look at the license
-and type `"agree"`.
+* Command line tools for Xcode or Xcode (by executing `xcode-select --install`) or [Xcode]
 
 Install Oracle Instant Client Packages
 --------------------------------------
 
-### Download Oracle Instant Client Packages
-
-Download the following packages from [Oracle Technology Network][]
-
-* Instant Client Package - Basic (`instantclient-basic-macos.x64-12.1.0.2.0.zip`) or Basic Lite (`instantclient-basiclite-macos.x64-12.1.0.2.0.zip`)
-* Instant Client Package - SDK (`instantclient-sdk-macos.x64-12.1.0.2.0.zip`)
-* Instant Client Package - SQL*Plus (`instantclient-sdk-macos.x64-12.1.0.2.0.zip`) (optionally) 
-
-### Install Oracle Instant Client Packages via Homebrew
-
-To install `Oracle Instant Client Basic` via [Homebrew][]
-
-* Copy downloaded zip files to `/Library/Caches/Homebrew`
-  (if the environment variable `HOMEBREW_CACHE`
-  is not set and `$HOME/Library/Caches/Homebrew` doesn't exist.)
-
-* Run the followining commands:
-
-        brew tap InstantClientTap/instantclient
-        brew install instantclient-basic
-        brew install instantclient-sdk
-        brew install instantclient-sqlplus # (optionally)
-
-* Set the environment variable `OCI_DIR` while performing the following installation steps
-  if Homebrew is installed outside `/usr/local`.
-
-        export OCI_DIR=$(brew --prefix)/lib
-
-To install `Oracle Instant Client Basic Lite` via [Homebrew][]
-
-* Copy downloaded zip files to `/Library/Caches/Homebrew`
-  (if the environment variable `HOMEBREW_CACHE`
-  is not set and `$HOME/Library/Caches/Homebrew` doesn't exist.)
-
-* Run the followining commands:
-
-        brew tap InstantClientTap/instantclient
-        brew install instantclient-basiclite
-        brew install instantclient-sdk
-        brew install instantclient-sqlplus --with-basiclite # (optionally)
-        
-* Set the environment variable `OCI_DIR` while performing the following installation steps
-  if Homebrew is installed outside `/usr/local`.
-
-        export OCI_DIR=$(brew --prefix)/lib
-
-### Install Oracle Instant Client Manually
-
-If you don't use [Homebrew][], do the following:
-
-Unzip the packages as follows:
-
-    mkdir -p /opt/oracle
-    cd /opt/oracle
-
-Copy downloaded files to /opt/oracle before running the following commands.
-
-    unzip instantclient-basic-macos.x64-12.1.0.2.0.zip
-    unzip instantclient-sdk-macos.x64-12.1.0.2.0.zip
-    unzip instantclient-sqlplus-macos.x64-12.1.0.2.0.zip
-
-Make a symbolic link to link the library.
-
-    cd /opt/oracle/instantclient_12_1
-    ln -s libclntsh.dylib.12.1 libclntsh.dylib
-
-Set the environment variable OCI_DIR while performing the following installation steps.
-
-    export OCI_DIR=/opt/oracle/instantclient_12_1
-
-Installation
-------------
-
-If you get a problem in the following steps, look at {file:docs/report-installation-issue.md}.
-
-### gem package
-
-Run the following command.
+If you have installed [Homebrew], use the following command:
 
-    gem install ruby-oci8
+```shell
+$ brew tap InstantClientTap/instantclient
+$ brew install instantclient-basic   # or instantclient-basiclite
+$ brew install instantclient-sdk
+$ brew install instantclient-sqlplus # (optionally)
+```
 
-### tar.gz package
+Otherwise, look at this [page][OTN] and set the environment variable
+`OCI_DIR` to point the the directory where instant client is installed.
+Ruby-oci8 installation script checks the directory.
 
-#### Download the source code
+```shell
+export OCI_DIR=$HOME/Downloads/instantclient_19_8  # for example
+```
 
-Download the latest tar.gz package from [download page][].
+Install ruby-oci8
+-----------------
 
-#### Run make and install
+Note that `/usr/bin/ruby` isn't available. You need to use [`rbenv`] or so.
 
-    tar xvfz ruby-oci8-VERSION.tar.gz
-    cd ruby-oci8-VERSION
-    make
-    make install
+```shell
+$ gem install ruby-oci8
+```
 
-[download page]: https://bintray.com/kubo/generic/ruby-oci8
 [Homebrew]: http://brew.sh/
-[fix_oralib]: https://github.com/kubo/fix_oralib_osx
-[Oracle Technology Network]: http://www.oracle.com/technetwork/topics/intel-macsoft-096467.html
+[OTN]: https://www.oracle.com/database/technologies/instant-client/macos-intel-x86-downloads.html#ic_osx_inst
+[Xcode]: https://apps.apple.com/us/app/xcode/id497799835
+[`rbenv`]: https://github.com/rbenv/rbenv

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/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'

data/ext/oci8/apiwrap.yml

@@ -83,6 +83,17 @@ OCIBindByPos:
             - ub4 *curelep
             - ub4 mode
 
+# round trip: 0
+OCIBindDynamic:
+  :version: 800
+  :args:
+            - OCIBind *bindp
+            - OCIError *errhp
+            - void  *ictxp
+            - OCICallbackInBind icbfp
+            - void  *octxp
+            - OCICallbackOutBind ocbfp
+
 # round trip: 0
 OCIBindObject:
   :version: 800
@@ -180,6 +191,15 @@ OCIDefineByPos:
             - ub2 *rcodep
             - ub4 mode
 
+# round trip: 0
+OCIDefineDynamic:
+  :version: 800
+  :args:
+            - OCIDefine *defnp
+            - OCIError *errhp
+            - dvoid *octxp
+            - OCICallbackDefine ocbfp
+
 # round trip: 0
 OCIDefineObject:
   :version: 800
@@ -321,13 +341,6 @@ OCILobLocatorIsInit:
             - CONST OCILobLocator *locp
             - boolean *is_initialized
 
-# round trip: 1
-OCILogoff:
-  :version: 800
-  :args:
-            - OCISvcCtx *svchp
-            - OCIError *errhp
-
 # round trip: 0
 OCINumberAbs:
   :version: 800
@@ -1149,21 +1162,6 @@ OCIIntervalSetYearMonth:
             - sb4 mnth
             - OCIInterval *result
 
-# round trip: 1
-OCILogon2_nb:
-  :version: 900
-  :args:
-            - OCIEnv *envhp
-            - OCIError *errhp
-            - OCISvcCtx **svchp
-            - CONST text *username
-            - ub4 uname_len
-            - CONST text *password
-            - ub4 passwd_len
-            - CONST text *dbname
-            - ub4 dbname_len
-            - ub4 mode
-
 # round trip: 0 (not docmented. I guess.)
 OCIRowidToChar:
   :version: 900
@@ -1308,3 +1306,17 @@ OCIPing_nb:
             - OCISvcCtx *svchp
             - OCIError *errhp
             - ub4 mode
+
+#
+# Oracle 18.1
+#
+OCIServerRelease2:
+  :version: 1800
+  :args:
+            - dvoid *hndlp
+            - OCIError *errhp
+            - OraText *bufp
+            - ub4 bufsz
+            - ub1 hndltype
+            - ub4 *version
+            - ub4 mode

data/ext/oci8/attr.c

@@ -15,8 +15,9 @@ typedef struct {
     OCIRowid *ridp;
 } rowid_arg_t;
 
-static VALUE get_rowid_attr(rowid_arg_t *arg)
+static VALUE get_rowid_attr(VALUE varg)
 {
+    rowid_arg_t *arg = (rowid_arg_t *)varg;
     oci8_base_t *base = arg->base;
     ub4 attrtype = arg->attrtype;
     char buf[MAX_ROWID_LEN];
@@ -36,8 +37,9 @@ static VALUE get_rowid_attr(rowid_arg_t *arg)
     return rb_external_str_new_with_enc(buf, buflen, rb_usascii_encoding());
 }
 
-static VALUE rowid_ensure(rowid_arg_t *arg)
+static VALUE rowid_ensure(VALUE varg)
 {
+    rowid_arg_t *arg = (rowid_arg_t *)varg;
     if (arg->ridp != NULL) {
         OCIDescriptorFree(arg->ridp, OCI_DTYPE_ROWID);
     }