ruby-oci8 2.2.1 → 2.2.2

This diff has not been reviewed by any users.
Sign up to get free protection for your applications and to get access to all the features.
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