ruby-oci8 2.2.1 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/.yardopts CHANGED
@@ -11,9 +11,4 @@
11
11
  NEWS
12
12
  COPYING
13
13
  COPYING_old
14
- docs/install-full-client.md
15
- docs/install-instant-client.md
16
- docs/install-binary-package.md
17
- docs/install-on-osx.md
18
- docs/platform-specific-issues.md
19
- docs/report-installation-issue.md
14
+ docs/*.md
data/ChangeLog CHANGED
@@ -1,3 +1,101 @@
1
+ 2016-04-24 Kubo Takehiro <kubo@jiubao.org>
2
+ * mkpkg-win32.rb: Added to compile mingw32 packages.
3
+ * dist-files: Updated to include docs/report-installation-issue.md.
4
+
5
+ 2016-04-24 Kubo Takehiro <kubo@jiubao.org>
6
+ * NEWS: Add changes between 2.2.1 and 2.2.2.
7
+ * lib/oci8/version.rb: update to 2.2.2.
8
+
9
+ 2016-04-24 Kubo Takehiro <kubo@jiubao.org>
10
+ * docs/report-installation-issue.md: Use RbConfig::CONFIG instead of
11
+ deprecated Config::CONFIG.
12
+
13
+ 2016-04-24 Kubo Takehiro <kubo@jiubao.org>
14
+ * lib/oci8/oci8.rb: Add OCI8::in_cond and OCI8:InCondBindHelper.
15
+ * test/test_all.rb, test/test_bind_array.rb: Add test of OCI8::in_cond.
16
+ * README.md, docs/bind-array-to-in_cond.md: Add document of OCI8::in_cond.
17
+
18
+ 2016-04-10 Kubo Takehiro <kubo@jiubao.org>
19
+ * lib/oci8/connection_pool.rb: update document.
20
+
21
+ 2016-03-27 Kubo Takehiro <kubo@jiubao.org>
22
+ * lib/oci8/object.rb: Suppress warning: instance variable
23
+ @name_to_tdo not initialized.
24
+
25
+ 2016-03-27 Kubo Takehiro <kubo@jiubao.org>
26
+ * ext/oci8/apiwrap.yml, ext/oci8/metadata.c, ext/oci8/object.c,
27
+ ext/oci8/oci8.h, lib/oci8/object.rb, test/setup_test_object.sql,
28
+ test/test_object.rb: Check object type from each object instance
29
+ when an Oracle object is got from a bind parameter.
30
+ (github issue #119)
31
+
32
+ 2016-03-27 Kubo Takehiro <kubo@jiubao.org>
33
+ * lib/ruby-oci8.rb: Added for 'Bundler.require'.
34
+ (github issue #114)
35
+ * dist-files: Add lib/ruby-oci8.rb.
36
+
37
+ 2016-03-27 Kubo Takehiro <kubo@jiubao.org>
38
+ * README.md, docs/timeout-parameters.md, lib/oci8/oci8.rb:
39
+ Update documents about timeout parameters.
40
+
41
+ 2016-03-18 Kubo Takehiro <kubo@jiubao.org>
42
+ * ext/oci8/oraconf.rb: Fix for mswin64.
43
+
44
+ 2016-03-15 Kubo Takehiro <kubo@jiubao.org>
45
+ * docs/conflicts-local-connections-and-processes.md: Add a document
46
+ about conflicts between local connections and child process
47
+ handling on Unix.
48
+ * README.md: Add a link to a newly added file.
49
+
50
+ 2016-03-13 Kubo Takehiro <kubo@jiubao.org>
51
+ * ruby-oci8.gemspec: Change the license name in gemspec to suppress the
52
+ following warning.
53
+ WARNING: license value '2-clause BSD-style license' is invalid.
54
+ Use a license identifier from http://spdx.org/licenses or 'Nonstandard'
55
+ for a nonstandard license.
56
+
57
+ 2016-01-29 Kubo Takehiro <kubo@jiubao.org>
58
+ * lib/oci8/oci8.rb, lib/oci8/properties.rb: Rename outbound_connect_timeout in
59
+ OCI8::properties to connect_timeout.
60
+ * docs/timeout-parameters.md: Revise document.
61
+
62
+ 2015-12-20 Kubo Takehiro <kubo@jiubao.org>
63
+ * lib/oci8/cursor.rb: Use OCI_ATTR_UB8_ROW_COUNT to get the number of processed rows
64
+ if Oracle client version is 12c or upper.
65
+
66
+ 2015-12-20 Kubo Takehiro <kubo@jiubao.org>
67
+ * lib/oci8/oci8.rb, lib/oci8/properties.rb, test/test_connstr.rb:
68
+ Support tcp_connect_timeout, connect_timeout, send_timeout and
69
+ recv_timeout in OCI8::properties.
70
+ * .yardopts, dist-files, docs/timeout-parameters.md: Add document
71
+ about timeout parameters.
72
+
73
+ 2015-12-19 Kubo Takehiro <kubo@jiubao.org>
74
+ * lib/oci8/oci8.rb, lib/oci8/ocihandle.rb: Support SYSBACKUP, SYSDG
75
+ and SYSKM privileges.
76
+ (github issue #110)
77
+
78
+ 2015-12-19 Kubo Takehiro <kubo@jiubao.org>
79
+ * ext/oci8/plthook_win32.c: Fix bug introduced by the previous commit
80
+ for mingw32 64-bit compiler.
81
+ (github issue #113)
82
+
83
+ 2015-12-18 Kubo Takehiro <kubo@jiubao.org>
84
+ * ext/oci8/plthook_win32.c, ext/oci8/extconf.rb: Import the latest
85
+ plthook_win32.c for cygwin. Ruby-oci8 had not been compiled on
86
+ cygwin since 2.1.8.
87
+ (github issue #113)
88
+
89
+ 2015-12-18 Kubo Takehiro <kubo@jiubao.org>
90
+ * ext/oci8/oraconf.rb: Fix a linkage error on cygwin and mingw32
91
+ when installing without `--with-runtime-check`.
92
+ This bug was introduced in ruby-oci8 2.2.1.
93
+ (github issue #113)
94
+
95
+ 2015-11-28 Kubo Takehiro <kubo@jiubao.org>
96
+ * ext/oci8/oraconf.rb: Check the default value of DYLD_FALLBACK_LIBRARY_PATH
97
+ after checking OCI_DIR. (OS X only)
98
+
1
99
  2015-11-01 Kubo Takehiro <kubo@jiubao.org>
2
100
  * NEWS: Add changes between 2.2.0.2 and 2.2.1.
3
101
  * lib/oci8/version.rb: update to 2.2.1.
data/NEWS CHANGED
@@ -1,5 +1,52 @@
1
1
  # @markup markdown
2
2
 
3
+ 2.2.2
4
+ =====
5
+
6
+ New Features
7
+ ------------
8
+
9
+ ### Add OCI8::in_cond
10
+
11
+ This is a helper method to bind an array to parameters in IN-conditions.
12
+ See {file:docs/bind-array-to-in_cond.md Bind an Array to IN-condition}
13
+
14
+ ### Add timeout parameters in OCI8::properties
15
+
16
+ See {file:docs/timeout-parameters.md Timeout Parameters}
17
+
18
+ ### Support SYSBACKUP, SYSDG and SYSKM privileges.
19
+
20
+ For example:
21
+
22
+ OCI8.new(username, password, database, :SYSBACKUP)
23
+
24
+ (github issue #110)
25
+
26
+ ### Support {OCI8::Cursor#row_count} over 4G (Oracle 12c client only)
27
+
28
+ Fixed Issues
29
+ ------------
30
+
31
+ ### Fix type mapping of subtypes of Oracle object
32
+
33
+ github issue #119
34
+
35
+ ### Fix compile error on cygwin since ruby-oci8 2.1.8.
36
+
37
+ github issue #113
38
+
39
+ ### Fix compile error when the ruby was compiled by Visual Studio 64bit.
40
+
41
+ Other Changes
42
+ -------------
43
+
44
+ - Suppress warning: instance variable @name_to_tdo not initialized.
45
+
46
+
47
+ - Check the default value of DYLD_FALLBACK_LIBRARY_PATH after checking OCI_DIR on installation. (OS X only)
48
+
49
+
3
50
  2.2.1
4
51
  =====
5
52
 
@@ -9,7 +56,7 @@ New Features
9
56
  ### Add OCI8::Metadata::Boolean
10
57
 
11
58
  Support boolean type binding. This feature requires Oracle 12c client and server.
12
- This doens't work when either Oracle server or client is 11g or lower.
59
+ Binding a boolean value fails when either Oracle server or client is 11g or lower.
13
60
 
14
61
  Fixed Issues
15
62
  ------------
data/README.md CHANGED
@@ -41,6 +41,13 @@ Report issues
41
41
  * {file:docs/report-installation-issue.md Report Installation Issues}
42
42
  * [The issues page on github](https://github.com/kubo/ruby-oci8/issues)
43
43
 
44
+ Other documents
45
+ ===============
46
+
47
+ * {file:docs/timeout-parameters.md Timeout Parameters}
48
+ * {file:docs/conflicts-local-connections-and-processes.md Conflicts between Local Connections and Child Process Handling on Unix}
49
+ * {file:docs/bind-array-to-in_cond.md Bind an Array to IN-condition}
50
+
44
51
  License
45
52
  =======
46
53
 
data/dist-files CHANGED
@@ -10,13 +10,16 @@ metaconfig
10
10
  pre-distclean.rb
11
11
  ruby-oci8.gemspec
12
12
  setup.rb
13
+ docs/bind-array-to-in_cond.md
13
14
  docs/install-binary-package.md
14
15
  docs/install-full-client.md
15
16
  docs/install-instant-client.md
16
17
  docs/install-on-osx.md
18
+ docs/conflicts-local-connections-and-processes.md
17
19
  docs/osx-install-dev-tools.png
18
20
  docs/platform-specific-issues.md
19
21
  docs/report-installation-issue.md
22
+ docs/timeout-parameters.md
20
23
  ext/oci8/.document
21
24
  ext/oci8/MANIFEST
22
25
  ext/oci8/apiwrap.c.tmpl
@@ -73,6 +76,7 @@ lib/oci8/ocihandle.rb
73
76
  lib/oci8/oracle_version.rb
74
77
  lib/oci8/properties.rb
75
78
  lib/oci8/version.rb
79
+ lib/ruby-oci8.rb
76
80
  test/README
77
81
  test/config.rb
78
82
  test/setup_test_object.sql
@@ -0,0 +1,38 @@
1
+ @ Bind an Array to IN-condition
2
+
3
+ Bind an Array to IN-condition
4
+ =============================
5
+
6
+ Binding an arbitrary-length array to IN-condition is not simple.
7
+ You need to create an SQL statement containing a comma-separated
8
+ list whose length is same with the input data.
9
+
10
+ Example:
11
+
12
+ ids = [ ... ] # an arbitrary-length array containing user IDs.
13
+
14
+ place_holder_string = Array.new(ids.length) {|index| ":id_#{index}"}.join(', ')
15
+ # place_holder_string is:
16
+ # ":id_0" if ids.length == 1
17
+ # ":id_0, :id_1" if ids.length == 2
18
+ # ...
19
+ cursor = conn.parse("select * from users where id in (#{place_holder_string})")
20
+ ids.each_with_index do |id, index|
21
+ cursor.bind_param("id#{index}", id) # bind each element
22
+ end
23
+ cursor.exec()
24
+
25
+ However this is awkward. So {OCI8.in_cond} was added in ruby-oci8 2.2.2.
26
+ The above code is rewritten as follows:
27
+
28
+ ids = [ ... ] # an arbitrary-length array containing user IDs.
29
+
30
+ in_cond = OCI8::in_cond(:id, ids)]
31
+ cursor = conn.exec("select * from users where id in (#{in_cond.names})", *in_cond.values)
32
+
33
+ or
34
+
35
+ ids = [ ... ] # an arbitrary-length array containing user IDs.
36
+
37
+ in_cond = OCI8::in_cond(:id, ids, Integer) # set the data type explicitly
38
+ cursor = conn.exec("select * from users where id in (#{in_cond.names})", *in_cond.values)
@@ -0,0 +1,95 @@
1
+ # @title Conflicts between Local Connections and Child Process Handling on Unix
2
+
3
+ Background
4
+ ==========
5
+
6
+ When a local (not-TCP) Oracle connection is established on Unix,
7
+ Oracle client library changes signal handlers in the process to reap
8
+ all dead child processes. However it conflicts with child process
9
+ handling in ruby.
10
+
11
+ Problem 1: It trashes child process handling of Open3::popen.
12
+ ==========
13
+
14
+ require 'oci8'
15
+ require 'open3'
16
+
17
+ Open3::popen3('true') do |i, o, e, w|
18
+ p w.value
19
+ end
20
+
21
+ conn = OCI8.new(username, password)
22
+ puts "establish a local connection"
23
+
24
+ Open3::popen3('true') do |i, o, e, w|
25
+ p w.value
26
+ end
27
+
28
+ The above code outputs the following result:
29
+
30
+ #<Process::Status: pid 19236 exit 0>
31
+ establish a local connection
32
+ nil
33
+
34
+ `w.value` after a local connection doesn't work because Oracle reaps
35
+ the child process on the process termination before ruby detects it.
36
+
37
+ Problem 2: It creates defunct processes after disconnection if signal handlers are reset.
38
+ ==========
39
+
40
+ The `system` function overwrites signal handlers.
41
+ It fixes the problem 1 as follows.
42
+
43
+ require 'oci8'
44
+ require 'open3'
45
+
46
+ Open3::popen3('true') do |i, o, e, w|
47
+ p w.value
48
+ end
49
+
50
+ conn = OCI8.new(username, password) # Signal handlers are changed here.
51
+ puts "establish a local connection"
52
+ system('true') # Signal handlers are reset here.
53
+
54
+ Open3::popen3('true') do |i, o, e, w|
55
+ p w.value
56
+ end
57
+
58
+ The above code outputs the following result:
59
+
60
+ #<Process::Status: pid 19652 exit 0>
61
+ establish a local connection
62
+ #<Process::Status: pid 19656 exit 0>
63
+
64
+ `w.value` after a local connection works.
65
+
66
+ However it makes another problem.
67
+
68
+ require 'oci8'
69
+
70
+ conn = OCI8.new(username, password) # Signal handlers are changed here.
71
+ # An Oracle server process is created here.
72
+ puts "establish a local connection"
73
+ system('true') # Signal handlers are reset here.
74
+
75
+ conn.logoff # The Oracle server process exits and become defunct.
76
+
77
+ # ... do other stuffs...
78
+
79
+ If a program repeatedly creates a local connection and disconnects it,
80
+ the number of defunct processes increases gradually.
81
+
82
+ Solution: BEQUEATH_DETACH=YES
83
+ ==========
84
+
85
+ By setting [BEQUEATH_DETACH=YES][] in `sqlnet.ora`, Oracle client library
86
+ doesn't change signal handlers. The above two problems are fixed.
87
+
88
+ Oracle client library reads `sqlnet.ora` in the following locations:
89
+
90
+ * `$TNS_ADMIN/sqlnet.ora` if the environment variable `TNS_ADMIN`
91
+ is set and `$TNS_ADMIN/sqlnet.ora` exists.
92
+ Otherwise, `$ORACLE_HOME/network/admin/sqlnet.ora`.
93
+ * `$HOME/.sqlnet.ora`
94
+
95
+ [BEQUEATH_DETACH=YES]: https://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF183
@@ -20,14 +20,14 @@ If it is a new one, post the following information to [github][].
20
20
 
21
21
  file `which ruby`
22
22
  ruby --version
23
- ruby -r rbconfig -e "p Config::CONFIG['host']"
24
- ruby -r rbconfig -e "p Config::CONFIG['CC']"
25
- ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
26
- ruby -r rbconfig -e "p Config::CONFIG['LDSHARED']"
27
- ruby -r rbconfig -e "p Config::CONFIG['LDFLAGS']"
28
- ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
29
- ruby -r rbconfig -e "p Config::CONFIG['LIBS']"
30
- ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
23
+ ruby -r rbconfig -e "p RbConfig::CONFIG['host']"
24
+ ruby -r rbconfig -e "p RbConfig::CONFIG['CC']"
25
+ ruby -r rbconfig -e "p RbConfig::CONFIG['CFLAGS']"
26
+ ruby -r rbconfig -e "p RbConfig::CONFIG['LDSHARED']"
27
+ ruby -r rbconfig -e "p RbConfig::CONFIG['LDFLAGS']"
28
+ ruby -r rbconfig -e "p RbConfig::CONFIG['DLDLAGS']"
29
+ ruby -r rbconfig -e "p RbConfig::CONFIG['LIBS']"
30
+ ruby -r rbconfig -e "p RbConfig::CONFIG['GNU_LD']"
31
31
 
32
32
  # if you use gcc,
33
33
  gcc --print-prog-name=ld
@@ -0,0 +1,91 @@
1
+ # @title Timeout Parameters
2
+
3
+ Timeout Parameters
4
+ ==================
5
+
6
+ The following timeout parameters are available since ruby-oci8 2.2.2.
7
+
8
+ * tcp_connect_timeout
9
+ * connect_timeout
10
+ * send_timeout
11
+ * recv_timeout
12
+
13
+ For example:
14
+
15
+ OCI8.properties[:tcp_connect_timeout] = 10
16
+ OCI8.properties[:connect_timeout] = 15
17
+ OCI8.properties[:send_timeout] = 60
18
+ OCI8.properties[:recv_timeout] = 60
19
+
20
+ These parameters are applied only to TCP/IP connections.
21
+
22
+ The first two parameters `tcp_connect_timeout` and `connect_timeout`
23
+ are applied only to [connect descriptors][connect descriptor] using [Easy Connect Naming Method][EZCONNECT].
24
+ If you use a net service name, you should set [TRANSPORT_CONNECT_TIMEOUT][] and/or
25
+ [CONNECT_TIMEOUT][] in the address descriptor in `tnsnames.ora` instead of these parameters.
26
+ If you use easy connect naming method without any of `port`, `service_name`, `server` and `instance_name`,
27
+ you need to use `//host` to distinguish it from a net service name.
28
+
29
+ The next two parameters `send_timeout` and `recv_timeout` are available on Oracle 11g client
30
+ or upper. Use these parameters to prevent a ruby process from being blocked by poor quality network.
31
+ Otherwise, the ruby process may be blocked until TCP keepalive time (2 hours).
32
+
33
+ tcp_connect_timeout
34
+ -------------------
35
+
36
+ `tcp_connect_timeout` is equivalent to [TCP.CONNECT_TIMEOUT][] in the client-side `sqlnet.ora` and
37
+ [TRANSPORT_CONNECT_TIMEOUT][] in the address descriptor.
38
+ See description about [TCP.CONNECT_TIMEOUT][] and [TRANSPORT_CONNECT_TIMEOUT][].
39
+
40
+ connect_timeout
41
+ ---------------
42
+
43
+ `connect_timeout` is equivalent to [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] in the client-side `sqlnet.ora`
44
+ and [CONNECT_TIMEOUT][] in the address description.
45
+ See description about [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] and [CONNECT_TIMEOUT][].
46
+
47
+ Note: this parameter isn't equivalent to login timeout. It needs the following three
48
+ steps to establish a database connection.
49
+
50
+ 1. Establish a TCP/IP connection.
51
+ 2. Establish an [Oracle Net][] connection on the TCP/IP connection.
52
+ 3. Authenticate and authorize the database user.
53
+
54
+ `tcp_connect_timeout` sets the timeout of the first step.
55
+ `connect_timeout` sets the total timeout of the first and the second steps.
56
+ There is no timeout parameter to limit the maximum time of all three steps.
57
+
58
+ Use `send_timeout` and `recv_timeout` in case that a TCP/IP connection stalls
59
+ in the third step.
60
+
61
+ send_timeout
62
+ ------------
63
+
64
+ `send_timeout` is equivalent to [SQLNET.SEND_TIMEOUT][] in the client-side `sqlnet.ora`.
65
+ See description about [SQLNET.SEND_TIMEOUT][].
66
+
67
+ Note that the connection becomes unusable on timeout.
68
+
69
+ See also {OCI8#send_timeout=}.
70
+
71
+ recv_timeout
72
+ ------------
73
+
74
+ `recv_timeout` is equivalent to [SQLNET.RECV_TIMEOUT][] in the client-side `sqlnet.ora`.
75
+ See description about [SQLNET.RECV_TIMEOUT][].
76
+
77
+ Note that the connection becomes unusable on timeout.
78
+
79
+ See also {OCI8#recv_timeout=}.
80
+
81
+ Note: This parameter must be larger than the longest SQL execution time in your applications.
82
+
83
+ [TCP.CONNECT_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#BIIDDACA
84
+ [SQLNET.OUTBOUND_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF427
85
+ [SQLNET.SEND_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF228
86
+ [SQLNET.RECV_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF227
87
+ [connect descriptor]: https://docs.oracle.com/database/121/NETRF/glossary.htm#BGBEDFBF
88
+ [EZCONNECT]: https://docs.oracle.com/database/121/NETAG/naming.htm#NETAG255
89
+ [CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#NETRF666
90
+ [TRANSPORT_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#NETRF1982
91
+ [Oracle Net]: https://en.wikipedia.org/wiki/Oracle_Net_Services#Oracle_Net