dbi-dbrc 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 360d2807dbe54d14d421397476a8f5aa078ae2b6881fb33b9f9e86fd508c2eda
-  data.tar.gz: c93adb1f0fdc58885e9e18cdb01b656761684a8201ca8aa188af7769e8eda776
+  metadata.gz: 0ff5de96e8773faa52022e20fff1d008c360faa548ff65b9aac4a82b2a7e34b5
+  data.tar.gz: dc7c04ad5ee358f59fca1a1c6331907a62e94177cdcc0cc2912eef9e204817c1
 SHA512:
-  metadata.gz: 6db3ef1daa6494aa793df1ee029b7baa6c777d2185d70ce3c141fcf85f9d4b9f7cb55982828acc8d8111958ca65744534153324542fd53e563460fe73f525d6c
-  data.tar.gz: 380b6774c0e94754af1843e2b9a5067c814e6065c50a8f9a15053032d30b4d46204b7c984fe84ee9922eddf77499b74b6ac2e80c14424d26f135c3f171c92e29
+  metadata.gz: f5ca232636482744e5049a744b629f0fd7b956c511e3024d166ff633c68f3ca16fb089c2d5b126da676d09cc4cdf7ac11bc2b57a46c8b4f01846e4d982c6d9ab
+  data.tar.gz: 9296fac30f6fc8a811e5e8cc1468a97d6da9ccb9a8155caecd1e61dc177f1599087191412cdfc294403cb73d6300c0d72e46ed9ba7ecaab15e22bc8c36f65371

data/{CHANGES → CHANGES.md}

@@ -1,10 +1,16 @@
-== 1.4.1 - 14-Jan-2018
+## 1.5.0 - 12-Apr-2021
+* Switched from test-unit to rspec, with corresponding changes in the
+  gemspec and Rakefile.
+* Switched doc files to markdown format.
+* Added a Gemfile.
+ 
+## 1.4.1 - 14-Jan-2018
 * Fixed some test warnings.
 * Added metadata to gemspec.
 * The VERSION constant is now frozen.
 * Updated the cert, should be good for about 10 years.
 
-== 1.4.0 - 6-Dec-2015
+## 1.4.0 - 6-Dec-2015
 * Use Dir.home to calculate the home directory on Unixy platforms. Therefore
   Ruby 1.9.3 or later is now required.
 * The DBI::DBRC::YML class looks for "maximum_reconnects" instead of
@@ -13,37 +19,37 @@
 * Some gemspec and Rakefile updates.
 * Added a dbi-dbrc.rb file for convenience.
 
-== 1.3.0 - 3-Oct-2015
+## 1.3.0 - 3-Oct-2015
 * License changed to Apache 2.0.
 * Rakefile gem related tasks now assume Rubygems 2.x.
 * Added a certs file. This gem is now signed.
 
-== 1.2.0 - 8-Nov-2014
+## 1.2.0 - 8-Nov-2014
 * Updated dependency for MS Windows. Now uses win32-file-attributes instead
   of win32-file.
 * Minor updates to the Rakefile and gemspec.
 
-== 1.1.9 - 10-Jan-2013
+## 1.1.9 - 10-Jan-2013
 * Fixed an unused variable warning.
 * Changed the way I check for MS Windows.
 
-== 1.1.8 - 7-Oct-2010
+## 1.1.8 - 7-Oct-2010
 * Fixed a logic bug in the constructor that primarily affected MS Windows with
   regards to determining the user's home directory.
 
-== 1.1.7 - 6-Oct-2010
+## 1.1.7 - 6-Oct-2010
 * More robust file decryption/encryption for MS Windows.
 * Better platform checking for MS Windows.
 * Refactored the Rakefile. Removed the old installation tasks and replaced
   them with a series of gem tasks.
 * Updated the win32 library dependencies.
 
-== 1.1.6 - 10-Sep-2009
+## 1.1.6 - 10-Sep-2009
 * Fixed validation for dbrc_dir argument.
 * Added a test for bogus dbrc_dir arguments.
 
-== 1.1.5 - 3-Sep-2009
-* License changed to Artistic 2.0.
+## 1.1.5 - 3-Sep-2009
+* License changed to Artistic-2.0.
 * Some gemspec updates, including the license and description.
 * Renamed the test files. The ts_all.rb file was removed.
 * Added win32-process as a dependency on MS Windows.
@@ -53,24 +59,24 @@
 * Refactored the main test task.
 * Added explicit copyright and warranty to the README file.
 
