1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
== Migrations ==
If your plugin requires changes to the app's database you will likely want to somehow add migrations. Rails does not include any built-in support for calling migrations from plugins, but you can still make it easy for developers to call migrations from plugins.
If you have a very simple needs, like creating a table that will always have the same name and columns, then you can use a more simple solution, like creating a custom rake task or method. If your migration needs user input to supply table names or other options, you probably want to opt for generating a migration.
Let's say you have the following migration in your plugin:
*vendor/plugins/yaffle/lib/db/migrate/20081116181115_create_birdhouses.rb:*
[source, ruby]
----------------------------------------------
class CreateBirdhouses < ActiveRecord::Migration
def self.up
create_table :birdhouses, :force => true do |t|
t.string :name
t.timestamps
end
end
def self.down
drop_table :birdhouses
end
end
----------------------------------------------
Here are a few possibilities for how to allow developers to use your plugin migrations:
=== Create a custom rake task ===
*vendor/plugins/yaffle/tasks/yaffle_tasks.rake:*
[source, ruby]
----------------------------------------------
namespace :db do
namespace :migrate do
desc "Migrate the database through scripts in vendor/plugins/yaffle/lib/db/migrate and update db/schema.rb by invoking db:schema:dump. Target specific version with VERSION=x. Turn off output with VERBOSE=false."
task :yaffle => :environment do
ActiveRecord::Migration.verbose = ENV["VERBOSE"] ? ENV["VERBOSE"] == "true" : true
ActiveRecord::Migrator.migrate("vendor/plugins/yaffle/lib/db/migrate/", ENV["VERSION"] ? ENV["VERSION"].to_i : nil)
Rake::Task["db:schema:dump"].invoke if ActiveRecord::Base.schema_format == :ruby
end
end
end
----------------------------------------------
=== Call migrations directly ===
*vendor/plugins/yaffle/lib/yaffle.rb:*
[source, ruby]
----------------------------------------------
Dir.glob(File.join(File.dirname(__FILE__), "db", "migrate", "*")).each do |file|
require file
end
----------------------------------------------
*db/migrate/20081116181115_create_birdhouses.rb:*
[source, ruby]
----------------------------------------------
class CreateBirdhouses < ActiveRecord::Migration
def self.up
Yaffle::CreateBirdhouses.up
end
def self.down
Yaffle::CreateBirdhouses.down
end
end
----------------------------------------------
.Editor's note:
NOTE: several plugin frameworks such as Desert and Engines provide more advanced plugin functionality.
=== Generate migrations ===
Generating migrations has several advantages over other methods. Namely, you can allow other developers to more easily customize the migration. The flow looks like this:
* call your script/generate script and pass in whatever options they need
* examine the generated migration, adding/removing columns or other options as necessary
This example will demonstrate how to use one of the built-in generator methods named 'migration_template' to create a migration file. Extending the rails migration generator requires a somewhat intimate knowledge of the migration generator internals, so it's best to write a test first:
*vendor/plugins/yaffle/test/yaffle_migration_generator_test.rb*
[source, ruby]
------------------------------------------------------------------
require File.dirname(__FILE__) + '/test_helper.rb'
require 'rails_generator'
require 'rails_generator/scripts/generate'
class MigrationGeneratorTest < Test::Unit::TestCase
def setup
FileUtils.mkdir_p(fake_rails_root)
@original_files = file_list
end
def teardown
ActiveRecord::Base.pluralize_table_names = true
FileUtils.rm_r(fake_rails_root)
end
def test_generates_correct_file_name
Rails::Generator::Scripts::Generate.new.run(["yaffle_migration", "some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination => fake_rails_root)
new_file = (file_list - @original_files).first
assert_match /add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migrations/, new_file
assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migrations do |t|/, File.read(new_file)
end
def test_pluralizes_properly
ActiveRecord::Base.pluralize_table_names = false
Rails::Generator::Scripts::Generate.new.run(["yaffle_migration", "some_name_nobody_is_likely_to_ever_use_in_a_real_migration"], :destination => fake_rails_root)
new_file = (file_list - @original_files).first
assert_match /add_yaffle_fields_to_some_name_nobody_is_likely_to_ever_use_in_a_real_migration/, new_file
assert_match /add_column :some_name_nobody_is_likely_to_ever_use_in_a_real_migration do |t|/, File.read(new_file)
end
private
def fake_rails_root
File.join(File.dirname(__FILE__), 'rails_root')
end
def file_list
Dir.glob(File.join(fake_rails_root, "db", "migrate", "*"))
end
end
------------------------------------------------------------------
.Editor's note:
NOTE: the migration generator checks to see if a migation already exists, and it's hard-coded to check the 'db/migrate' directory. As a result, if your test tries to generate a migration that already exists in the app, it will fail. The easy workaround is to make sure that the name you generate in your test is very unlikely to actually appear in the app.
After running the test with 'rake' you can make it pass with:
*vendor/plugins/yaffle/generators/yaffle_migration/yaffle_migration_generator.rb*
[source, ruby]
------------------------------------------------------------------
class YaffleMigrationGenerator < Rails::Generator::NamedBase
def manifest
record do |m|
m.migration_template 'migration:migration.rb', "db/migrate", {:assigns => yaffle_local_assigns,
:migration_file_name => "add_yaffle_fields_to_#{custom_file_name}"
}
end
end
private
def custom_file_name
custom_name = class_name.underscore.downcase
custom_name = custom_name.pluralize if ActiveRecord::Base.pluralize_table_names
custom_name
end
def yaffle_local_assigns
returning(assigns = {}) do
assigns[:migration_action] = "add"
assigns[:class_name] = "add_yaffle_fields_to_#{custom_file_name}"
assigns[:table_name] = custom_file_name
assigns[:attributes] = [Rails::Generator::GeneratedAttribute.new("last_squawk", "string")]
end
end
end
------------------------------------------------------------------
The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement. It reuses the built in rails `migration_template` method, and reuses the built-in rails migration template.
It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names. This way people using your generator won't have to manually change the generated files if they've turned pluralization off.
To run the generator, type the following at the command line:
------------------------------------------------------------------
./script/generate yaffle_migration bird
------------------------------------------------------------------
and you will see a new file:
*db/migrate/20080529225649_add_yaffle_fields_to_birds.rb*
[source, ruby]
------------------------------------------------------------------
class AddYaffleFieldsToBirds < ActiveRecord::Migration
def self.up
add_column :birds, :last_squawk, :string
end
def self.down
remove_column :birds, :last_squawk
end
end
------------------------------------------------------------------
|
