dbi-dbrc 1.3.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 67a3a14643684c577916f199d8e356d33392390a
-  data.tar.gz: d846477c348cc70e508da67600a74d6f1e8f5808
+SHA256:
+  metadata.gz: 813eb7a49bd78983624e1e91031b3f93d83a872a1edea9bc2a1bced57985af9a
+  data.tar.gz: f9a2a4b40d14ecdc5e36b02c8c8c14c5e5bf47cf34400f365b9e4b23b03a540c
 SHA512:
-  metadata.gz: f56a3dbcdab4caaf4bdd33996d8939c3a607a01238fde3819b214f5836cdc018c6cc62a806ad63a3716c1af9cd33383e2e186e5b704cf93f10305ed2e5259e61
-  data.tar.gz: fb15eb083cad740e86d68174db035b11b182bee5a5cdd6a75e77b016311460a43cddace9b5786885e058c4f916faaa966f6bbe7870982055aae3f2f998a9ab4b
+  metadata.gz: b46c7b59855bfa381213fa8ce30d31dbe4646811a6fd085ec698a1d6d3504eda6838a9693355ee958fd13e5aad679b6f2f5a060050cfaa64a45ec5214e84c4ab
+  data.tar.gz: 7f222c7eda45b449a59ecff9fb6c9631ac3dd54e59f3c12a858333ba478a1fa1f4e0269bd96a4453c320a56c47826e49da2994656caa1e61bebbde78e5d54a80

data/{CHANGES → CHANGES.md}

@@ -1,34 +1,68 @@
-== 1.3.0 - 3-Oct-2015
+## 1.7.0 - 19-Jun-2021
+* Added a DBI::DBRC::JSON subclass, and corresponding specs, so you can now
+  store information in JSON format.
+* Updated and/or removed old information from the README file.
+
+## 1.6.0 - 9-Jun-2021
+* Now supports gpg encrypted files, with a 4th optional parameter where you
+  can pass gpg options (usually a password, but whatever gpgme supports).
+* Added gpgme as a dependency.
+* Updated specs for MS Windows.
+* The "home" handling is now a bit simpler, as it was originally written
+  before that method existed in core Ruby.
+
+## 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
+* 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
+  "max_reconn" to be consistent with the other classes.
+* Aliases are now universal for all classes.
+* Some gemspec and Rakefile updates.
+* Added a dbi-dbrc.rb file for convenience.
+
+## 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.
@@ -38,24 +72,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.
@@ -64,21 +98,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
@@ -87,7 +121,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
@@ -104,19 +138,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'.
@@ -125,7 +159,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.
@@ -147,9 +181,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,16 +1,20 @@
-* MANIFEST
-* CHANGES
-* README
+* CHANGES.md
+* MANIFEST.md
+* README.md
 * Rakefile
 * dbi-dbrc.gemspec
 * certs/djberg96_pub.pem
 * lib/dbi/dbrc.rb
+* lib/dbi/dbrc/json.rb
+* lib/dbi/dbrc/xml.rb
+* lib/dbi/dbrc/yaml.rb
 * examples/plain/.dbrc
 * examples/plain/test.rb
 * examples/xml_examples/.dbrc
 * 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_json_spec.rb
+* spec/dbi_dbrc_xml_spec.rb
+* spec/dbi_dbrc_yml_spec.rb

data/README.md

@@ -0,0 +1,307 @@
+## Description
+This is essentially a database connection configuration library, allowing you
+to avoid hard-coding passwords in your programs, and store other generalized
+information, when making database connections.
+
+It can also be used as a general password storage manager for other types of
+connections, e.g. ssh, ftp, etc.
+
+The name was originally based on the old DBI library (which in turn was based
+on the Perl library of the same name), and was originally meant as a supplement
+to that library. The DBI library is now defunct, but it not necessary to use
+this library. But, that explains why there's an outer "DBI" namespace module.
+
+## Requirements
+* gpgme - For GPG encrypted files (which you should be doing).
+
+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 somewhere on your filesystem (normally 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
+```
+
+The format for JSON is as follows:
+
+```json
+[
+  {
+    "foo": {
+      "user": "dan",
+      "password": "mypass",
+      "driver": "oracle",
+      "interval": 30,
+      "timeout": 10,
+      "maximum_reconnects": 2
+    }
+  }
+]
+```
+   
+## Constants
+`VERSION`
+
+The current version of this library, returned as a String.
+    
+## Class Methods
+`DBRC.new(db, user = nil, dir = nil, gpg_options = 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.
+
+The fourth argument, if present, are options that are forwarded to the
+`GPGME::Crypto.new` constructor for GPG encrypted files. Typically this
+would at least be the :password option, but YMMV.
+
+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'
+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
+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.
+
+## Summary
+These methods don't really "do" anything. They're simply meant as a
+convenience mechanism for your database 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
+None at this time.
+   
+## 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