-== 1.1.4 - 10-Nov-2008
+## 1.1.4 - 10-Nov-2008
 * Added a custom inspect method which filters the password.
 
-== 1.1.3 - 21-Jul-2008
+## 1.1.3 - 21-Jul-2008
 * More RUBY_PLATFORM changes that I missed in the last release.
 * Added inline RDOC for the accessors and updated the documentation
   for the constructor.
 * Added the DBI::DBRC#dbrc_dir and DBI::DBRC#dbrc_file methods.
 * More tests.
 
-== 1.1.2 - 18-Jul-2008
+## 1.1.2 - 18-Jul-2008
 * Changed platform checking from RUBY_PLATFORM to Config::CONFIG['host_os']
   so that other implementations won't choke.
 * Updated the gemspec to add the sys-admin dependency.
 * Added a rubyforge_project to the gemspec.
 * Now has a separate gem for MS Windows.
 
-== 1.1.1 - 2-Aug-2007
+## 1.1.1 - 2-Aug-2007
 * DBRCError is now DBRC::Error.
 * Added a Rakefile with tasks for installation and testing.
 * Added the win32-dir library as a prerequisite for MS Windows.
@@ -79,21 +85,21 @@
   warnings that appeared when run with -w.
 * Some doc and test updates.
 
-== 1.1.0 - 19-Oct-2005
+## 1.1.0 - 19-Oct-2005
 * Bug fix for MS Windows (there's no Win32 namespace for win32/file).
 * Changed platform detection mechanism.
 
-== 1.0.1 - 7-Oct-2005
+## 1.0.1 - 7-Oct-2005
 * Improved the error message when an entry isn't found.
 
-== 1.0.0 - 15-Jun-2005
+## 1.0.0 - 15-Jun-2005
 * Ditches the use of 'etc'.  Now requires the 'sys-admin' package as its
   replacement (for all platforms).
 * Moved project to RubyForge.
 * Minor updates to tests, README and gemspec.
 * Now hosted on RubyForge.
 
-== 0.5.1 - 17-Mar-2005
+## 0.5.1 - 17-Mar-2005
 * Removed the 'doc' directory completely, and moved the primary
   documentation into the README file.
 * Removed the INSTALL file.  Moved the installation directions into the
@@ -102,7 +108,7 @@
 * Made the README and CHANGES files rdoc friendly.
 * Added a gemspec.
 
-== 0.5.0 - 15-Oct-2004
+## 0.5.0 - 15-Oct-2004
 * Added a YAML subclass.  Use this if you want to store your information in
   the .dbrc file in YAML format.
 * On Win32 systems, the .dbrc file must now be "hidden".  Also, it will
@@ -119,19 +125,19 @@
   using rdtool.
 * Test suite changes.
 
-== 0.4.0 - 3-Sep-2004
+## 0.4.0 - 3-Sep-2004
 * Removed redundant error handling for cases when the database and/or login
   are not found.
 * Added an XML subclass.  Use this if you want to store your information in
   the .dbrc file in XML format.
 
-== 0.3.0 - 26-Oct-2003
+## 0.3.0 - 26-Oct-2003
 * Win32 support added.  Requires the win32-etc package.
 * rd doc separated from source.  Moved to 'doc' directory.
 * Documentation updates and corrections.
 * Minor test suite tweaks for Win32 systems.
 
-== 0.2.1 - 28-Aug-2003
+## 0.2.1 - 28-Aug-2003
 * Removed VERSION class method.  Just use the constant.
 * Bug fix with regards to split and Ruby 1.8.  Thanks Michael Garriss.
 * Changed 'changelog' to 'CHANGES'.
@@ -140,7 +146,7 @@
 * Test unit cleanup
 * Minor internal directory layout and doc changes
 
-== 0.2.0 - 13-Jan-2003
+## 0.2.0 - 13-Jan-2003
 * DBRC class now under the DBI module namespace
 * Changed "timeout" to "time_out" to avoid confusion with the timeout
   module.
@@ -162,9 +168,9 @@
 * Install script improved
 * Documentation additions, including plain text doc
 
-== 0.1.1 - 26-Jul-2002
+## 0.1.1 - 26-Jul-2002
 * Added 'dsn()' method
 * Minor documentation additions
 
-== 0.1.0 - 26-Jul-2002
+## 0.1.0 - 26-Jul-2002
 * Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org' do
+  gemspec
+end

data/{MANIFEST → MANIFEST.md}

@@ -1,6 +1,6 @@
-* MANIFEST
-* CHANGES
-* README
+* CHANGES.md
+* MANIFEST.md
+* README.md
 * Rakefile
 * dbi-dbrc.gemspec
 * certs/djberg96_pub.pem
@@ -11,6 +11,6 @@
 * examples/xml_examples/test_xml.rb
 * examples/yml_examples/.dbrc
 * examples/yml_examples/test_yml.rb
-* test/test_dbi_dbrc.rb
-* test/test_dbi_dbrc_xml.rb
-* test/test_dbi_dbrc_yml.rb
+* spec/dbi_dbrc_spec.rb
+* spec/dbi_dbrc_xml_spec.rb
+* spec/dbi_dbrc_yml_spec.rb

data/README.md

@@ -0,0 +1,292 @@
+## Description
+This is a supplement to the dbi library, allowing you to avoid hard-coding
+passwords in your programs that make database connections. It can also
+be used as a general password storage mechanism for other types of
+connections, e.g. ssh, ftp, etc.
+
+## Requirements
+For most platforms there are no additional requirements. However, for MS
+Windows there are these additional requirements:
+
+* sys-admin
+* win32-file-attributes
+* win32-dir
+* win32-process
+
+## Installation
+`gem install dbi-dbrc`
+
+## Synopsis
+```ruby
+require 'dbi/dbrc'
+
+dbrc = DBI::DBRC.new('mydb') # or...
+dbrc = DBI::DBRC.new('mydb', 'someUser')
+
+puts dbrc.db
+puts dbrc.user
+puts dbrc.driver
+puts dbrc.timeout
+puts dbrc.max_reconn
+puts dbrc.interval
+puts dbrc.dsn
+```
+
+## Notes on the .dbrc file
+This module relies on a file in your home directory called ".dbrc", and it
+is meant to be analogous to the ".netrc" file used by programs such as
+telnet. The .dbrc file has several conditions that must be met by the
+module or it will fail:
+
+* Permissions must be set to 600 (Unix only).
+* Must be hidden (MS Windows only).
+* Must be owned by the current user.
+* Must have database, user and password. Other fields are optional.
+* Must be in the following space-separated format (in the 'plain' version):
+
+```
+  database user password driver timeout maximum_reconnects interval
+  # e.g. mydb     dan    mypass     oracle   10        2         30
+```
+
+You may include comments in the .dbrc file by starting the line with a
+"#" symbol.
+
+A failure in any of the rules mentioned above will result in a `DBRC::Error`
+being raised. In addition, the file may also be encrypted on MS Windows
+systems, in which case the file will automatically be (temporarily)
+decrypted.
+
+The format for XML (using the example above) is as follows:
+
+```xml
+<dbrc>
+ <database name="mydb">
+   <user>dan</user>
+   <password>mypass</password>
+   <driver>oracle</driver>
+   <interval>30</interval>
+   <timeout>10</timeout>
+   <maximum_reconnects>2</maximum_reconnects>
+ </database>
+</dbrc>
+```
+
+The format for YAML is as follows:
+
+```yaml
+- mydb:
+  user: dan
+  password: mypass
+  driver: oracle
+  interval: 30
+  timeout: 10
+  max_reconn: 2
+```
+   
+## Constants
+`VERSION`
+
+The current version of this library, returned as a String.
+    
+## Class Methods
+`DBRC.new(db, user=nil, dir=nil)`
+
+The constructor takes one to three arguments. The first argument is the
+database name. This *must* be provided. If only the database name is
+passed, the module will look for the first database entry in the .dbrc
+file that matches.
+
+The second argument, a user name, is optional. If it is passed, the
+module will look for the first entry in the .dbrc file where both the
+database *and* user name match.
+
+The third argument, also optional, specifies the directory where DBRC will
+look for the .dbrc file. By default, it looks in the pwuid (present
+working user id) home directory. The rules for a .dbrc file still apply.
+
+MS Windows users should read the "Notes" section for how your home directory
+is determined.
+    
+## Instance Methods
+`DBRC#database`
+
+The name of the database. Note that the same entry can appear more than
+once, presumably because you have multiple user id's for the same database.
+    
+`DBRC#db`
+
+An alias for DBRC#database.
+    
+`DBRC#database=(database)`
+
+Sets the database to +database+. This is generally discouraged because
+it does not automatically reset the dsn.
+    
+`DBRC#db=(database)`
+
+An alias for DBRC#database=.
+   
+`DBRC#user`
+
+A valid user name for that database.
+    
+`DBRC#user=(user)`
+
+Sets the user name to +user+.
+    
+`DBRC#password`
+
+The password for that user.
+    
+`DBRC#passwd`
+
+An alias for DBRC#password.
+    
+`DBRC#password=(password)`
+
+Sets the password to +password+.
+
+`DBRC#passwd=(password)`
+
+An alias for DBRC#password=.
+    
+`DBRC#driver`
+
+The driver type for that database (Oracle, MySql, etc).
+    
+`DBRC#driver=(driver)`
+
+Sets the driver to +driver+.  This use is discouraged because it does not reset the dsn.
+    
+`DBRC#timeout`
+
+The timeout period for a connection before the attempt is dropped.
+   
+`DBRC#time_out`
+
+An alias for DBRC#timeout, provided purely for the sake of backwards compatability.
+    
+`DBRC#timeout=(int)`
+
+Sets the timeout value to +int+.
+   
+`DBRC#maximum_reconnects`
+
+The maximum number of reconnect attempts that should be made for the the
+database. Presumablly, you would use this with a "retry" within a rescue block.
+
+`DBRC#max_reconn`
+
+An alias for DBRC#maximum_reconnects.
+   
+`DBRC#maximum_reconnects=(max)`
+
+Sets the maximum number of reconnect attempts to +max+.
+
+`DBRC#max_reconn=(max)`
+
+An alias for DBRC#maximum_reconnects.
+    
+`DBRC#interval`
+
+The number of seconds to wait before attempting to reconnect to the database
+again should a network/database glitch occur.
+    
+`DBRC#interval=(int)`
+
+Sets the interval seconds between connection attempts.
+    
+`DBRC#dsn`
+
+Returns a string in "dbi:<driver>:<database>" format.
+    
+`DBRC#dsn=(dsn)`
+
+Sets the dsn string to +dsn+.  This method is discouraged because it does
+not automatically reset the driver or database.
+    
+## Canonical Example
+```ruby
+# This is a basic template for how I do things:
+
+require 'dbi/dbrc'
+require 'timeout'
+
+db = DBI::DBRC.new("somedb")
+n = db.max_reconn
+
+begin
+  Timeout.timeout(db.timeout){
+    DBI.connect(db.dsn, db.user, db.passwd)
+  }
+rescue DBI::Error
+  n -= 1
+  if n > 0
+    sleep db.interval
+    retry
+  end
+  raise
+rescue TimeoutError
+ # handle timeout error
+end
+```
+
+## Notes for MS Windows Users
+The `home` directory for Win32 users is determined by `ENV['USERPROFILE']`.
+If that is not set then `ENV['HOME']` is used. If that is not set, then
+the directory found by the sys-admin library is used.
+
+To make your file hidden, right click on the .dbrc file in your Explorer
+window, select "Properties" and check the "Hidden" checkbox.
+
+I was going to require that the .dbrc file be encrypted on MS Windows,
+but that may require an official "certificate", assigned to you by a third
+party, which is a bit much to expect. However, if the file is encrypted,
+DBRC will attempt to decrypt it, parse it, and encrypt it again when done
+parsing.
+
+## Notes on running the test suite
+I cannot guarantee that the .dbrc files under the `examples`
+subdirectories maintain the appropriate properties. This can cause
+failures for the test suite (which uses these files).
+
+The only solution is to perform a `chmod 600 .dbrc` (on Unix) or set
+the properties to 'hidden' (on MS Windows) manually, for the file in
+question.
+   
+## Summary
+These "methods" don't really do anything. They're simply meant as a
+convenience mechanism for you dbi connections, plus a little bit of
+obfuscation (for passwords).
+
+## Adding your own configuration
+If you want to add your own type of configuration file, you can still use
+the dbi-dbrc library. All you need to do is:
+
+* subclass DBRC
+* redefine the `parse_dbrc_config_file` method (a private method).
+
+Take a look at the XML and YML subclasses in dbrc.rb for two examples that
+you can work from.
+   
+## Future Plans
+Add DBI::DBRC::JSON.
+   
+## Known Bugs
+I'm not positive about the dsn strings for databases other than Oracle.
+If it's not correct, please let me know.
+   
+## Copyright
+(C) Copyright 2002-2021, Daniel J. Berger, all rights reserved.
+
+## License
+Apache-2.0
+   
+## Warranty
+This package is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantability and fitness for a particular purpose
+   
+## Author
+Daniel J. Berger