sequel 5.83.0 → 5.84.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (126) hide show
  1. checksums.yaml +4 -4
  2. data/lib/sequel/adapters/shared/sqlite.rb +3 -1
  3. data/lib/sequel/database/connecting.rb +1 -1
  4. data/lib/sequel/database/misc.rb +8 -3
  5. data/lib/sequel/database/schema_methods.rb +2 -0
  6. data/lib/sequel/extensions/pg_json_ops.rb +328 -1
  7. data/lib/sequel/sql.rb +8 -5
  8. data/lib/sequel/version.rb +1 -1
  9. metadata +2 -236
  10. data/CHANGELOG +0 -1393
  11. data/README.rdoc +0 -936
  12. data/doc/advanced_associations.rdoc +0 -884
  13. data/doc/association_basics.rdoc +0 -1859
  14. data/doc/bin_sequel.rdoc +0 -146
  15. data/doc/cheat_sheet.rdoc +0 -255
  16. data/doc/code_order.rdoc +0 -104
  17. data/doc/core_extensions.rdoc +0 -405
  18. data/doc/dataset_basics.rdoc +0 -96
  19. data/doc/dataset_filtering.rdoc +0 -222
  20. data/doc/extensions.rdoc +0 -77
  21. data/doc/fork_safety.rdoc +0 -84
  22. data/doc/mass_assignment.rdoc +0 -98
  23. data/doc/migration.rdoc +0 -660
  24. data/doc/model_dataset_method_design.rdoc +0 -129
  25. data/doc/model_hooks.rdoc +0 -254
  26. data/doc/model_plugins.rdoc +0 -270
  27. data/doc/mssql_stored_procedures.rdoc +0 -43
  28. data/doc/object_model.rdoc +0 -563
  29. data/doc/opening_databases.rdoc +0 -439
  30. data/doc/postgresql.rdoc +0 -611
  31. data/doc/prepared_statements.rdoc +0 -144
  32. data/doc/querying.rdoc +0 -1070
  33. data/doc/reflection.rdoc +0 -120
  34. data/doc/release_notes/5.0.0.txt +0 -159
  35. data/doc/release_notes/5.1.0.txt +0 -31
  36. data/doc/release_notes/5.10.0.txt +0 -84
  37. data/doc/release_notes/5.11.0.txt +0 -83
  38. data/doc/release_notes/5.12.0.txt +0 -141
  39. data/doc/release_notes/5.13.0.txt +0 -27
  40. data/doc/release_notes/5.14.0.txt +0 -63
  41. data/doc/release_notes/5.15.0.txt +0 -39
  42. data/doc/release_notes/5.16.0.txt +0 -110
  43. data/doc/release_notes/5.17.0.txt +0 -31
  44. data/doc/release_notes/5.18.0.txt +0 -69
  45. data/doc/release_notes/5.19.0.txt +0 -28
  46. data/doc/release_notes/5.2.0.txt +0 -33
  47. data/doc/release_notes/5.20.0.txt +0 -89
  48. data/doc/release_notes/5.21.0.txt +0 -87
  49. data/doc/release_notes/5.22.0.txt +0 -48
  50. data/doc/release_notes/5.23.0.txt +0 -56
  51. data/doc/release_notes/5.24.0.txt +0 -56
  52. data/doc/release_notes/5.25.0.txt +0 -32
  53. data/doc/release_notes/5.26.0.txt +0 -35
  54. data/doc/release_notes/5.27.0.txt +0 -21
  55. data/doc/release_notes/5.28.0.txt +0 -16
  56. data/doc/release_notes/5.29.0.txt +0 -22
  57. data/doc/release_notes/5.3.0.txt +0 -121
  58. data/doc/release_notes/5.30.0.txt +0 -20
  59. data/doc/release_notes/5.31.0.txt +0 -148
  60. data/doc/release_notes/5.32.0.txt +0 -46
  61. data/doc/release_notes/5.33.0.txt +0 -24
  62. data/doc/release_notes/5.34.0.txt +0 -40
  63. data/doc/release_notes/5.35.0.txt +0 -56
  64. data/doc/release_notes/5.36.0.txt +0 -60
  65. data/doc/release_notes/5.37.0.txt +0 -30
  66. data/doc/release_notes/5.38.0.txt +0 -28
  67. data/doc/release_notes/5.39.0.txt +0 -19
  68. data/doc/release_notes/5.4.0.txt +0 -80
  69. data/doc/release_notes/5.40.0.txt +0 -40
  70. data/doc/release_notes/5.41.0.txt +0 -25
  71. data/doc/release_notes/5.42.0.txt +0 -136
  72. data/doc/release_notes/5.43.0.txt +0 -98
  73. data/doc/release_notes/5.44.0.txt +0 -32
  74. data/doc/release_notes/5.45.0.txt +0 -34
  75. data/doc/release_notes/5.46.0.txt +0 -87
  76. data/doc/release_notes/5.47.0.txt +0 -59
  77. data/doc/release_notes/5.48.0.txt +0 -14
  78. data/doc/release_notes/5.49.0.txt +0 -59
  79. data/doc/release_notes/5.5.0.txt +0 -61
  80. data/doc/release_notes/5.50.0.txt +0 -78
  81. data/doc/release_notes/5.51.0.txt +0 -47
  82. data/doc/release_notes/5.52.0.txt +0 -87
  83. data/doc/release_notes/5.53.0.txt +0 -23
  84. data/doc/release_notes/5.54.0.txt +0 -27
  85. data/doc/release_notes/5.55.0.txt +0 -21
  86. data/doc/release_notes/5.56.0.txt +0 -51
  87. data/doc/release_notes/5.57.0.txt +0 -23
  88. data/doc/release_notes/5.58.0.txt +0 -31
  89. data/doc/release_notes/5.59.0.txt +0 -73
  90. data/doc/release_notes/5.6.0.txt +0 -31
  91. data/doc/release_notes/5.60.0.txt +0 -22
  92. data/doc/release_notes/5.61.0.txt +0 -43
  93. data/doc/release_notes/5.62.0.txt +0 -132
  94. data/doc/release_notes/5.63.0.txt +0 -33
  95. data/doc/release_notes/5.64.0.txt +0 -50
  96. data/doc/release_notes/5.65.0.txt +0 -21
  97. data/doc/release_notes/5.66.0.txt +0 -24
  98. data/doc/release_notes/5.67.0.txt +0 -32
  99. data/doc/release_notes/5.68.0.txt +0 -61
  100. data/doc/release_notes/5.69.0.txt +0 -26
  101. data/doc/release_notes/5.7.0.txt +0 -108
  102. data/doc/release_notes/5.70.0.txt +0 -35
  103. data/doc/release_notes/5.71.0.txt +0 -21
  104. data/doc/release_notes/5.72.0.txt +0 -33
  105. data/doc/release_notes/5.73.0.txt +0 -66
  106. data/doc/release_notes/5.74.0.txt +0 -45
  107. data/doc/release_notes/5.75.0.txt +0 -35
  108. data/doc/release_notes/5.76.0.txt +0 -86
  109. data/doc/release_notes/5.77.0.txt +0 -63
  110. data/doc/release_notes/5.78.0.txt +0 -67
  111. data/doc/release_notes/5.79.0.txt +0 -28
  112. data/doc/release_notes/5.8.0.txt +0 -170
  113. data/doc/release_notes/5.80.0.txt +0 -40
  114. data/doc/release_notes/5.81.0.txt +0 -31
  115. data/doc/release_notes/5.82.0.txt +0 -61
  116. data/doc/release_notes/5.83.0.txt +0 -56
  117. data/doc/release_notes/5.9.0.txt +0 -99
  118. data/doc/schema_modification.rdoc +0 -679
  119. data/doc/security.rdoc +0 -443
  120. data/doc/sharding.rdoc +0 -286
  121. data/doc/sql.rdoc +0 -648
  122. data/doc/testing.rdoc +0 -204
  123. data/doc/thread_safety.rdoc +0 -15
  124. data/doc/transactions.rdoc +0 -250
  125. data/doc/validations.rdoc +0 -558
  126. data/doc/virtual_rows.rdoc +0 -265
