Permalink
Browse files

Improve documentation.

  • Loading branch information...
rsutphin committed Aug 29, 2011
1 parent 61c9931 commit a7c34ce28f80240d8fec066c252b76a63317be3e
Showing with 120 additions and 43 deletions.
  1. +2 −1 .gitignore
  2. +5 −0 .yardopts
  3. +16 −13 CHANGELOG.markdown
  4. +6 −0 Gemfile
  5. +60 −17 README.markdown
  6. +0 −9 Rakefile
  7. +6 −3 bcdatabase.gemspec
  8. +25 −0 lib/bcdatabase.rb
View
@@ -1,5 +1,6 @@
pkg
coverage
Gemfile.lock
-rdoc
+doc
reports
+.yardoc
View
@@ -0,0 +1,5 @@
+--no-private
+--markup markdown
+--hide-void-return
+--files CHANGELOG.markdown
+--readme README.markdown
View
@@ -1,58 +1,61 @@
+Bcdatabase history
+==================
+
1.0.7
-=====
+-----
1.0.6
-=====
+-----
- Use `ENV['RAILS_ENV']` instead of the unreliable `RAILS_ENV` constant.
1.0.5
-=====
+-----
- Loosen highline dependency so that bcdatabase can be used in buildr buildfiles.
1.0.4
-=====
+-----
- Fix command line utilities that were broken in 1.0.3 due to
inadequate test coverage. (GH-4)
1.0.3
-=====
+-----
- Support ActiveSupport 3. ActiveSupport 2 continues to work.
1.0.2
-=====
+-----
- Tighten up gemspec gem deps. Bcdatabase does not currently work
with ActiveSupport 3.
1.0.1
-=====
+-----
- Update some old syntax for ruby 1.9 compatibility (David Yip)
1.0.0
-=====
+-----
- Split out from NUBIC internal `bcdatabase` project.
(Changelog entries below reflect the relevant changes & version numbers from that project.)
0.4.1
-=====
+-----
- Fix `bcdatabase encrypt` so that it doesn't re-encrypt already encrypted
epassword entries.
0.4.0
-=====
+-----
- Use the YAML entry name as the "database" value if no other value is
provided. This is to DRY up PostgreSQL configurations where the username
(already defaulted) and the database name are the same.
0.2.0
-=====
+-----
- Change default encrypted secret password location
0.1.0
-=====
+-----
- Support encrypted passwords
- Command-line utility (also called bcdatabase) for creating encrypted passwords
- Gem distribution
0.0.0
-=====
+-----
Original release.
View
@@ -12,3 +12,9 @@ if ENV['ACTIVESUPPORT_VERSION']
gem 'activesupport', version
end
+
+group :development do
+ # For yard's markdown support
+ platforms :jruby do; gem 'maruku'; end
+ platforms :ruby_18, :ruby_19 do; gem 'rdiscount'; end
+end
View
@@ -1,7 +1,14 @@
-bcdatabase
+Bcdatabase
==========
-*bcdatabase* is a library and utility which provides database configuration parameter management for Ruby on Rails applications. It provides a simple mechanism for separating database configuration attributes from application source code so that there's no temptation to check passwords into the version control system. And it centralizes the parameters for a single server so that they can be easily shared among multiple applications and easily updated by a single administrator.
+*Bcdatabase* is a library and utility which provides database
+configuration parameter management for Ruby on Rails applications. It
+provides a simple mechanism for separating database configuration
+attributes from application source code so that there's no temptation
+to check passwords into the version control system. And it
+centralizes the parameters for a single server so that they can be
+easily shared among multiple applications and easily updated by a
+single administrator.
## Installing bcdatabase
@@ -29,7 +36,10 @@ A bog-standard rails application's `config/database.yml` file looks like this:
username: cfg_animal
password: very-secret
-Rails allows this file to contain [ERB][]. `bcdatabase` uses ERB to replace an entire configuration block. If you wanted to replace, say, just the production block in this example, you would transform it like so:
+Rails allows this file to contain [ERB][]. `bcdatabase` uses ERB to
+replace an entire configuration block. If you wanted to replace, say,
+just the production block in this example, you would transform it like
+so:
<%
require 'bcdatabase'
@@ -50,7 +60,9 @@ Rails allows this file to contain [ERB][]. `bcdatabase` uses ERB to replace an
<%= bcdb.production :prod, :cfg_animal %>
-This means "create a YAML block for the *production* environment from the configuration entry named *cfg_animal* in /etc/nubic/db/*prod*.yml." The method called can be anything:
+This means "create a YAML block for the *production* environment from
+the configuration entry named *cfg_animal* in
+/etc/nubic/db/*prod*.yml." The method called can be anything:
<%= bcdb.development :local, :cfg_animal %>
<%= bcdb.staging 'stage', 'cfg_animal' %>
@@ -60,21 +72,33 @@ This means "create a YAML block for the *production* environment from the config
## Directly accessing configuration parameters from bcdatabase
-More rarely, you might need to access the actual configuration hash, instead of the YAMLized version. You can access it by invoking `Bcdatabase.load` as shown earlier, then using the bracket operator to specify the configuration you want:
+More rarely, you might need to access the actual configuration hash,
+instead of the YAMLized version. You can access it by invoking
+`Bcdatabase.load` as shown earlier, then using the bracket operator to
+specify the configuration you want:
bcdb[:local, :cfg_animal]
-The resulting hash is suitable for passing to `ActiveRecord::Base.establish_connection`, for instance.
+The resulting hash is suitable for passing to
+`ActiveRecord::Base.establish_connection`, for instance.
## Central configuration files
-The database configuration properties for all the applications on a server are stored in one or more files under `/etc/nubic/db` (by default; see "File locations" below). Each one is a standard YAML file, similar to rails' `database.yml` but with a few enhancements:
+The database configuration properties for all the applications on a
+server are stored in one or more files under `/etc/nubic/db` (by
+default; see "File locations" below). Each one is a standard YAML
+file, similar to rails' `database.yml` but with a few enhancements:
-* Each file can have a defaults entry which provides attributes which are shared across all configurations in the file
-* Each entry defaults its "username" attribute to the name of the entry (useful for Oracle)
-* Each entry defaults its "database" attribute to the name of the entry (useful for PostgreSQL)
+* Each file can have a defaults entry which provides attributes which
+ are shared across all configurations in the file
+* Each entry defaults its "username" attribute to the name of the
+ entry (useful for Oracle)
+* Each entry defaults its "database" attribute to the name of the
+ entry (useful for PostgreSQL)
-Since each file can define a set of default properties which are shared by all the contained configurations, it makes sense to group databases which have some shared configuration elements.
+Since each file can define a set of default properties which are
+shared by all the contained configurations, it makes sense to group
+databases which have some shared configuration elements.
### Example
@@ -105,13 +129,24 @@ and `:bcstage, :personnel`:
## Obscuring passwords
-bcdatabase supports storing encrypted passwords instead of the plaintext ones shown in the previous example. Encrypted passwords are defined with the key `epassword` instead of `password`. The library will decrypt the `epassword` value and expose it to the calling code (usually rails) unencrypted under the `password` key. The `bcdatabase` command line utility handles encrypting passwords; see the next section.
+bcdatabase supports storing encrypted passwords instead of the
+plaintext ones shown in the previous example. Encrypted passwords are
+defined with the key `epassword` instead of `password`. The library
+will decrypt the `epassword` value and expose it to the calling code
+(usually rails) unencrypted under the `password` key. The
+`bcdatabase` command line utility handles encrypting passwords; see
+the next section.
-While the passwords are technically encrypted, the master key must be stored on the same machine so that they can be decrypted on demand. That means this feature only obscures passwords &mdash; it will not deter a determined attacker.
+While the passwords are technically encrypted, the master key must be
+stored on the same machine so that they can be decrypted on demand.
+That means this feature only obscures passwords &mdash; it will not
+deter a determined attacker.
## `bcdatabase` command line utility
-The gem includes a command line utility (also called `bcdatabase`) which assists with creating `epassword` entries. It has online help; after installing the gem, try `bcdatabase help` to read it:
+The gem includes a command line utility (also called `bcdatabase`)
+which assists with creating `epassword` entries. It has online help;
+after installing the gem, try `bcdatabase help` to read it:
$ bcdatabase help
usage: bcdatabase <command> [args]
@@ -123,15 +158,23 @@ The gem includes a command line utility (also called `bcdatabase`) which assists
## File locations
-`/etc/nubic/db` is the default place the library will look for the central configuration files. It may be overridden with the environment variable `BCDATABASE_PATH`. For instance, if you wanted to keep these files in your home directory on your development machine &mdash; perhaps so that editing them doesn't require elevated privileges &mdash; you could add this to `~/.bashrc`:
+`/etc/nubic/db` is the default place the library will look for the
+central configuration files. It may be overridden with the
+environment variable `BCDATABASE_PATH`. For instance, if you wanted
+to keep these files in your home directory on your development machine
+&mdash; perhaps so that editing them doesn't require elevated
+privileges &mdash; you could add this to `~/.bashrc`:
export BCDATABASE_PATH=${HOME}/nubic/db
-Similarly, the file containing the encryption password has a sensible default location, but that location can be overridden by setting `BCDATABASE_PASS`.
+Similarly, the file containing the encryption password has a sensible
+default location, but that location can be overridden by setting
+`BCDATABASE_PASS`.
## Credits
-`bcdatabase` was developed at and for the [Northwestern University Biomedical Informatics Center][NUBIC].
+`bcdatabase` was developed at and for the [Northwestern University
+Biomedical Informatics Center][NUBIC].
[NUBIC]: http://www.nucats.northwestern.edu/centers/nubic/index.html
View
@@ -5,15 +5,6 @@ require 'rake/rdoctask'
require 'spec/rake/spectask'
require 'ci/reporter/rake/rspec'
-Rake::RDocTask.new do |rdoc|
- version = Bcdatabase::VERSION
-
- rdoc.rdoc_dir = 'rdoc'
- rdoc.title = "bcdatabase #{version}"
- rdoc.rdoc_files.include('README*')
- rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
Spec::Rake::SpecTask.new(:spec) do |spec|
spec.libs << 'lib' << 'spec'
spec.spec_files = FileList['spec/**/*_spec.rb']
View
@@ -7,20 +7,23 @@ Gem::Specification.new do |s|
s.name = 'bcdatabase'
s.version = Bcdatabase::VERSION
s.summary = %Q{Server-central database configuration for rails and other ruby apps}
- s.description = %Q{bcdatabase is a tool for storing passwords and other database configuration information outside of your application source tree.}
+ s.description = %Q{bcdatabase is a tool for storing passwords and other configuration information outside of your application source tree.}
s.email = "rhett@detailedbalance.net"
- s.homepage = "http://github.com/rsutphin/bcdatabase"
+ s.homepage = "http://github.com/NUBIC/bcdatabase"
s.authors = ["Rhett Sutphin"]
s.require_paths = ["lib"]
s.executables = ['bcdatabase']
- s.files = Dir.glob("{CHANGELOG.markdown,LICENSE,README.markdown,{bin,lib}/**/*}")
+ s.files = Dir.glob("{CHANGELOG.markdown,LICENSE,README.markdown,bcdatabase.gemspec,{bin,lib}/**/*}")
s.add_dependency "activesupport", ">= 2.0"
s.add_dependency "highline", "~> 1.5"
s.add_dependency "i18n"
+ s.add_development_dependency 'bundler', '~> 1.0.15'
+ s.add_development_dependency 'rake', '~> 0.9.2'
s.add_development_dependency 'rspec', "~> 1.2"
s.add_development_dependency "ci_reporter", "~> 1.6"
+ s.add_development_dependency 'yard', '~> 0.7.2'
end
View
@@ -12,16 +12,26 @@ module Bcdatabase
CIPHER = 'aes-256-ecb'
class << self
+ ##
+ # The main entry point for Bcdatabase.
+ #
+ # @return [DatabaseConfigurations] a new instance reflecting
+ # either the passed-in path, the location indicated by
+ # `BCDATABASE_PATH` in the environment, or the default location.
def load(path=nil)
path ||= base_path
files = Dir.glob(File.join(path, "*.yml")) + Dir.glob(File.join(path, "*.yaml"))
DatabaseConfigurations.new(files)
end
+ ##
+ # @private exposed for collaboration
def encrypt(s)
Base64.encode64(encipher(:encrypt, s)).strip
end
+ ##
+ # @private exposed for collaboration
def decrypt(s)
encipher(:decrypt, Base64.decode64(s))
end
@@ -59,7 +69,14 @@ def base_path
end
end
+ ##
+ # The set of groups and entries returned by one call to {Bcdatabase.load}.
class DatabaseConfigurations
+ ##
+ # Creates a configuration from a set of YAML files.
+ #
+ # General use of the library should not use this method, but
+ # instead should use {Bcdatabase.load}.
def initialize(files)
@files = files
@map = { }
@@ -69,10 +86,18 @@ def initialize(files)
end
end
+ ##
+ # @return [Hash] the entry for the given group and name after all
+ # transformation is complete.
def [](groupname, dbname)
create_entry(groupname.to_s, dbname.to_s)
end
+ ##
+ # This method implements the Rails database.yml integration
+ # described in full in the {file:README.markdown}.
+ #
+ # @return [String] a YAMLized view of a configuration entry.
def method_missing(name, *args)
groupname = (args[0] or raise "Database configuration group not specified for #{name}")
dbname = (args[1] or raise "Database entry name not specified for #{name}")

0 comments on commit a7c34ce

Please sign in to comment.