README in dbi-dbrc-1.1.0 vs README in dbi-dbrc-1.1.1

- old
+ new

@@ -1,18 +1,24 @@ == Description This is a supplement to the dbi module, allowing you to avoid hard-coding passwords in your programs that make database connections. +== Requirements + * Ruby 1.8.2 or later + * sys-admin + * win32-file (MS Windows only) + * win32-dir (MS Windows only) + == Synopsis require 'dbi/dbrc' include DBI - dbrc = DBRC.new("mydb") + dbrc = DBRC.new('mydb') or - dbrc = DBRC.new("mydb","someUser") + dbrc = DBRC.new('mydb', 'someUser') puts dbrc.db puts dbrc.user puts dbrc.driver puts dbrc.timeout @@ -20,45 +26,37 @@ puts dbrc.interval puts dbrc.dsn dbh = DBI.connect(dbrc.dsn, dbrc.user, dbrc.password) -== Requirements - * Ruby 1.8.0 or later - * sys-admin - * win32-file (Win32 only) - == Installation -=== Manual Installation - * ruby test/ts_all.rb (optional) - * ruby install.rb -=== Gem Installation - * ruby dbi-dbrc.gemspec - * gem install dbi-dbrc-<version>.gem + rake test (optional) + rake install (non-gem) or rake install_gem (gem) == 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 (Win32 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 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 + "#" symbol. - A failure in any of the rules mentioned above will result in a DBRCError - being raised. In addition, the file may also be encrypted on Win32 systems, - in which case the file will automatically be (temporarily) decrypted. + 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: <dbrc> <database name="mydb"> @@ -85,29 +83,29 @@ VERSION The current version of this packages, 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 + 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 + 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. + 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. - Win32 users should read the "Notes" section for how your home directory + 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 + 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. @@ -181,73 +179,72 @@ 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 - This is a basic template for how I do things: + # This is a basic template for how I do things: - require "dbi/dbrc" - require "timeout" + require 'dbi/dbrc' + require 'timeout' db = DBI::DBRC.new("somedb") n = db.max_reconn begin timeout(db.time_out){ - DBI.connect(db.dsn,db.user,db.passwd) + DBI.connect(db.dsn, db.user, db.passwd) } rescue DBI::Error n -= 1 sleep db.interval if n > 0 retry if n > 0 raise rescue TimeoutError # handle timeout error end - -== Notes for Win32 Users + +== Notes for MS Windows Users The 'home' directory for Win32 users is determined by ENV['USERPROFILE']. - If that is not set, ENV['HOME'] is used. If that is not set, then - 'C:\Documents and Settings\' + Admin.get_user(Admin.get_login).home_dir is - used. + If that is not set, ENV['HOME'] is used. If that is not set, then + 'C:\Documents and Settings\user_name' 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 Win32 systems, + 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, + 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 + 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 + 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 package. All you need to do is: + the dbi-dbrc package. All you need to do is: * subclass DBRC - * redefine the +parse_dbrc_config_file+ method + * 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. == Known Bugs I'm not positive about the dsn strings for databases other than Oracle. If it's not correct, please let me know. == Author Daniel J. Berger - djberg96 at gmail dot com + djberg96 at nospam at gmail dot com imperator on IRC (irc.freenode.net)