data/doc/migration.rdoc DELETED
@@ -1,660 +0,0 @@
1
- = Migrations
2
-
3
- This guide is based on http://guides.rubyonrails.org/migrations.html
4
-
5
- == Overview
6
-
7
- Migrations make it easy to alter your database's schema in a systematic manner.
8
- They make it easier to coordinate with other developers and make sure that
9
- all developers are using the same database schema.
10
-
11
- Migrations are optional, you don't have to use them. You can always just
12
- create the necessary database structure manually using Sequel's schema
13
- modification methods or another database tool. However, if you are dealing
14
- with other developers, you'll have to send them all of the changes you are
15
- making. Even if you aren't dealing with other developers, you generally have
16
- to make the schema changes in 3 places (development, testing, and
17
- production), and it's probably easier to use the migrations system to apply
18
- the schema changes than it is to keep track of the changes manually and
19
- execute them manually at the appropriate time.
20
-
21
- Sequel tracks which migrations you have already run, so to apply migrations
22
- you generally need to run Sequel's migrator with <tt>bin/sequel -m</tt>:
23
-
24
- sequel -m path/to/migrations postgres://host/database
25
-
26
- Migrations in Sequel use a DSL via the <tt>Sequel.migration</tt>
27
- method, and inside the DSL, use the <tt>Sequel::Database</tt> schema
28
- modification methods such as +create_table+ and +alter_table+.
29
- See the {schema modification guide}[rdoc-ref:doc/schema_modification.rdoc]
30
- for details on the schema modification methods you can use.
31
-
32
- == A Basic Migration
33
-
34
- Here is a fairly basic Sequel migration:
35
-
36
- Sequel.migration do
37
- up do
38
- create_table(:artists) do
39
- primary_key :id
40
- String :name, null: false
41
- end
42
- end
43
-
44
- down do
45
- drop_table(:artists)
46
- end
47
- end
48
-
49
- This migration has an +up+ block which adds an artist table with an integer primary key named id,
50
- and a varchar or text column (depending on the database) named +name+ that doesn't accept +NULL+ values.
51
- Migrations should include both up and +down+ blocks, with the +down+ block reversing
52
- the change made by up. However, if you never need to be able to migrate down,
53
- you can leave out the +down+ block. In this case, the +down+ block just reverses the changes made by up,
54
- dropping the table.
55
-
56
- You can simplify the migration given above by using a reversible migration with a +change+
57
- block:
58
-
59
- Sequel.migration do
60
- change do
61
- create_table(:artists) do
62
- primary_key :id
63
- String :name, null: false
64
- end
65
- end
66
- end
67
-
68
- The +change+ block acts exactly like an +up+ block. The only difference is that
69
- it will attempt to create a +down+ block for you, assuming that it knows how to
70
- reverse the given migration. The +change+ block can usually correctly reverse
71
- the following methods:
72
-
73
- * +create_table+
74
- * +create_join_table+
75
- * +create_view+
76
- * +add_column+
77
- * +add_index+
78
- * +rename_column+
79
- * +rename_table+
80
- * +alter_table+ (supporting the following methods in the +alter_table+ block):
81
- * +add_column+
82
- * +add_constraint+
83
- * +add_foreign_key+ (with a symbol, not an array)
84
- * +add_primary_key+ (with a symbol, not an array)
85
- * +add_index+
86
- * +add_full_text_index+
87
- * +add_spatial_index+
88
- * +rename_column+
89
- * +set_column_allow_null+
90
-
91
- If you use any other methods, you should create your own +down+ block.
92
-
93
- To revert a migration created with +change+, you can copy the migration to a new file, and
94
- replace +change+ with +revert+. For example, if you no longer need the artists table, you
95
- can use the following migration. This will drop the artists table when migrating up, and
96
- recreate it when migrating down:
97
-
98
- Sequel.migration do
99
- revert do
100
- create_table(:artists) do
101
- primary_key :id
102
- String :name, null: false
103
- end
104
- end
105
- end
106
-
107
- In normal usage, when Sequel's migrator runs, it runs the +up+ blocks for all
108
- migrations that have not yet been applied. However, you can use the <tt>-M</tt>
109
- switch to specify the version to which to migrate, and if it is lower than the
110
- current version, Sequel will run the +down+ block on the appropriate migrations.
111
-
112
- You are not limited to creating tables inside a migration, you can alter existing tables
113
- as well as modify data. Let's say your artist database originally only included artists
114
- from Sacramento, CA, USA, but now you want to branch out and include artists in any city:
115
-
116
- Sequel.migration do
117
- up do
118
- add_column :artists, :location, String
119
- from(:artists).update(location: 'Sacramento')
120
- end
121
-
122
- down do
123
- drop_column :artists, :location
124
- end
125
- end
126
-
127
- This migration adds a +location+ column to the +artists+ table, and sets the +location+ column
128
- to <tt>'Sacramento'</tt> for all existing artists. It doesn't use a default on the column,
129
- because future artists should not be assumed to come from Sacramento. In the +down+ block, it
130
- just drops the +location+ column from the +artists+ table, reversing the actions of the up
131
- block.
132
-
133
- Note that when updating the +artists+ table in the update, a plain dataset is used, <tt>from(:artists)</tt>.
134
- This may look a little strange, but you need to be aware that inside an up or +down+ block in a migration,
135
- self always refers to the <tt>Sequel::Database</tt> object that the migration is being applied to.
136
- Since <tt>Database#from</tt> creates datasets, using <tt>from(:artists)</tt> inside the +up+ block creates
137
- a dataset on the database representing all columns in the +artists+ table, and updates it to set the
138
- +location+ column to <tt>'Sacramento'</tt>. You should avoid referencing the <tt>Sequel::Database</tt>
139
- object directly in your migration, and always use self to reference it, otherwise you may run into problems.
140
-
141
- == The +migration+ extension
142
-
143
- The migration code is not technically part of the core of Sequel. It's not loaded by default as it
144
- is only useful in specific cases. It is one of the extensions that ship with Sequel, which receive the same
145
- level of support as Sequel's core.
146
-
147
- If you want to play with Sequel's migration tools without using the <tt>bin/sequel</tt> tool, you
148
- need to load the migration extension manually:
149
-
150
- Sequel.extension :migration
151
-
152
- == Schema methods
153
-
154
- Migrations themselves do not contain any schema modification methods, but they make it easy to call
155
- any of the <tt>Sequel::Database</tt> modification methods, of which there are many. The main
156
- ones are +create_table+ and +alter_table+, but Sequel also comes with numerous other schema
157
- modification methods, most of which are shortcuts for +alter_table+ (all of these methods are
158
- described in more detail in the {schema modification guide}[rdoc-ref:doc/schema_modification.rdoc]):
159
-
160
- * add_column
161
- * add_index
162
- * create_view
163
- * drop_column
164
- * drop_index
165
- * drop_table
166
- * drop_view
167
- * rename_table
168
- * rename_column
169
- * set_column_default
170
- * set_column_type
171
-
172
- These methods handle the vast majority of cross database schema modification SQL. If you
173
- need to drop down to SQL to execute some database specific code, you can use the +run+
174
- method:
175
-
176
- Sequel.migration do
177
- up{run 'CREATE TRIGGER ...'}
178
- down{run 'DROP TRIGGER ...'}
179
- end
180
-
181
- In this case, we are using { and } instead of do and end to define the blocks. Just as
182
- before, the +run+ methods inside the blocks are called on the +Database+ object,
183
- which just executes the code on the underlying database.
184
-
185
- == Errors when running migrations
186
-
187
- Sequel attempts to run migrations inside of a transaction if the database supports
188
- transactional DDL statements. On the databases that don't support transactional DDL
189
- statements, if there is an error while running a migration, it will not rollback the
190
- previous schema changes made by the migration. In that case, you will
191
- need to update the database by hand.
192
-
193
- It's recommended to always run migrations on a test database and ensure they work
194
- before running them on any production database.
195
-
196
- == Transactions
197
-
198
- You can manually specify to use transactions on a per migration basis. For example,
199
- if you want to force transaction use for a particular migration, call the transaction
200
- method in the Sequel.migration block:
201
-
202
- Sequel.migration do
203
- transaction
204
- change do
205
- # ...
206
- end
207
- end
208
-
209
- Likewise, you can disable transaction use via no_transaction:
210
-
211
- Sequel.migration do
212
- no_transaction
213
- change do
214
- # ...
215
- end
216
- end
217
-
218
- This is necessary in some cases, such as when attempting to use CREATE INDEX CONCURRENTLY
219
- on PostgreSQL (which supports transactional schema, but not that statement inside a
220
- transaction).
221
-
222
- You can also override the transactions setting at the migrator level, either by forcing
223
- transactions even if no_transaction is set, or by disabling transactions all together:
224
-
225
- # Force transaction use
226
- Sequel::Migrator.run(DB, '/path/to/migrations/dir', :use_transactions=>true)
227
-
228
- # Disable use of transactions
229
- Sequel::Migrator.run(DB, '/path/to/migrations/dir', :use_transactions=>false)
230
-
231
- == Migration files
232
-
233
- While you can create migration objects yourself and apply them manually, most of the
234
- benefit to using migrations come from using Sequel's +Migrator+, which is what the
235
- <tt>bin/sequel -m</tt> switch does. Sequel's +Migrator+ expects that each migration
236
- will be in a separate file in a specific directory. The <tt>-m</tt> switch requires an
237
- argument be specified that is the path to the directory containing the migration files.
238
- For example:
239
-
240
- sequel -m db/migrations postgres://localhost/sequel_test
241
-
242
- will look in the <tt>db/migrations</tt> folder relative to the current directory,
243
- and run unapplied migrations on the PostgreSQL database sequel_test running on localhost.
244
-
245
- == Two separate migrators
246
-
247
- Sequel actually ships with two separate migrators. One is the +IntegerMigrator+, the other is
248
- the +TimestampMigrator+. They both have plusses and minuses:
249
-
250
- === +IntegerMigrator+
251
-
252
- * Simpler, uses migration versions starting with 1
253
- * Doesn't allow duplicate migrations
254
- * Doesn't allow missing migrations by default
255
- * Just stores the version of the last migration run
256
- * Good for single developer or small teams with close communication
257
- * Lower risk of undetected conflicting migrations
258
- * Requires manual merging of simultaneous migrations
259
-
260
- === +TimeStampMigrator+
261
-
262
- * More complex, uses migration versions where the version should represent a timestamp
263
- * Allows duplicate migrations (since you could have multiple in a given second)
264
- * Allows missing migrations (since you obviously don't have one every second)
265
- * Stores the file names of all applied migrations
266
- * Good for large teams without close communication
267
- * Higher risk of undetected conflicting migrations
268
- * Does not require manual merging of simultaneous migrations
269
-
270
- === Filenames
271
-
272
- In order for migration files to work with the Sequel, they must be specified as follows:
273
-
274
- version_name.rb
275
-
276
- where <tt>version</tt> is an integer and <tt>name</tt> is a string which should be a very brief
277
- description of what the migration does. Each migration class should contain 1 and only 1
278
- call to <tt>Sequel.migration</tt>.
279
-
280
- === +IntegerMigrator+ Filenames
281
-
282
- These are valid migration names for the +IntegerMigrator+:
283
-
284
- 1_create_artists.rb
285
- 2_add_artist_location.rb
286
-
287
- The only problem with this naming format is that if you have more than 9 migrations, the 10th
288
- one will look a bit odd:
289
-
290
- 1_create_artists.rb
291
- 2_add_artist_location.rb
292
- ...
293
- 9_do_something.rb
294
- 10_do_something_else.rb
295
-
296
- For this reasons, it's often best to start with 001 instead of 1, as that means you don't need
297
- to worry about that issue until the 1000th migration:
298
-
299
- 001_create_artists.rb
300
- 002_add_artist_location.rb
301
- ...
302
- 009_do_something.rb
303
- 010_do_something_else.rb
304
-
305
- Migrations start at 1, not 0. The migration version number 0
306
- is important though, as it is used to mean that all migrations should be unapplied (i.e. all
307
- +down+ blocks run). In Sequel, you can do that with:
308
-
309
- sequel -m db/migrations -M 0 postgres://localhost/sequel_test
310
-
311
- === +TimestampMigrator+ Filenames
312
-
313
- With the +TimestampMigrator+, the version integer should represent a timestamp, though this isn't strictly
314
- required.
315
-
316
- For example, for <tt>5/10/2010 12:00:00pm</tt>, you could use any of the following formats:
317
-
318
- # Date
319
- 20100510_create_artists.rb
320
-
321
- # Date and Time
322
- 20100510120000_create_artists.rb
323
-
324
- # Unix Epoch Time Integer
325
- 1273518000_create_artists.rb
326
-
327
- The important thing is that all migration files should be in the same format, otherwise when you
328
- update, it'll be difficult to make sure migrations are applied in the correct order, as well as
329
- be difficult to unapply some the affected migrations correctly.
330
-
331
- The +TimestampMigrator+ will be used if any filename in the migrations directory has a version
332
- greater than 20000101. Otherwise, the +IntegerMigrator+ will be used.
333
-
334
- You can force the use of the +TimestampMigrator+ in the API by calling TimestampMigrator.apply
335
- instead of Migrator.apply.
336
-
337
- === How to choose
338
-
339
- Basically, unless you need the features provided by the +TimestampMigrator+, stick with the
340
- +IntegerMigrator+, as it is simpler and makes it easier to detect possible errors.
341
-
342
- For a single developer, the +TimestampMigrator+ has no real benefits, so I would always recommend
343
- the +IntegerMigrator+. When dealing with multiple developers, it depends on the size of the
344
- development team, the team's communication level, and the level of overlap between developers.
345
-
346
- Let's say Alice works on a new feature that requires a migration at the same time Bob works
347
- on a separate feature that requires an unrelated migration. If both developers are committing
348
- to their own private respositories, when it comes time to merge, the +TimestampMigrator+ will not
349
- require any manually changes. That's because Alice will have a migration such as
350
- <tt>20100512_do_this.rb</tt> and Bob will have one such as <tt>20100512_do_that.rb</tt>.
351
-
352
- If the +IntegerMigrator+ was used, Alice would have <tt>34_do_this.rb</tt> and Bob would have
353
- <tt>34_do_that.rb</tt>. When the +IntegerMigrator+ was used, it would raise an exception due to
354
- the duplicate migration version. The only way to fix it would be to renumber one of the two
355
- migrations, and have the affected developer manually modify their database.
356
-
357
- So for unrelated migrations, the +TimestampMigrator+ works fine. However, let's say that the
358
- migrations are related, in such a way that if Bob's is run first, Alice's will fail. In this
359
- case, the +TimestampMigrator+ would not raise an error when Bob merges Alice's changes, since
360
- Bob ran his migration first. However, it would raise an error when Alice runs Bob's migration,
361
- and could leave the database in an inconsistent state if the database doesn't support transactional
362
- schema changes.
363
-
364
- With the +TimestampMigrator+, you are trading reliability for convenience. That's possibly a valid
365
- trade, especially if simultaneous related schema changes by separate developers are unlikely, but
366
- you should give it some thought before using it.
367
-
368
- == Ignoring missing migrations
369
-
370
- In some cases, you may want to allow a migration in the database that does not exist in the filesystem (deploying to an older version of code without running a down migration when deploy auto-migrates, for example). If required, you can pass <tt>allow_missing_migration_files: true</tt> as an option. This will stop errors from being raised if there are migrations in the database that do not exist in the filesystem. Note that the migrations themselves can still raise an error when using this option, if the database schema isn't in the state the migrations expect it to be in. In general, the <tt>allow_missing_migration_files: true</tt> option is very risky to use, and should only be used if it is absolutely necessary.
371
-
372
- == Modifying existing migrations
373
-
374
- Just don't do it.
375
-
376
- In general, you should not modify any migration that has been run on the database and been committed to
377
- the source control repository, unless the migration contains an error that causes data loss. As long
378
- as it is possible to undo the migration without losing data, you should just add another migration
379
- that undoes the actions of the previous bad migration, and does the correct action afterward.
380
-
381
- The main problem with modifying existing migrations is that you will have to manually modify any
382
- databases that ran the migration before it was modified. If you are a single developer, that may be
383
- an option, but certainly if you have multiple developers, it's a lot more work.
384
-
385
- == Creating a migration
386
-
387
- Sequel doesn't come with generators that create migrations for you. However, creating a migration
388
- is as simple as creating a file with the appropriate filename in your migrations directory that
389
- contains a <tt>Sequel.migration</tt> call. The minimal do-nothing migration is:
390
-
391
- Sequel.migration{}
392
-
393
- However, the migrations you write should contain an +up+ block that does something, and a +down+ block that
394
- reverses the changes made by the +up+ block:
395
-
396
- Sequel.migration do
397
- up{}
398
- down{}
399
- end
400
-
401
- or they should use the reversible migrations feature with a +change+ block:
402
-
403
- Sequel.migration do
404
- change{}
405
- end
406
-
407
- == What to put in your migration's +down+ block
408
-
409
- It's usually easy to determine what you should put in your migration's +up+ block,
410
- as it's whatever change you want to make to the database. The +down+ block is
411
- less obvious. In general, it should reverse the changes made by the +up+ block, which means
412
- it should execute the opposite of what the +up+ block does in the reverse order in which
413
- the +up+ block does it. Here's an example where you are switching from having a single
414
- artist per album to multiple artists per album:
415
-
416
- Sequel.migration do
417
- up do
418
- # Create albums_artists table
419
- create_join_table(album_id: :albums, artist_id: :artists)
420
-
421
- # Insert one row in the albums_artists table
422
- # for each row in the albums table where there
423
- # is an associated artist
424
- from(:albums_artists).insert([:album_id, :artist_id],
425
- from(:albums).select(:id, :artist_id).exclude(artist_id: nil))
426
-
427
- # Drop the now unnecesssary column from the albums table
428
- drop_column :albums, :artist_id
429
- end
430
- down do
431
- # Add the foreign key column back to the artists table
432
- alter_table(:albums){add_foreign_key :artist_id, :artists}
433
-
434
- # If possible, associate each album with one of the artists
435
- # it was associated with. This loses information, but
436
- # there's no way around that.
437
- from(:albums).update(artist_id: from(:albums_artists).
438
- select{max(artist_id)}.
439
- where(album_id: Sequel[:albums][:id])
440
- )
441
-
442
- # Drop the albums_artists table
443
- drop_join_table(album_id: :albums, artist_id: :artists)
444
- end
445
- end
446
-
447
- Note that the operations performed in the +down+ block are performed in the
448
- reverse order of how they are performed in the +up+ block. Also note how it
449
- isn't always possible to reverse exactly what was done in the +up+ block. You
450
- should try to do so as much as possible, but if you can't, you may want to have
451
- your +down+ block raise a <tt>Sequel::Error</tt> exception saying why the
452
- migration cannot be reverted.
453
-
454
- == Running migrations
455
-
456
- You can run migrations using the +sequel+ command line program that
457
- comes with Sequel. If you use the <tt>-m</tt> switch, +sequel+ will
458
- run the migrator instead of giving you an IRB session. The <tt>-m</tt>
459
- switch requires an argument that should be a path to a directory of migration
460
- files:
461
-
462
- sequel -m relative/path/to/migrations postgres://host/database
463
- sequel -m /absolute/path/to/migrations postgres://host/database
464
-
465
- If you do not provide a <tt>-M</tt> switch, +sequel+ will migrate to the latest
466
- version in the directory. If you provide a <tt>-M</tt> switch, it should specify
467
- an integer version to which to migrate.
468
-
469
- # Migrate all the way down
470
- sequel -m db/migrations -M 0 postgres://host/database
471
-
472
- # Migrate to version 10 (IntegerMigrator style migrations)
473
- sequel -m db/migrations -M 10 postgres://host/database
474
-
475
- # Migrate to version 20100510 (TimestampMigrator migrations using YYYYMMDD)
476
- sequel -m db/migrations -M 20100510 postgres://host/database
477
-
478
- Whether or not migrations use the +up+ or +down+ block depends on the version
479
- to which you are migrating. If you don't provide a <tt>-M</tt> switch, all
480
- unapplied migrations will be migrated up. If you provide a <tt>-M</tt>, it will
481
- depend on which migrations that have been applied. Applied migrations greater
482
- than that version will be migrated down, while unapplied migrations less than
483
- or equal to that version will be migrated up.
484
-
485
- == Running migrations from a Rake task
486
-
487
- You can also incorporate migrations into a Rakefile:
488
-
489
- namespace :db do
490
- desc "Run migrations"
491
- task :migrate, [:version] do |t, args|
492
- require "sequel/core"
493
- Sequel.extension :migration
494
- version = args[:version].to_i if args[:version]
495
- Sequel.connect(ENV.fetch("DATABASE_URL")) do |db|
496
- Sequel::Migrator.run(db, "db/migrations", target: version)
497
- end
498
- end
499
- end
500
-
501
- To migrate to the latest version, run:
502
-
503
- rake db:migrate
504
-
505
- This Rake task takes an optional argument specifying the target
506
- version. To migrate to version 42, run:
507
-
508
- rake db:migrate[42]
509
-
510
- == Verbose migrations
511
-
512
- By default, <tt>sequel -m</tt> operates as a well behaved command line utility
513
- should, printing out nothing if there is no error. If you want to see the SQL
514
- being executed during a migration, as well as the amount of time that each
515
- migration takes, you can use the <tt>-E</tt> option to +sequel+ to set up a
516
- +Database+ logger that logs to +STDOUT+. You can also log that same output to
517
- a file using the <tt>-l</tt> option with a log file name.
518
-
519
- If you want to include a logger in the rake task above, add a +:logger+ option
520
- when calling Sequel.connect:
521
-
522
- require "logger"
523
- Sequel.connect(ENV.fetch("DATABASE_URL"), logger: Logger.new($stderr))
524
-
525
- == Using models in your migrations
526
-
527
- Just don't do it.
528
-
529
- It can be tempting to use models in your migrations, especially since it's easy
530
- to load them at the same time using the <tt>-L</tt> option to +sequel+. However,
531
- this ties your migrations to your models, and makes it so that changes in your
532
- models can break old migrations.
533
-
534
- With Sequel, it should be easy to use plain datasets to accomplish pretty much
535
- anything you would want to accomplish in a migration. Even if you have to
536
- copy some code from a model method into a migration itself, it's better than
537
- having your migration use models and call model methods.
538
-
539
- == Dumping the current schema as a migration
540
-
541
- Sequel comes with a +schema_dumper+ extension that dumps the current schema of
542
- the database as a migration to +STDOUT+ (which you can redirect to a file using
543
- >). This is exposed in the +sequel+ command line tool with the <tt>-d</tt> and
544
- <tt>-D</tt> switches. <tt>-d</tt> dumps the schema in database independent
545
- format, while <tt>-D</tt> dumps the schema using a non-portable format, useful
546
- if you are using nonportable columns such as +inet+ in your database.
547
-
548
- Let's say you have an existing database and want to create a migration that
549
- would recreate the database's schema:
550
-
551
- sequel -d postgres://host/database > db/migrations/001_start.rb
552
-
553
- or using a nonportable format:
554
-
555
- sequel -D postgres://host/database > db/migrations/001_start.rb
556
-
557
- The main difference between the two is that <tt>-d</tt> will use the type methods
558
- with the database independent ruby class types, while <tt>-D</tt> will use
559
- the +column+ method with string types.
560
-
561
- You can take the migration created by the schema dumper to another computer
562
- with an empty database, and attempt to recreate the schema using:
563
-
564
- sequel -m db/migrations postgres://host/database
565
-
566
- The schema_dumper extension is quite limited in what types of
567
- database objects it supports. In general, it only supports
568
- dumping tables, columns, primary key and foreign key constraints,
569
- and some indexes. It does not support most table options, CHECK
570
- constraints, partial indexes, database functions, triggers,
571
- security grants/revokes, and a wide variety of other useful
572
- database properties. Be aware of the limitations when using the
573
- schema_dumper extension. If you are dumping the schema to restore
574
- to the same database type, it is recommended to use your database's
575
- dump and restore programs instead of the schema_dumper extension.
576
-
577
- == Checking for Current Migrations
578
-
579
- In your application code, you may want to check that you are up to date in
580
- regards to migrations (i.e. you don't have any unapplied migrations). Sequel
581
- offers two separate methods to do that. The first is Sequel::Migrator.check_current.
582
- This method raises an exception if there are outstanding migrations that need to
583
- be run. The second is Sequel::Migrator.is_current?, which returns true if there
584
- are no outstanding migrations, and false if there are outstanding migrations.
585
-
586
- If you want to ensure that your application code is up to date, you may want to
587
- add the following code after connecting to your database:
588
-
589
- Sequel.extension :migration
590
- Sequel::Migrator.check_current(DB, '/path/to/migrations')
591
-
592
- This will cause your application to raise an error when you start it if you have
593
- any outstanding migrations.
594
-
595
- == Old-style migration classes
596
-
597
- Before the <tt>Sequel.migration</tt> DSL was introduced, Sequel used classes
598
- for Migrations:
599
-
600
- Class.new(Sequel::Migration) do
601
- def up
602
- end
603
- def down
604
- end
605
- end
606
-
607
- or:
608
-
609
- class DoSomething < Sequel::Migration
610
- def up
611
- end
612
- def down
613
- end
614
- end
615
-
616
- This usage is discouraged in new code, but will continue to be supported indefinitely.
617
- It is not recommended to convert old-style migration classes to the <tt>Sequel.migration</tt>
618
- DSL, but it is recommended to use the <tt>Sequel.migration</tt> DSL for all new migrations.
619
-
620
- == Database-specific migrations
621
-
622
- While not a recommended practice, it is sometimes necessary to have parts of migrations be
623
- database-specific . You can use the Sequel::Database#database_type method to check which
624
- database the migration is being run on, and operate accordingly:
625
-
626
- Sequel.migration do
627
- up do
628
- if database_type == :mysql
629
- run 'MySQL specific code'
630
- else
631
- run 'Generic SQL code'
632
- end
633
- end
634
-
635
- down do
636
- if database_type == :mysql
637
- run 'MySQL specific code'
638
- else
639
- run 'Generic SQL code'
640
- end
641
- end
642
- end
643
-
644
- == Using Database Extensions in Migrations
645
-
646
- If you need to use database extensions in migrations (e.g. +:pg_enum+), you should load the extension in the up or down block as appropriate.
647
-
648
- Sequel.migration do
649
- up do
650
- extension :pg_enum
651
-
652
- # migration here
653
- end
654
-
655
- down do
656
- extension :pg_enum
657
-
658
- # migration here
659
- end
660
- end