Skip to content

Commit fe9fb19

Browse files
rsutphinrsutphin
committed
Extract version 1.0.0 from NUBIC's internal bcdatabase gem.
0 parents  commit fe9fb19

12 files changed

+918
-0
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.gemspec
2+
pkg
3+
coverage

‎CHANGELOG.markdown

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
1.0.0
2+
=====
3+
- Split out from NUBIC internal `bcdatabase` project.
4+
(Changelog entries below reflect the relevant changes & version numbers from that project.)
5+
6+
0.4.1
7+
=====
8+
- Fix `bcdatabase encrypt` so that it doesn't re-encrypt already encrypted
9+
epassword entries.
10+
11+
0.4.0
12+
=====
13+
- Use the YAML entry name as the "database" value if no other value is
14+
provided. This is to DRY up PostgreSQL configurations where the username
15+
(already defaulted) and the database name are the same.
16+
17+
0.2.0
18+
=====
19+
- Change default encrypted secret password location
20+
21+
0.1.0
22+
=====
23+
- Support encrypted passwords
24+
- Command-line utility (also called bcdatabase) for creating encrypted passwords
25+
- Gem distribution
26+
27+
0.0.0
28+
=====
29+
Original release.

‎LICENSE

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Copyright (c) 2009 Rhett Sutphin
2+
3+
Permission is hereby granted, free of charge, to any person obtaining
4+
a copy of this software and associated documentation files (the
5+
"Software"), to deal in the Software without restriction, including
6+
without limitation the rights to use, copy, modify, merge, publish,
7+
distribute, sublicense, and/or sell copies of the Software, and to
8+
permit persons to whom the Software is furnished to do so, subject to
9+
the following conditions:
10+
11+
The above copyright notice and this permission notice shall be
12+
included in all copies or substantial portions of the Software.
13+
14+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.markdown

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
bcdatabase
2+
==========
3+
4+
*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.
5+
6+
## Installing bcdatabase
7+
8+
Ensure that [gemcutter](http://gemcutter.org) is in your gem sources list, then:
9+
10+
$ gem install bcdatabase
11+
12+
## Using bcdatabase to configure the database for a Rails application
13+
14+
A bog-standard rails application's `config/database.yml` file looks like this:
15+
16+
development:
17+
adapter: oracle-enhanced
18+
database: //localhost/XE
19+
username: cfg_animal
20+
password: not-important
21+
22+
test:
23+
adapter: oracle-enhanced
24+
database: //localhost/XE
25+
username: cfg_animal_test
26+
password: who-cares
27+
28+
production:
29+
adapter: oracle-enhanced
30+
database: //super/prod
31+
username: cfg_animal
32+
password: very-secret
33+
34+
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:
35+
36+
<%
37+
require 'bcdatabase'
38+
bcdb = Bcdatabase.load
39+
%>
40+
41+
development:
42+
adapter: oracle-enhanced
43+
database: //localhost/XE
44+
username: cfg_animal
45+
password: not-important
46+
47+
test:
48+
adapter: oracle-enhanced
49+
database: //localhost/XE
50+
username: cfg_animal_test
51+
password: who-cares
52+
53+
<%= bcdb.production :prod, :cfg_animal %>
54+
55+
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:
56+
57+
<%= bcdb.development :local, :cfg_animal %>
58+
<%= bcdb.staging 'stage', 'cfg_animal' %>
59+
<%= bcdb.automated :dev, :cfg_animal_hudson %>
60+
61+
[ERB]: http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/
62+
63+
## Directly accessing configuration parameters from bcdatabase
64+
65+
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:
66+
67+
bcdb[:local, :cfg_animal]
68+
69+
The resulting hash is suitable for passing to `ActiveRecord::Base.establish_connection`, for instance.
70+
71+
## Central configuration files
72+
73+
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:
74+
75+
* Each file can have a defaults entry which provides attributes which are shared across all configurations in the file
76+
* Each entry defaults its "username" attribute to the name of the entry (useful for Oracle)
77+
* Each entry defaults its "database" attribute to the name of the entry (useful for PostgreSQL)
78+
79+
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.
80+
81+
### Example
82+
83+
If you have an `/etc/nubic/db/stage.yml` file that looks like this:
84+
85+
defaults:
86+
adapter: oracle-enhanced
87+
database: //mondo/stage
88+
cfg_animal:
89+
password: secret
90+
personnel:
91+
username: pers
92+
password: more-secret
93+
94+
You have defined two configuration entries. `:stage, :cfg_animal`:
95+
96+
adapter: oracle-enhanced
97+
username: cfg_animal
98+
password: secret
99+
database: //mondo/stage
100+
101+
and `:bcstage, :personnel`:
102+
103+
adapter: oracle-enhanced
104+
username: pers
105+
password: more-secret
106+
database: //mondo/stage
107+
108+
## Obscuring passwords
109+
110+
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.
111+
112+
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.
113+
114+
## `bcdatabase` command line utility
115+
116+
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:
117+
118+
$ bcdatabase help
119+
usage: bcdatabase <command> [args]
120+
Command-line utility for bcdatabase 1.0.0
121+
encrypt Encrypts all the password entries in a bcdatabase YAML file
122+
epass Generate epasswords from individual database passwords
123+
gen-key Generate a key for bcdatabase to use
124+
help List commands or display help for one
125+
126+
## File locations
127+
128+
`/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`:
129+
130+
export BCDATABASE_PATH=${HOME}/nubic/db
131+
132+
Similarly, the file containing the encryption password has a sensible default location, but that location can be overridden by setting `BCDATABASE_PASS`.
133+
134+
## Credits
135+
136+
`bcdatabase` was developed at and for the [Northwestern University Biomedical Informatics Center][NUBIC].
137+
138+
[NUBIC]: http://www.nucats.northwestern.edu/centers/nubic/index.html
139+
140+
### Copyright
141+
142+
Copyright (c) 2009 Rhett Sutphin. See LICENSE for details.

‎Rakefile

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
require 'rubygems'
2+
require 'rake'
3+
4+
begin
5+
require 'jeweler'
6+
Jeweler::Tasks.new do |gem|
7+
gem.name = "bcdatabase"
8+
gem.summary = %Q{Server-central database configuration for rails and other ruby apps}
9+
gem.description = %Q{bcdatabase is a tool for storing passwords and other database configuration information outside of your application source tree.}
10+
gem.email = "[email protected]"
11+
gem.homepage = "http://github.com/rsutphin/bcdatabase"
12+
gem.authors = ["Rhett Sutphin"]
13+
gem.add_development_dependency 'rspec', ">= 1.2"
14+
gem.add_dependency 'highline', '>= 1.4'
15+
gem.add_dependency 'activesupport', '>= 2.0'
16+
end
17+
Jeweler::GemcutterTasks.new
18+
rescue LoadError
19+
puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
20+
end
21+
22+
require 'spec/rake/spectask'
23+
Spec::Rake::SpecTask.new(:spec) do |spec|
24+
spec.libs << 'lib' << 'spec'
25+
spec.spec_files = FileList['spec/**/*_spec.rb']
26+
end
27+
28+
Spec::Rake::SpecTask.new(:rcov) do |spec|
29+
spec.libs << 'lib' << 'spec'
30+
spec.pattern = 'spec/**/*_spec.rb'
31+
spec.rcov = true
32+
# rcov can't tell that /Library/Ruby is a system path
33+
spec.rcov_opts = ['--exclude', "spec/*,/Library/Ruby/*"]
34+
end
35+
36+
task :spec => :check_dependencies
37+
38+
task :default => :spec
39+
40+
require 'rake/rdoctask'
41+
Rake::RDocTask.new do |rdoc|
42+
version = File.exist?('VERSION') ? File.read('VERSION') : ""
43+
44+
rdoc.rdoc_dir = 'rdoc'
45+
rdoc.title = "schema_qualified_tables #{version}"
46+
rdoc.rdoc_files.include('README*')
47+
rdoc.rdoc_files.include('lib/**/*.rb')
48+
end
49+
50+
# Disable github release since I don't want to commit the gemspec
51+
Rake::Task[:release].prerequisites.delete 'github:release'
52+
53+
task :build => [:gemspec]

‎VERSION.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
:major: 1
3+
:minor: 0
4+
:build:
5+
:patch: 0

‎bin/bcdatabase

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
#!/usr/bin/env ruby -W
2+
3+
require 'rubygems'
4+
require 'bcdatabase/commands'
5+
6+
module Bcdatabase::Commands
7+
UTILITY_NAME = File.basename(__FILE__)
8+
end
9+
10+
###### MAIN
11+
12+
command = ARGV.shift
13+
unless command
14+
$stderr.puts "Please specify a command."
15+
$stderr.puts Bcdatabase::Commands.help
16+
exit(1)
17+
end
18+
19+
klass = Bcdatabase::Commands[command]
20+
unless klass
21+
$stderr.puts "Unknown command #{command}."
22+
$stderr.puts Bcdatabase::Commands.help
23+
exit(2)
24+
end
25+
klass.new(ARGV).main

0 commit comments

Comments
 (0)