dbmule 0.1.0 → 0.1.1
Sign up to get free protection for your applications and to get access to all the features.
- data/README.markdown +144 -144
- data/Rakefile +1 -1
- data/VERSION +1 -1
- data/dbmule.gemspec +3 -3
- data/lib/mule_migrations/tasks/mule.rake +5 -5
- metadata +6 -5
data/README.markdown
CHANGED
@@ -1,200 +1,200 @@
|
|
1
|
-
|
1
|
+
## Mule
|
2
2
|
|
3
|
-
|
4
|
-
==========
|
5
|
-
In the 2.x release we have moved to using Rails 3 migrations instead of maintaining our own migration related code. Just about anything you can do with Rails 3 migrations you can now do with [Standalone Migrations](https://github.com/thuss/standalone-migrations) too! This removed 95% of the code we have to maintain. Big thanks to [Ricardo Valeriano](http://ricardovaleriano.com/) and [Michael Grosser](http://pragmatig.wordpress.com) for undertaking this major rewrite!
|
3
|
+
###What is it?
|
6
4
|
|
7
|
-
|
8
|
-
==========
|
9
|
-
[Standalone Migrations](https://github.com/thuss/standalone-migrations) relies on the contributions of the open-source community! To submit a fix or an enhancement fork the repository, checkout the *develop* branch, make your changes, add your name to the *Contributors* section in README.markdown, and send us a pull request! If you're active and do good work we'll add you as a collaborator!
|
5
|
+
Mule is a database migration tool based on a stand-alone version of [Rails Migrations](http://guides.rubyonrails.org/migrations.html). By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby coding is required. It supports multi-database environments, including support for existing databases.
|
10
6
|
|
11
|
-
|
12
|
-
=====
|
13
|
-
Install Ruby, RubyGems and a ruby-database driver (e.g. `gem install mysql`) then:
|
7
|
+
You interact with Mule via a series of [Rake](http://rake.rubyforge.org/) commands which map almost 1:1 to Rails Migrations commands, so if you are familiar with them you will be right at home, but if not, don't worry -- it's really easy.
|
14
8
|
|
15
|
-
|
9
|
+
These commands give you a simple, yet powerful toolset allowing you to manage database migrations across both development and production environments.
|
16
10
|
|
17
|
-
|
11
|
+
###How do I use it?
|
12
|
+
|
13
|
+
####Prerequisites
|
14
|
+
|
15
|
+
Before using Mule, you must set up a Ruby environment on your machine. Follow the instructions at the links for [Ruby](http://www.ruby-lang.org/en/downloads/) and [RubyGems](https://rubygems.org/pages/download).
|
16
|
+
|
17
|
+
Once you have both Ruby and RubyGems installed, you should install the Ruby database driver for whatever database you are using, for example:
|
18
|
+
|
19
|
+
PostgreSQL
|
20
|
+
|
21
|
+
$ gem install pg
|
22
|
+
|
23
|
+
####Installation
|
24
|
+
|
25
|
+
Once your Ruby environment is set up, installing Mule is no big deal:
|
26
|
+
|
27
|
+
$ gem install dbmule
|
28
|
+
|
29
|
+
Next, create a `Rakefile` in your project's base directory containing the following lines:
|
18
30
|
|
19
31
|
```ruby
|
20
|
-
require '
|
21
|
-
|
32
|
+
require 'mule_migrations'
|
33
|
+
MuleMigrations::Tasks.load_tasks
|
22
34
|
```
|
23
35
|
|
24
|
-
|
36
|
+
Installation is complete, you are now ready to begin using Mule.
|
37
|
+
|
38
|
+
####Create a database project
|
39
|
+
|
40
|
+
To begin, create a new database project. A database project represents one database in your system. You can do this with one command:
|
41
|
+
|
42
|
+
rake mule:new_project db=foo_bar_database
|
43
|
+
|
44
|
+
Mule will then create a directory in your project's base directory called whatever you put in for `foo_bar_database` above. Inside it will create the basic Mule project structure, which looks like this:
|
45
|
+
|
46
|
+
foo_bar_database/
|
47
|
+
db/
|
48
|
+
migrate/
|
49
|
+
sql/
|
50
|
+
seeds/
|
51
|
+
config.yml
|
52
|
+
seeds.rb
|
53
|
+
|
54
|
+
After the project has been created, you will need to edit the `foo_bar_database\db\config.yml` file and enter the correct database connection information for each environment section you require (development, test, production below). You can create an arbitary number of environments, with any names you like:
|
25
55
|
|
26
56
|
development:
|
27
|
-
adapter:
|
28
|
-
|
57
|
+
adapter: postgresql
|
58
|
+
encoding: unicode
|
59
|
+
database: foo_bar_database_development
|
29
60
|
pool: 5
|
30
|
-
|
61
|
+
username:
|
62
|
+
password:
|
63
|
+
host: localhost
|
31
64
|
|
32
|
-
|
33
|
-
adapter:
|
34
|
-
encoding:
|
35
|
-
|
36
|
-
database: somedatabase_dev
|
65
|
+
test:
|
66
|
+
adapter: postgresql
|
67
|
+
encoding: unicode
|
68
|
+
database: foo_bar_database_test
|
37
69
|
pool: 5
|
38
|
-
username:
|
70
|
+
username:
|
39
71
|
password:
|
40
|
-
|
72
|
+
host: localhost
|
41
73
|
|
42
|
-
|
43
|
-
adapter:
|
44
|
-
|
74
|
+
production:
|
75
|
+
adapter: postgresql
|
76
|
+
encoding: unicode
|
77
|
+
database: foo_bar_database_production
|
45
78
|
pool: 5
|
46
|
-
|
79
|
+
username: ENV['FOO_BAR_DATABASE_USER']
|
80
|
+
password: ENV['FOO_BAR_DATABASE_PSWD']
|
81
|
+
host: ENV['FOO_BAR_DATABASE_HOST']
|
47
82
|
|
48
|
-
|
83
|
+
####Changing the current environment
|
49
84
|
|
50
|
-
|
51
|
-
edit db/migrate/20081220234130_foo_bar_migration.rb
|
85
|
+
Any command you run will default to the `development` environment, but you can specify which environment you want to run using RAILS_ENV:
|
52
86
|
|
53
|
-
|
87
|
+
$ rake mule:migrate db=foo_bar_database RAILS_ENV=production
|
54
88
|
|
55
|
-
|
56
|
-
def up
|
57
|
-
execute "insert into foo values (123,'something');"
|
58
|
-
end
|
89
|
+
####Enable migrations on an existing database
|
59
90
|
|
60
|
-
|
61
|
-
execute "delete from foo where field='something';"
|
62
|
-
end
|
63
|
-
```
|
91
|
+
Sometimes you will need to create a database project for an existing database. To do so, follow the instructions above for creating a project and then run the following command:
|
64
92
|
|
65
|
-
|
93
|
+
$ rake mule:configure_existing_database db=foo_bar_database
|
66
94
|
|
67
|
-
|
95
|
+
This will add an initial database version to your database with the contents of a schema dump, so that it can be recreated in other environments.
|
68
96
|
|
69
|
-
|
97
|
+
####Create a migration:
|
70
98
|
|
71
|
-
rake
|
99
|
+
$ rake mule:new_migration db=foo_bar_database name=foo_bar_migration
|
72
100
|
|
73
|
-
|
101
|
+
A migration represents a single change you want to make in the database, such as adding a table, adding a column, creating an index, dropping a column, dropping a database, dropping an index, defining a stored procedure...and so on.
|
74
102
|
|
75
|
-
|
76
|
-
rake db:migrate RAILS_ENV=test
|
103
|
+
A migration has both an UP and DOWN implementation: UP to make the change and DOWN to undo it. When you call the command above, by default Mule will create two SQL scripts in the `foo_bar_database/db/sql` directory. The format of the filenames are:
|
77
104
|
|
78
|
-
|
105
|
+
<timestamp>_<name_of_migration>_up.sql
|
106
|
+
<timestamp>_<name_of_migration>_down.sql
|
79
107
|
|
80
|
-
|
108
|
+
example: 20130128185251_foo_bar_migration_up.sql
|
109
|
+
example: 20130128185251_foo_bar_migration_down.sql
|
81
110
|
|
82
|
-
|
111
|
+
These files are plain old SQL files and that's all they should contain.
|
83
112
|
|
84
|
-
|
113
|
+
Using Ruby
|
85
114
|
|
86
|
-
|
115
|
+
If you want to use the ActiveRecord domain-specific language to write your migrations instead of SQL, pass into the command the flag `type=ruby` so that the SQL scripts are not generated and then edit both the up and down methods of the file created in the `foo_bar_database/db/migrate` directory. The format of the filename is:
|
87
116
|
|
88
|
-
|
117
|
+
<timestamp>_<name_of_migration>.rb
|
89
118
|
|
90
|
-
|
119
|
+
example: 20130128185251_foo_bar_migration.rb
|
91
120
|
|
92
|
-
|
93
|
-
directory in your project. But if for some reason you need a specific
|
94
|
-
directory structure to work with, you can use a configuration file
|
95
|
-
named .standalone_migrations in the root of your project containing
|
96
|
-
the following:
|
121
|
+
####Migrate database to latest version:
|
97
122
|
|
98
|
-
|
99
|
-
db:
|
100
|
-
seeds: db/seeds.rb
|
101
|
-
migrate: db/migrate
|
102
|
-
schema: db/schema.rb
|
103
|
-
config:
|
104
|
-
database: db/config.yml
|
105
|
-
```
|
123
|
+
$ rake mule:migrate db=foo_bar_database
|
106
124
|
|
107
|
-
|
108
|
-
the keys and Standalone Migrations will assume the default values.
|
125
|
+
This command will run any migrations that have not been run on the database.
|
109
126
|
|
110
|
-
####
|
127
|
+
####Migrate database to specific version (up or down depending on current version):
|
111
128
|
|
112
|
-
|
113
|
-
configuration based on runtime aspects (maybe environment variables),
|
114
|
-
you can use the `StandaloneMigrations::Configurator.environments_config`
|
115
|
-
method. Check the usage example:
|
129
|
+
$ rake mule:migrate db=foo_bar_database VERSION=<specific_version_number>
|
116
130
|
|
117
|
-
|
118
|
-
require 'tasks/standalone_migrations'
|
131
|
+
####Run a single, specific migration:
|
119
132
|
|
120
|
-
|
133
|
+
$ rake mule:migrate:up db=foo_bar_database VERSION=<specific_version_number>
|
121
134
|
|
122
|
-
|
135
|
+
or
|
123
136
|
|
124
|
-
|
125
|
-
db = URI.parse(ENV['DATABASE_URL'])
|
126
|
-
return {
|
127
|
-
:adapter => db.scheme == 'postgres' ? 'postgresql' : db.scheme,
|
128
|
-
:host => db.host,
|
129
|
-
:username => db.user,
|
130
|
-
:password => db.password,
|
131
|
-
:database => db.path[1..-1],
|
132
|
-
:encoding => 'utf8'
|
133
|
-
}
|
134
|
-
end
|
137
|
+
$ rake mule:migrate:down db=foo_bar_database VERSION=<specific_version_number>
|
135
138
|
|
136
|
-
|
137
|
-
end
|
139
|
+
####Rollback database to the previous version:
|
138
140
|
|
139
|
-
|
140
|
-
```
|
141
|
+
$ rake mule:rollback db=foo_bar_database
|
141
142
|
|
142
|
-
|
143
|
-
change some configuration, call the #on method on the object
|
144
|
-
received as argument in your block passed to ::environments_config
|
145
|
-
method call. The #on method receives the key to the configuration
|
146
|
-
that you want to change within the block. The block should return
|
147
|
-
your new configuration hash or nil if you want the configuration
|
148
|
-
to stay the same.
|
143
|
+
####Rollback database a certain number of steps:
|
149
144
|
|
150
|
-
|
151
|
-
in your current configuration? Then you should receive the configuration
|
152
|
-
in your block, like this:
|
145
|
+
$ rake mule:rollback db=foo_bar_database STEP=<how_many_steps>
|
153
146
|
|
154
|
-
|
155
|
-
require 'tasks/standalone_migrations'
|
147
|
+
####Seed database:
|
156
148
|
|
157
|
-
|
149
|
+
$ rake mule:seed db=foo_bar_database
|
158
150
|
|
159
|
-
|
160
|
-
p current_custom_config
|
161
|
-
# => the values on your current "my_custom_config" environment
|
162
|
-
nil
|
163
|
-
end
|
151
|
+
You can create arbitrary SQL files in the `foo_bar_database/db/seeds` directory and they will be executed with this command. Specify order by numbering your files. If you want the data to be removed at each call to `mule:seed`, then you need to add that logic.
|
164
152
|
|
165
|
-
|
166
|
-
```
|
153
|
+
####Retrieve database version:
|
167
154
|
|
168
|
-
|
155
|
+
$ rake mule:version db=foo_bar_database
|
169
156
|
|
170
|
-
|
171
|
-
save the database-specific SQL generated by the migrations, simply
|
172
|
-
add this to your `Rakefile`.
|
157
|
+
####Create database:
|
173
158
|
|
174
|
-
|
175
|
-
|
176
|
-
|
177
|
-
|
159
|
+
$ rake mule:create db=foo_bar_database
|
160
|
+
|
161
|
+
####Drop database:
|
162
|
+
|
163
|
+
$ rake mule:drop db=foo_bar_database
|
164
|
+
|
165
|
+
####Reset database:
|
166
|
+
|
167
|
+
$ rake mule:reset db=foo_bar_database
|
168
|
+
|
169
|
+
####Dump schema:
|
170
|
+
|
171
|
+
$ rake mule:structure:dump db=foo_bar_database
|
172
|
+
|
173
|
+
####Load schema:
|
174
|
+
|
175
|
+
$ rake mule:structure:load db=foo_bar_database
|
176
|
+
|
177
|
+
###Notes for production:
|
178
|
+
|
179
|
+
####Database environment variables
|
180
|
+
|
181
|
+
The `foo_bar_database/db/config.yml` file can contain environment variable accessors:
|
182
|
+
|
183
|
+
production:
|
184
|
+
adapter: postgresql
|
185
|
+
encoding: unicode
|
186
|
+
database: foo_bar_database_production
|
187
|
+
pool: 5
|
188
|
+
username: ENV['FOO_BAR_USER']
|
189
|
+
password: ENV['FOO_BAR_PSWD']
|
190
|
+
host: ENV['FOO_BAR_HOST']
|
191
|
+
|
192
|
+
You can use this in production configurations to pass in database configuration during execution of the command:
|
193
|
+
|
194
|
+
$ rake mule:migrate db=foo_bar_database RAILS_ENV=production FOO_BAR_USER=<prod_user> FOO_BAR_PSWD=<prod_pswd> FOO_BAR_HOST=<prod_host>
|
195
|
+
|
196
|
+
####Safeguard for destructive commands
|
197
|
+
|
198
|
+
Mule has a safeguard system in place for any `foo_bar_database/db/config.yml` environment that contains the word 'production'. If you run any command that is typically destructive in nature (i.e. data could be lost), then it is required that you pass in an additional confirm argument to the command. The confirm argument must contain the database project name:
|
178
199
|
|
179
|
-
|
180
|
-
migration.
|
181
|
-
|
182
|
-
Contributors
|
183
|
-
============
|
184
|
-
- [Todd Huss](http://gabrito.com/)
|
185
|
-
- [Michael Grosser](http://pragmatig.wordpress.com)
|
186
|
-
- [Ricardo Valeriano](http://ricardovaleriano.com/)
|
187
|
-
- [Two Bit Labs](http://twobitlabs.com/)
|
188
|
-
- [ClassMonkeys](http://www.classmonkeys.com/)
|
189
|
-
- [Windandtides](http://windandtides.com/)
|
190
|
-
- [Eric Lindvall](http://bitmonkey.net)
|
191
|
-
- [Steve Hodgkiss](http://stevehodgkiss.com/)
|
192
|
-
- [Rich Meyers](https://github.com/richmeyers)
|
193
|
-
- [Wes Bailey](http://exposinggotchas.blogspot.com/)
|
194
|
-
- [Robert J. Berger](http://blog.ibd.com/)
|
195
|
-
- [Federico Builes](http://mheroin.com/)
|
196
|
-
- [Gazler](http://blog.gazler.com/)
|
197
|
-
- [Yuu Yamashita](https://github.com/yyuu)
|
198
|
-
- [Koen Punt](http://www.koen.pt/)
|
199
|
-
|
200
|
-
This work is originally based on [Lincoln Stoll's blog post](http://lstoll.net/2008/04/stand-alone-activerecord-migrations/) and [David Welton's post](http://journal.dedasys.com/2007/01/28/using-migrations-outside-of-rails).
|
200
|
+
$ rake mule:rollback confirm=foo_bar_database db=foo_bar_database RAILS_ENV=production
|
data/Rakefile
CHANGED
@@ -31,7 +31,7 @@ rescue LoadError => e
|
|
31
31
|
else
|
32
32
|
Jeweler::Tasks.new do |gem|
|
33
33
|
gem.name = 'dbmule'
|
34
|
-
gem.summary = "Mule is a database migration tool based
|
34
|
+
gem.summary = "Mule is a database migration tool based on a stand-alone version of Rails Migrations. By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby coding is required. It supports multi-database environments, including support for existing databases."
|
35
35
|
gem.email = "willstepp@gmail.com"
|
36
36
|
gem.homepage = "http://github.com/willstepp/dbmule"
|
37
37
|
gem.authors = ["Daniel Stepp"]
|
data/VERSION
CHANGED
@@ -1 +1 @@
|
|
1
|
-
0.1.
|
1
|
+
0.1.1
|
data/dbmule.gemspec
CHANGED
@@ -5,11 +5,11 @@
|
|
5
5
|
|
6
6
|
Gem::Specification.new do |s|
|
7
7
|
s.name = "dbmule"
|
8
|
-
s.version = "0.1.
|
8
|
+
s.version = "0.1.1"
|
9
9
|
|
10
10
|
s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
|
11
11
|
s.authors = ["Daniel Stepp"]
|
12
|
-
s.date = "2013-01-
|
12
|
+
s.date = "2013-01-29"
|
13
13
|
s.email = "willstepp@gmail.com"
|
14
14
|
s.extra_rdoc_files = [
|
15
15
|
"README.markdown"
|
@@ -39,7 +39,7 @@ Gem::Specification.new do |s|
|
|
39
39
|
s.homepage = "http://github.com/willstepp/dbmule"
|
40
40
|
s.require_paths = ["lib"]
|
41
41
|
s.rubygems_version = "1.8.25"
|
42
|
-
s.summary = "Mule is a database migration tool based
|
42
|
+
s.summary = "Mule is a database migration tool based on a stand-alone version of Rails Migrations. By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby coding is required. It supports multi-database environments, including support for existing databases."
|
43
43
|
|
44
44
|
if s.respond_to? :specification_version then
|
45
45
|
s.specification_version = 3
|
@@ -18,7 +18,7 @@ development:
|
|
18
18
|
pool: 5
|
19
19
|
username:
|
20
20
|
password:
|
21
|
-
host:
|
21
|
+
host: localhost
|
22
22
|
|
23
23
|
test:
|
24
24
|
adapter: postgresql
|
@@ -27,16 +27,16 @@ test:
|
|
27
27
|
pool: 5
|
28
28
|
username:
|
29
29
|
password:
|
30
|
-
host:
|
30
|
+
host: localhost
|
31
31
|
|
32
32
|
production:
|
33
33
|
adapter: postgresql
|
34
34
|
encoding: unicode
|
35
35
|
database: #{db}_production
|
36
36
|
pool: 5
|
37
|
-
username:
|
38
|
-
password:
|
39
|
-
host:
|
37
|
+
username: ENV['#{db.upcase}_USER']
|
38
|
+
password: ENV['#{db.upcase}_PSWD']
|
39
|
+
host: ENV['#{db.upcase}_HOST']
|
40
40
|
eos
|
41
41
|
end
|
42
42
|
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: dbmule
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.1.
|
4
|
+
version: 0.1.1
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
@@ -9,7 +9,7 @@ authors:
|
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2013-01-
|
12
|
+
date: 2013-01-29 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: rake
|
@@ -109,7 +109,8 @@ rubyforge_project:
|
|
109
109
|
rubygems_version: 1.8.25
|
110
110
|
signing_key:
|
111
111
|
specification_version: 3
|
112
|
-
summary: Mule is a database migration tool based
|
113
|
-
Migrations.
|
114
|
-
|
112
|
+
summary: Mule is a database migration tool based on a stand-alone version of Rails
|
113
|
+
Migrations. By default, Mule uses SQL scripts instead of Migrations DSL, so no Ruby
|
114
|
+
coding is required. It supports multi-database environments, including support for
|
115
|
+
existing databases.
|
115
116
|
test_files: []
|