dbi-dbrc 1.1.8-x86-mingw32 → 1.1.9-x86-mingw32

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/CHANGES CHANGED
@@ -1,141 +1,145 @@
1
- == 1.1.8 - 7-Oct-2010
2
- * Fixed a logic bug in the constructor that primarily affected MS Windows with
3
- regards to determining the user's home directory.
4
-
5
- == 1.1.7 - 6-Oct-2010
6
- * More robust file decryption/encryption for MS Windows.
7
- * Better platform checking for MS Windows.
8
- * Refactored the Rakefile. Removed the old installation tasks and replaced
9
- them with a series of gem tasks.
10
- * Updated the win32 library dependencies.
11
-
12
- == 1.1.6 - 10-Sep-2009
13
- * Fixed validation for dbrc_dir argument.
14
- * Added a test for bogus dbrc_dir arguments.
15
-
16
- == 1.1.5 - 3-Sep-2009
17
- * License changed to Artistic 2.0.
18
- * Some gemspec updates, including the license and description.
19
- * Renamed the test files. The ts_all.rb file was removed.
20
- * Added win32-process as a dependency on MS Windows.
21
- * Added test-unit as a development dependency. Some tests were refactored
22
- to use features from test-unit 2.x.
23
- * Added the 'test_xml' and 'test_yml' rake tasks.
24
- * Refactored the main test task.
25
- * Added explicit copyright and warranty to the README file.
26
-
27
- == 1.1.4 - 10-Nov-2008
28
- * Added a custom inspect method which filters the password.
29
-
30
- == 1.1.3 - 21-Jul-2008
31
- * More RUBY_PLATFORM changes that I missed in the last release.
32
- * Added inline RDOC for the accessors and updated the documentation
33
- for the constructor.
34
- * Added the DBI::DBRC#dbrc_dir and DBI::DBRC#dbrc_file methods.
35
- * More tests.
36
-
37
- == 1.1.2 - 18-Jul-2008
38
- * Changed platform checking from RUBY_PLATFORM to Config::CONFIG['host_os']
39
- so that other implementations won't choke.
40
- * Updated the gemspec to add the sys-admin dependency.
41
- * Added a rubyforge_project to the gemspec.
42
- * Now has a separate gem for MS Windows.
43
-
44
- == 1.1.1 - 2-Aug-2007
45
- * DBRCError is now DBRC::Error.
46
- * Added a Rakefile with tasks for installation and testing.
47
- * Added the win32-dir library as a prerequisite for MS Windows.
48
- * Removed the install.rb file. That's now handled by the Rakefile.
49
- * Some refactoring in the constructor, including the elimination of
50
- warnings that appeared when run with -w.
51
- * Some doc and test updates.
52
-
53
- == 1.1.0 - 19-Oct-2005
54
- * Bug fix for MS Windows (there's no Win32 namespace for win32/file).
55
- * Changed platform detection mechanism.
56
-
57
- == 1.0.1 - 7-Oct-2005
58
- * Improved the error message when an entry isn't found.
59
-
60
- == 1.0.0 - 15-Jun-2005
61
- * Ditches the use of 'etc'. Now requires the 'sys-admin' package as its
62
- replacement (for all platforms).
63
- * Moved project to RubyForge.
64
- * Minor updates to tests, README and gemspec.
65
- * Now hosted on RubyForge.
66
-
67
- == 0.5.1 - 17-Mar-2005
68
- * Removed the 'doc' directory completely, and moved the primary
69
- documentation into the README file.
70
- * Removed the INSTALL file. Moved the installation directions into the
71
- README file.
72
- * Moved the examples into a toplevel 'examples' directory.
73
- * Made the README and CHANGES files rdoc friendly.
74
- * Added a gemspec.
75
-
76
- == 0.5.0 - 15-Oct-2004
77
- * Added a YAML subclass. Use this if you want to store your information in
78
- the .dbrc file in YAML format.
79
- * On Win32 systems, the .dbrc file must now be "hidden". Also, it will
80
- automatically decrypt/encrypt the file if it is encrypted. This also
81
- means that the win32-file package is also required on Win32 systems.
82
- * Massive refactoring of the XML subclass. It should work better now.
83
- * Moved the YML and XML subclasses directly into the dbrc.rb file.
84
- * For the aliases, you can now write as well as read.
85
- * In lieu of the namespace fix for "timeout" in 1.8, I have renamed "time_out"
86
- to simply "timeout". For backwards compatability, I have created an alias,
87
- so you may still use the old method name. However, this means that you
88
- should only use this package with 1.8.0 or later.
89
- * Removed the dbrc.html file. You can generate this on your own if you wish
90
- using rdtool.
91
- * Test suite changes.
92
-
93
- == 0.4.0 - 3-Sep-2004
94
- * Removed redundant error handling for cases when the database and/or login
95
- are not found.
96
- * Added an XML subclass. Use this if you want to store your information in
97
- the .dbrc file in XML format.
98
-
99
- == 0.3.0 - 26-Oct-2003
100
- * Win32 support added. Requires the win32-etc package.
101
- * rd doc separated from source. Moved to 'doc' directory.
102
- * Documentation updates and corrections.
103
- * Minor test suite tweaks for Win32 systems.
104
-
105
- == 0.2.1 - 28-Aug-2003
106
- * Removed VERSION class method. Just use the constant.
107
- * Bug fix with regards to split and Ruby 1.8. Thanks Michael Garriss.
108
- * Changed 'changelog' to 'CHANGES'.
109
- * Added a vanilla test script (test.rb)
110
- * Minor code optimization (IO.foreach)
111
- * Test unit cleanup
112
- * Minor internal directory layout and doc changes
113
-
114
- == 0.2.0 - 13-Jan-2003
115
- * DBRC class now under the DBI module namespace
116
- * Changed "timeout" to "time_out" to avoid confusion with the timeout
117
- module.
118
- * The 'time_out', 'max_reconn', and 'interval' methods now return Integers,
119
- rather than Strings.
120
- * Only the database, user and password fields are required now within the
121
- .dbrc file. The driver, time_out and max_reconn entries can be left blank
122
- without causing an error. Note that the 'dsn' method will return 'nil'
123
- if the driver isn't set.
124
- * Added a DBRCException class instead of just raising an error string.
125
- * Changed 'db' method to 'database' (but 'db' is an alias)
126
- * Changed 'max_reconn' method to 'maximum_reconnects' (but 'max_reconn'
127
- is an alias')
128
- * Added 'passwd' alias for 'password' method
129
- * Added a VERSION class method
130
- * Methods that should have been private are now private
131
- * Internal directory layout change
132
- * Tests added
133
- * Install script improved
134
- * Documentation additions, including plain text doc
135
-
136
- == 0.1.1 - 26-Jul-2002
137
- * Added 'dsn()' method
138
- * Minor documentation additions
139
-
140
- == 0.1.0 - 26-Jul-2002
141
- * Initial release
1
+ == 1.1.9 - 10-Jan-2013
2
+ * Fixed an unused variable warning.
3
+ * Changed the way I check for MS Windows.
4
+
5
+ == 1.1.8 - 7-Oct-2010
6
+ * Fixed a logic bug in the constructor that primarily affected MS Windows with
7
+ regards to determining the user's home directory.
8
+
9
+ == 1.1.7 - 6-Oct-2010
10
+ * More robust file decryption/encryption for MS Windows.
11
+ * Better platform checking for MS Windows.
12
+ * Refactored the Rakefile. Removed the old installation tasks and replaced
13
+ them with a series of gem tasks.
14
+ * Updated the win32 library dependencies.
15
+
16
+ == 1.1.6 - 10-Sep-2009
17
+ * Fixed validation for dbrc_dir argument.
18
+ * Added a test for bogus dbrc_dir arguments.
19
+
20
+ == 1.1.5 - 3-Sep-2009
21
+ * License changed to Artistic 2.0.
22
+ * Some gemspec updates, including the license and description.
23
+ * Renamed the test files. The ts_all.rb file was removed.
24
+ * Added win32-process as a dependency on MS Windows.
25
+ * Added test-unit as a development dependency. Some tests were refactored
26
+ to use features from test-unit 2.x.
27
+ * Added the 'test_xml' and 'test_yml' rake tasks.
28
+ * Refactored the main test task.
29
+ * Added explicit copyright and warranty to the README file.
30
+
31
+ == 1.1.4 - 10-Nov-2008
32
+ * Added a custom inspect method which filters the password.
33
+
34
+ == 1.1.3 - 21-Jul-2008
35
+ * More RUBY_PLATFORM changes that I missed in the last release.
36
+ * Added inline RDOC for the accessors and updated the documentation
37
+ for the constructor.
38
+ * Added the DBI::DBRC#dbrc_dir and DBI::DBRC#dbrc_file methods.
39
+ * More tests.
40
+
41
+ == 1.1.2 - 18-Jul-2008
42
+ * Changed platform checking from RUBY_PLATFORM to Config::CONFIG['host_os']
43
+ so that other implementations won't choke.
44
+ * Updated the gemspec to add the sys-admin dependency.
45
+ * Added a rubyforge_project to the gemspec.
46
+ * Now has a separate gem for MS Windows.
47
+
48
+ == 1.1.1 - 2-Aug-2007
49
+ * DBRCError is now DBRC::Error.
50
+ * Added a Rakefile with tasks for installation and testing.
51
+ * Added the win32-dir library as a prerequisite for MS Windows.
52
+ * Removed the install.rb file. That's now handled by the Rakefile.
53
+ * Some refactoring in the constructor, including the elimination of
54
+ warnings that appeared when run with -w.
55
+ * Some doc and test updates.
56
+
57
+ == 1.1.0 - 19-Oct-2005
58
+ * Bug fix for MS Windows (there's no Win32 namespace for win32/file).
59
+ * Changed platform detection mechanism.
60
+
61
+ == 1.0.1 - 7-Oct-2005
62
+ * Improved the error message when an entry isn't found.
63
+
64
+ == 1.0.0 - 15-Jun-2005
65
+ * Ditches the use of 'etc'. Now requires the 'sys-admin' package as its
66
+ replacement (for all platforms).
67
+ * Moved project to RubyForge.
68
+ * Minor updates to tests, README and gemspec.
69
+ * Now hosted on RubyForge.
70
+
71
+ == 0.5.1 - 17-Mar-2005
72
+ * Removed the 'doc' directory completely, and moved the primary
73
+ documentation into the README file.
74
+ * Removed the INSTALL file. Moved the installation directions into the
75
+ README file.
76
+ * Moved the examples into a toplevel 'examples' directory.
77
+ * Made the README and CHANGES files rdoc friendly.
78
+ * Added a gemspec.
79
+
80
+ == 0.5.0 - 15-Oct-2004
81
+ * Added a YAML subclass. Use this if you want to store your information in
82
+ the .dbrc file in YAML format.
83
+ * On Win32 systems, the .dbrc file must now be "hidden". Also, it will
84
+ automatically decrypt/encrypt the file if it is encrypted. This also
85
+ means that the win32-file package is also required on Win32 systems.
86
+ * Massive refactoring of the XML subclass. It should work better now.
87
+ * Moved the YML and XML subclasses directly into the dbrc.rb file.
88
+ * For the aliases, you can now write as well as read.
89
+ * In lieu of the namespace fix for "timeout" in 1.8, I have renamed "time_out"
90
+ to simply "timeout". For backwards compatability, I have created an alias,
91
+ so you may still use the old method name. However, this means that you
92
+ should only use this package with 1.8.0 or later.
93
+ * Removed the dbrc.html file. You can generate this on your own if you wish
94
+ using rdtool.
95
+ * Test suite changes.
96
+
97
+ == 0.4.0 - 3-Sep-2004
98
+ * Removed redundant error handling for cases when the database and/or login
99
+ are not found.
100
+ * Added an XML subclass. Use this if you want to store your information in
101
+ the .dbrc file in XML format.
102
+
103
+ == 0.3.0 - 26-Oct-2003
104
+ * Win32 support added. Requires the win32-etc package.
105
+ * rd doc separated from source. Moved to 'doc' directory.
106
+ * Documentation updates and corrections.
107
+ * Minor test suite tweaks for Win32 systems.
108
+
109
+ == 0.2.1 - 28-Aug-2003
110
+ * Removed VERSION class method. Just use the constant.
111
+ * Bug fix with regards to split and Ruby 1.8. Thanks Michael Garriss.
112
+ * Changed 'changelog' to 'CHANGES'.
113
+ * Added a vanilla test script (test.rb)
114
+ * Minor code optimization (IO.foreach)
115
+ * Test unit cleanup
116
+ * Minor internal directory layout and doc changes
117
+
118
+ == 0.2.0 - 13-Jan-2003
119
+ * DBRC class now under the DBI module namespace
120
+ * Changed "timeout" to "time_out" to avoid confusion with the timeout
121
+ module.
122
+ * The 'time_out', 'max_reconn', and 'interval' methods now return Integers,
123
+ rather than Strings.
124
+ * Only the database, user and password fields are required now within the
125
+ .dbrc file. The driver, time_out and max_reconn entries can be left blank
126
+ without causing an error. Note that the 'dsn' method will return 'nil'
127
+ if the driver isn't set.
128
+ * Added a DBRCException class instead of just raising an error string.
129
+ * Changed 'db' method to 'database' (but 'db' is an alias)
130
+ * Changed 'max_reconn' method to 'maximum_reconnects' (but 'max_reconn'
131
+ is an alias')
132
+ * Added 'passwd' alias for 'password' method
133
+ * Added a VERSION class method
134
+ * Methods that should have been private are now private
135
+ * Internal directory layout change
136
+ * Tests added
137
+ * Install script improved
138
+ * Documentation additions, including plain text doc
139
+
140
+ == 0.1.1 - 26-Jul-2002
141
+ * Added 'dsn()' method
142
+ * Minor documentation additions
143
+
144
+ == 0.1.0 - 26-Jul-2002
145
+ * Initial release
data/MANIFEST CHANGED
@@ -1,15 +1,15 @@
1
- * MANIFEST
2
- * CHANGES
3
- * README
4
- * Rakefile
5
- * dbi-dbrc.gemspec
6
- * lib/dbi/dbrc.rb
7
- * examples/plain/.dbrc
8
- * examples/plain/test.rb
9
- * examples/xml_examples/.dbrc
10
- * examples/xml_examples/test_xml.rb
11
- * examples/yml_examples/.dbrc
12
- * examples/yml_examples/test_yml.rb
13
- * test/test_dbi_dbrc.rb
14
- * test/test_dbi_dbrc_xml.rb
15
- * test/test_dbi_dbrc_yml.rb
1
+ * MANIFEST
2
+ * CHANGES
3
+ * README
4
+ * Rakefile
5
+ * dbi-dbrc.gemspec
6
+ * lib/dbi/dbrc.rb
7
+ * examples/plain/.dbrc
8
+ * examples/plain/test.rb
9
+ * examples/xml_examples/.dbrc
10
+ * examples/xml_examples/test_xml.rb
11
+ * examples/yml_examples/.dbrc
12
+ * examples/yml_examples/test_yml.rb
13
+ * test/test_dbi_dbrc.rb
14
+ * test/test_dbi_dbrc_xml.rb
15
+ * test/test_dbi_dbrc_yml.rb
data/README CHANGED
@@ -1,260 +1,260 @@
1
- == Description
2
- This is a supplement to the dbi module, allowing you to avoid hard-coding
3
- passwords in your programs that make database connections. It can also
4
- be used as a general password storage mechanism for other types of
5
- connections, e.g. ssh, ftp, etc.
6
-
7
- == Requirements
8
- * Ruby 1.8.2 or later
9
- * sys-admin
10
- * win32-file (MS Windows only)
11
- * win32-dir (MS Windows only)
12
-
13
- == Installation
14
- gem install dbi-dbrc
15
-
16
- == Synopsis
17
- require 'dbi/dbrc'
18
- include DBI
19
-
20
- dbrc = DBRC.new('mydb')
21
-
22
- or
23
-
24
- dbrc = DBRC.new('mydb', 'someUser')
25
-
26
- puts dbrc.db
27
- puts dbrc.user
28
- puts dbrc.driver
29
- puts dbrc.timeout
30
- puts dbrc.max_reconn
31
- puts dbrc.interval
32
- puts dbrc.dsn
33
-
34
- == Notes on the .dbrc file
35
- This module relies on a file in your home directory called ".dbrc", and it
36
- is meant to be analogous to the ".netrc" file used by programs such as
37
- telnet. The .dbrc file has several conditions that must be met by the
38
- module or it will fail:
39
-
40
- * Permissions must be set to 600 (Unix only).
41
- * Must be hidden (MS Windows only).
42
- * Must be owned by the current user.
43
- * Must have database, user and password. Other fields are optional.
44
- * Must be in the following space-separated format (in the 'plain' version):
45
-
46
- database user password driver timeout maximum_reconnects interval
47
-
48
- e.g. mydb dan mypass oracle 10 2 30
49
-
50
- You may include comments in the .dbrc file by starting the line with a
51
- "#" symbol.
52
-
53
- A failure in any of the rules mentioned above will result in a DBRC::Error
54
- being raised. In addition, the file may also be encrypted on MS Windows
55
- systems, in which case the file will automatically be (temporarily)
56
- decrypted.
57
-
58
- The format for XML (using the example above) is as follows:
59
-
60
- <dbrc>
61
- <database name="mydb">
62
- <user>dan</user>
63
- <password>mypass</password>
64
- <driver>oracle</driver>
65
- <interval>30</interval>
66
- <timeout>10</timeout>
67
- <maximum_reconnects>2</maximum_reconnects>
68
- </database>
69
- </dbrc>
70
-
71
- The format for YAML is as follows:
72
-
73
- - mydb:
74
- user: dan
75
- password: mypass
76
- driver: oracle
77
- interval: 30
78
- timeout: 10
79
- max_reconn: 2
80
-
81
- == Constants
82
- VERSION
83
- The current version of this library, returned as a String.
84
-
85
- == Class Methods
86
- DBRC.new(db, user=nil, dir=nil)
87
- The constructor takes one to three arguments. The first argument is the
88
- database name. This *must* be provided. If only the database name is
89
- passed, the module will look for the first database entry in the .dbrc
90
- file that matches.
91
-
92
- The second argument, a user name, is optional. If it is passed, the
93
- module will look for the first entry in the .dbrc file where both the
94
- database *and* user name match.
95
-
96
- The third argument, also optional, specifies the directory where DBRC will
97
- look for the .dbrc file. By default, it looks in the pwuid (present
98
- working user id) home directory. The rules for a .dbrc file still apply.
99
-
100
- MS Windows users should read the "Notes" section for how your home directory
101
- is determined.
102
-
103
- == Instance Methods
104
- DBRC#database
105
- The name of the database. Note that the same entry can appear more than
106
- once, presumably because you have multiple user id's for the same
107
- database.
108
-
109
- DBRC#db
110
- An alias for DBRC#database.
111
-
112
- DBRC#database=(database)
113
- Sets the database to +database+. This is generally discouraged because
114
- it does not automatically reset the dsn.
115
-
116
- DBRC#db=(database)
117
- An alias for DBRC#database=.
118
-
119
- DBRC#user
120
- A valid user name for that database.
121
-
122
- DBRC#user=(user)
123
- Sets the user name to +user+.
124
-
125
- DBRC#password
126
- The password for that user.
127
-
128
- DBRC#passwd
129
- An alias for DBRC#password.
130
-
131
- DBRC#password=(password)
132
- Sets the password to +password+.
133
-
134
- DBRC#passwd=(password)
135
- An alias for DBRC#password=.
136
-
137
- DBRC#driver
138
- The driver type for that database (Oracle, MySql, etc).
139
-
140
- DBRC#driver=(driver)
141
- Sets the driver to +driver+. This use is discouraged because it does
142
- not reset the dsn.
143
-
144
- DBRC#timeout
145
- The timeout period for a connection before the attempt is dropped.
146
-
147
- DBRC#time_out
148
- An alias for DBRC#timeout, provided purely for the sake of backwards
149
- compatability.
150
-
151
- DBRC#timeout=(int)
152
- Sets the timeout value to +int+.
153
-
154
- DBRC#maximum_reconnects
155
- The maximum number of reconnect attempts that should be made for the the
156
- database. Presumablly, you would use this with a "retry" within a rescue
157
- block.
158
-
159
- DBRC#max_reconn
160
- An alias for DBRC#maximum_reconnects.
161
-
162
- DBRC#maximum_reconnects=(max)
163
- Sets the maximum number of reconnect attempts to +max+.
164
-
165
- DBRC#max_reconn=(max)
166
- An alias for DBRC#maximum_reconnects.
167
-
168
- DBRC#interval
169
- The number of seconds to wait before attempting to reconnect to the database
170
- again should a network/database glitch occur.
171
-
172
- DBRC#interval=(int)
173
- Sets the interval seconds between connection attempts.
174
-
175
- DBRC#dsn
176
- Returns a string in "dbi:<driver>:<database>" format.
177
-
178
- DBRC#dsn=(dsn)
179
- Sets the dsn string to +dsn+. This method is discouraged because it does
180
- not automatically reset the driver or database.
181
-
182
- == Canonical Example
183
- # This is a basic template for how I do things:
184
-
185
- require 'dbi/dbrc'
186
- require 'timeout'
187
-
188
- db = DBI::DBRC.new("somedb")
189
- n = db.max_reconn
190
-
191
- begin
192
- Timeout.timeout(db.timeout){
193
- DBI.connect(db.dsn, db.user, db.passwd)
194
- }
195
- rescue DBI::Error
196
- n -= 1
197
- if n > 0
198
- sleep db.interval
199
- retry
200
- end
201
- raise
202
- rescue TimeoutError
203
- # handle timeout error
204
- end
205
-
206
- == Notes for MS Windows Users
207
- The 'home' directory for Win32 users is determined by ENV['USERPROFILE'].
208
- If that is not set, ENV['HOME'] is used. If that is not set, then
209
- 'C:\Documents and Settings\user_name' is used.
210
-
211
- To make your file hidden, right click on the .dbrc file in your Explorer
212
- window, select "Properties" and check the "Hidden" checkbox.
213
-
214
- I was going to require that the .dbrc file be encrypted on MS Windows,
215
- but that may require an official "certificate", assigned to you by a third
216
- party, which is a bit much to expect. However, if the file is encrypted,
217
- DBRC will attempt to decrypt it, parse it, and encrypt it again when done
218
- parsing.
219
-
220
- == Notes on running the test suite
221
- I cannot guarantee that the .dbrc files under the +examples+
222
- subdirectories maintain the appropriate properties. This can cause
223
- failures for the test suite (which uses these files).
224
-
225
- The only solution is to perform a 'chmod 600 .dbrc' (on Unix) or set
226
- the properties to 'hidden' (on MS Windows) manually, for the file in
227
- question.
228
-
229
- == Summary
230
- These "methods" don't really do anything. They're simply meant as a
231
- convenience mechanism for you dbi connections, plus a little bit of
232
- obfuscation (for passwords).
233
-
234
- == Adding your own configuration
235
- If you want to add your own type of configuration file, you can still use
236
- the dbi-dbrc library. All you need to do is:
237
-
238
- * subclass DBRC
239
- * redefine the +parse_dbrc_config_file+ method (a private method).
240
-
241
- Take a look at the XML and YML subclasses in dbrc.rb for two examples that
242
- you can work from.
243
-
244
- == Future Plans
245
- Add DBI::DBRC::JSON.
246
-
247
- == Known Bugs
248
- I'm not positive about the dsn strings for databases other than Oracle.
249
- If it's not correct, please let me know.
250
-
251
- == Copyright
252
- (C) Copyright 2002-2009, Daniel J. Berger, all rights reserved.
253
-
254
- = Warranty
255
- This package is provided "as is" and without any express or
256
- implied warranties, including, without limitation, the implied
257
- warranties of merchantability and fitness for a particular purpose
258
-
259
- == Author
260
- Daniel J. Berger
1
+ == Description
2
+ This is a supplement to the dbi module, allowing you to avoid hard-coding
3
+ passwords in your programs that make database connections. It can also
4
+ be used as a general password storage mechanism for other types of
5
+ connections, e.g. ssh, ftp, etc.
6
+
7
+ == Requirements
8
+ * sys-admin
9
+ * win32-file (MS Windows only)
10
+ * win32-dir (MS Windows only)
11
+ * win32-process (MS Windows only)
12
+
13
+ == Installation
14
+ gem install dbi-dbrc
15
+
16
+ == Synopsis
17
+ require 'dbi/dbrc'
18
+ include DBI
19
+
20
+ dbrc = DBRC.new('mydb')
21
+
22
+ or
23
+
24
+ dbrc = DBRC.new('mydb', 'someUser')
25
+
26
+ puts dbrc.db
27
+ puts dbrc.user
28
+ puts dbrc.driver
29
+ puts dbrc.timeout
30
+ puts dbrc.max_reconn
31
+ puts dbrc.interval
32
+ puts dbrc.dsn
33
+
34
+ == Notes on the .dbrc file
35
+ This module relies on a file in your home directory called ".dbrc", and it
36
+ is meant to be analogous to the ".netrc" file used by programs such as
37
+ telnet. The .dbrc file has several conditions that must be met by the
38
+ module or it will fail:
39
+
40
+ * Permissions must be set to 600 (Unix only).
41
+ * Must be hidden (MS Windows only).
42
+ * Must be owned by the current user.
43
+ * Must have database, user and password. Other fields are optional.
44
+ * Must be in the following space-separated format (in the 'plain' version):
45
+
46
+ database user password driver timeout maximum_reconnects interval
47
+
48
+ e.g. mydb dan mypass oracle 10 2 30
49
+
50
+ You may include comments in the .dbrc file by starting the line with a
51
+ "#" symbol.
52
+
53
+ A failure in any of the rules mentioned above will result in a DBRC::Error
54
+ being raised. In addition, the file may also be encrypted on MS Windows
55
+ systems, in which case the file will automatically be (temporarily)
56
+ decrypted.
57
+
58
+ The format for XML (using the example above) is as follows:
59
+
60
+ <dbrc>
61
+ <database name="mydb">
62
+ <user>dan</user>
63
+ <password>mypass</password>
64
+ <driver>oracle</driver>
65
+ <interval>30</interval>
66
+ <timeout>10</timeout>
67
+ <maximum_reconnects>2</maximum_reconnects>
68
+ </database>
69
+ </dbrc>
70
+
71
+ The format for YAML is as follows:
72
+
73
+ - mydb:
74
+ user: dan
75
+ password: mypass
76
+ driver: oracle
77
+ interval: 30
78
+ timeout: 10
79
+ max_reconn: 2
80
+
81
+ == Constants
82
+ VERSION
83
+ The current version of this library, returned as a String.
84
+
85
+ == Class Methods
86
+ DBRC.new(db, user=nil, dir=nil)
87
+ The constructor takes one to three arguments. The first argument is the
88
+ database name. This *must* be provided. If only the database name is
89
+ passed, the module will look for the first database entry in the .dbrc
90
+ file that matches.
91
+
92
+ The second argument, a user name, is optional. If it is passed, the
93
+ module will look for the first entry in the .dbrc file where both the
94
+ database *and* user name match.
95
+
96
+ The third argument, also optional, specifies the directory where DBRC will
97
+ look for the .dbrc file. By default, it looks in the pwuid (present
98
+ working user id) home directory. The rules for a .dbrc file still apply.
99
+
100
+ MS Windows users should read the "Notes" section for how your home directory
101
+ is determined.
102
+
103
+ == Instance Methods
104
+ DBRC#database
105
+ The name of the database. Note that the same entry can appear more than
106
+ once, presumably because you have multiple user id's for the same
107
+ database.
108
+
109
+ DBRC#db
110
+ An alias for DBRC#database.
111
+
112
+ DBRC#database=(database)
113
+ Sets the database to +database+. This is generally discouraged because
114
+ it does not automatically reset the dsn.
115
+
116
+ DBRC#db=(database)
117
+ An alias for DBRC#database=.
118
+
119
+ DBRC#user
120
+ A valid user name for that database.
121
+
122
+ DBRC#user=(user)
123
+ Sets the user name to +user+.
124
+
125
+ DBRC#password
126
+ The password for that user.
127
+
128
+ DBRC#passwd
129
+ An alias for DBRC#password.
130
+
131
+ DBRC#password=(password)
132
+ Sets the password to +password+.
133
+
134
+ DBRC#passwd=(password)
135
+ An alias for DBRC#password=.
136
+
137
+ DBRC#driver
138
+ The driver type for that database (Oracle, MySql, etc).
139
+
140
+ DBRC#driver=(driver)
141
+ Sets the driver to +driver+. This use is discouraged because it does
142
+ not reset the dsn.
143
+
144
+ DBRC#timeout
145
+ The timeout period for a connection before the attempt is dropped.
146
+
147
+ DBRC#time_out
148
+ An alias for DBRC#timeout, provided purely for the sake of backwards
149
+ compatability.
150
+
151
+ DBRC#timeout=(int)
152
+ Sets the timeout value to +int+.
153
+
154
+ DBRC#maximum_reconnects
155
+ The maximum number of reconnect attempts that should be made for the the
156
+ database. Presumablly, you would use this with a "retry" within a rescue
157
+ block.
158
+
159
+ DBRC#max_reconn
160
+ An alias for DBRC#maximum_reconnects.
161
+
162
+ DBRC#maximum_reconnects=(max)
163
+ Sets the maximum number of reconnect attempts to +max+.
164
+
165
+ DBRC#max_reconn=(max)
166
+ An alias for DBRC#maximum_reconnects.
167
+
168
+ DBRC#interval
169
+ The number of seconds to wait before attempting to reconnect to the database
170
+ again should a network/database glitch occur.
171
+
172
+ DBRC#interval=(int)
173
+ Sets the interval seconds between connection attempts.
174
+
175
+ DBRC#dsn
176
+ Returns a string in "dbi:<driver>:<database>" format.
177
+
178
+ DBRC#dsn=(dsn)
179
+ Sets the dsn string to +dsn+. This method is discouraged because it does
180
+ not automatically reset the driver or database.
181
+
182
+ == Canonical Example
183
+ # This is a basic template for how I do things:
184
+
185
+ require 'dbi/dbrc'
186
+ require 'timeout'
187
+
188
+ db = DBI::DBRC.new("somedb")
189
+ n = db.max_reconn
190
+
191
+ begin
192
+ Timeout.timeout(db.timeout){
193
+ DBI.connect(db.dsn, db.user, db.passwd)
194
+ }
195
+ rescue DBI::Error
196
+ n -= 1
197
+ if n > 0
198
+ sleep db.interval
199
+ retry
200
+ end
201
+ raise
202
+ rescue TimeoutError
203
+ # handle timeout error
204
+ end
205
+
206
+ == Notes for MS Windows Users
207
+ The 'home' directory for Win32 users is determined by ENV['USERPROFILE'].
208
+ If that is not set, ENV['HOME'] is used. If that is not set, then
209
+ the directory found by the sys-admin library is used.
210
+
211
+ To make your file hidden, right click on the .dbrc file in your Explorer
212
+ window, select "Properties" and check the "Hidden" checkbox.
213
+
214
+ I was going to require that the .dbrc file be encrypted on MS Windows,
215
+ but that may require an official "certificate", assigned to you by a third
216
+ party, which is a bit much to expect. However, if the file is encrypted,
217
+ DBRC will attempt to decrypt it, parse it, and encrypt it again when done
218
+ parsing.
219
+
220
+ == Notes on running the test suite
221
+ I cannot guarantee that the .dbrc files under the +examples+
222
+ subdirectories maintain the appropriate properties. This can cause
223
+ failures for the test suite (which uses these files).
224
+
225
+ The only solution is to perform a 'chmod 600 .dbrc' (on Unix) or set
226
+ the properties to 'hidden' (on MS Windows) manually, for the file in
227
+ question.
228
+
229
+ == Summary
230
+ These "methods" don't really do anything. They're simply meant as a
231
+ convenience mechanism for you dbi connections, plus a little bit of
232
+ obfuscation (for passwords).
233
+
234
+ == Adding your own configuration
235
+ If you want to add your own type of configuration file, you can still use
236
+ the dbi-dbrc library. All you need to do is:
237
+
238
+ * subclass DBRC
239
+ * redefine the +parse_dbrc_config_file+ method (a private method).
240
+
241
+ Take a look at the XML and YML subclasses in dbrc.rb for two examples that
242
+ you can work from.
243
+
244
+ == Future Plans
245
+ Add DBI::DBRC::JSON.
246
+
247
+ == Known Bugs
248
+ I'm not positive about the dsn strings for databases other than Oracle.
249
+ If it's not correct, please let me know.
250
+
251
+ == Copyright
252
+ (C) Copyright 2002-2013, Daniel J. Berger, all rights reserved.
253
+
254
+ = Warranty
255
+ This package is provided "as is" and without any express or
256
+ implied warranties, including, without limitation, the implied
257
+ warranties of merchantability and fitness for a particular purpose
258
+
259
+ == Author
260
+ Daniel J. Berger