sequel 5.82.0 → 5.84.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (135) hide show
  1. checksums.yaml +4 -4
  2. data/bin/sequel +9 -17
  3. data/lib/sequel/adapters/jdbc/derby.rb +1 -1
  4. data/lib/sequel/adapters/shared/db2.rb +1 -1
  5. data/lib/sequel/adapters/shared/mssql.rb +14 -2
  6. data/lib/sequel/adapters/shared/postgres.rb +42 -4
  7. data/lib/sequel/adapters/shared/sqlite.rb +3 -1
  8. data/lib/sequel/database/connecting.rb +1 -4
  9. data/lib/sequel/database/misc.rb +27 -7
  10. data/lib/sequel/database/schema_methods.rb +17 -1
  11. data/lib/sequel/dataset/sql.rb +13 -0
  12. data/lib/sequel/extensions/pg_json_ops.rb +328 -1
  13. data/lib/sequel/extensions/stdio_logger.rb +48 -0
  14. data/lib/sequel/extensions/string_agg.rb +15 -2
  15. data/lib/sequel/plugins/defaults_setter.rb +16 -4
  16. data/lib/sequel/plugins/optimistic_locking.rb +2 -0
  17. data/lib/sequel/sql.rb +8 -5
  18. data/lib/sequel/version.rb +1 -1
  19. metadata +4 -235
  20. data/CHANGELOG +0 -1377
  21. data/README.rdoc +0 -936
  22. data/doc/advanced_associations.rdoc +0 -884
  23. data/doc/association_basics.rdoc +0 -1859
  24. data/doc/bin_sequel.rdoc +0 -146
  25. data/doc/cheat_sheet.rdoc +0 -255
  26. data/doc/code_order.rdoc +0 -104
  27. data/doc/core_extensions.rdoc +0 -405
  28. data/doc/dataset_basics.rdoc +0 -96
  29. data/doc/dataset_filtering.rdoc +0 -222
  30. data/doc/extensions.rdoc +0 -77
  31. data/doc/fork_safety.rdoc +0 -84
  32. data/doc/mass_assignment.rdoc +0 -98
  33. data/doc/migration.rdoc +0 -660
  34. data/doc/model_dataset_method_design.rdoc +0 -129
  35. data/doc/model_hooks.rdoc +0 -254
  36. data/doc/model_plugins.rdoc +0 -270
  37. data/doc/mssql_stored_procedures.rdoc +0 -43
  38. data/doc/object_model.rdoc +0 -563
  39. data/doc/opening_databases.rdoc +0 -439
  40. data/doc/postgresql.rdoc +0 -611
  41. data/doc/prepared_statements.rdoc +0 -144
  42. data/doc/querying.rdoc +0 -1070
  43. data/doc/reflection.rdoc +0 -120
  44. data/doc/release_notes/5.0.0.txt +0 -159
  45. data/doc/release_notes/5.1.0.txt +0 -31
  46. data/doc/release_notes/5.10.0.txt +0 -84
  47. data/doc/release_notes/5.11.0.txt +0 -83
  48. data/doc/release_notes/5.12.0.txt +0 -141
  49. data/doc/release_notes/5.13.0.txt +0 -27
  50. data/doc/release_notes/5.14.0.txt +0 -63
  51. data/doc/release_notes/5.15.0.txt +0 -39
  52. data/doc/release_notes/5.16.0.txt +0 -110
  53. data/doc/release_notes/5.17.0.txt +0 -31
  54. data/doc/release_notes/5.18.0.txt +0 -69
  55. data/doc/release_notes/5.19.0.txt +0 -28
  56. data/doc/release_notes/5.2.0.txt +0 -33
  57. data/doc/release_notes/5.20.0.txt +0 -89
  58. data/doc/release_notes/5.21.0.txt +0 -87
  59. data/doc/release_notes/5.22.0.txt +0 -48
  60. data/doc/release_notes/5.23.0.txt +0 -56
  61. data/doc/release_notes/5.24.0.txt +0 -56
  62. data/doc/release_notes/5.25.0.txt +0 -32
  63. data/doc/release_notes/5.26.0.txt +0 -35
  64. data/doc/release_notes/5.27.0.txt +0 -21
  65. data/doc/release_notes/5.28.0.txt +0 -16
  66. data/doc/release_notes/5.29.0.txt +0 -22
  67. data/doc/release_notes/5.3.0.txt +0 -121
  68. data/doc/release_notes/5.30.0.txt +0 -20
  69. data/doc/release_notes/5.31.0.txt +0 -148
  70. data/doc/release_notes/5.32.0.txt +0 -46
  71. data/doc/release_notes/5.33.0.txt +0 -24
  72. data/doc/release_notes/5.34.0.txt +0 -40
  73. data/doc/release_notes/5.35.0.txt +0 -56
  74. data/doc/release_notes/5.36.0.txt +0 -60
  75. data/doc/release_notes/5.37.0.txt +0 -30
  76. data/doc/release_notes/5.38.0.txt +0 -28
  77. data/doc/release_notes/5.39.0.txt +0 -19
  78. data/doc/release_notes/5.4.0.txt +0 -80
  79. data/doc/release_notes/5.40.0.txt +0 -40
  80. data/doc/release_notes/5.41.0.txt +0 -25
  81. data/doc/release_notes/5.42.0.txt +0 -136
  82. data/doc/release_notes/5.43.0.txt +0 -98
  83. data/doc/release_notes/5.44.0.txt +0 -32
  84. data/doc/release_notes/5.45.0.txt +0 -34
  85. data/doc/release_notes/5.46.0.txt +0 -87
  86. data/doc/release_notes/5.47.0.txt +0 -59
  87. data/doc/release_notes/5.48.0.txt +0 -14
  88. data/doc/release_notes/5.49.0.txt +0 -59
  89. data/doc/release_notes/5.5.0.txt +0 -61
  90. data/doc/release_notes/5.50.0.txt +0 -78
  91. data/doc/release_notes/5.51.0.txt +0 -47
  92. data/doc/release_notes/5.52.0.txt +0 -87
  93. data/doc/release_notes/5.53.0.txt +0 -23
  94. data/doc/release_notes/5.54.0.txt +0 -27
  95. data/doc/release_notes/5.55.0.txt +0 -21
  96. data/doc/release_notes/5.56.0.txt +0 -51
  97. data/doc/release_notes/5.57.0.txt +0 -23
  98. data/doc/release_notes/5.58.0.txt +0 -31
  99. data/doc/release_notes/5.59.0.txt +0 -73
  100. data/doc/release_notes/5.6.0.txt +0 -31
  101. data/doc/release_notes/5.60.0.txt +0 -22
  102. data/doc/release_notes/5.61.0.txt +0 -43
  103. data/doc/release_notes/5.62.0.txt +0 -132
  104. data/doc/release_notes/5.63.0.txt +0 -33
  105. data/doc/release_notes/5.64.0.txt +0 -50
  106. data/doc/release_notes/5.65.0.txt +0 -21
  107. data/doc/release_notes/5.66.0.txt +0 -24
  108. data/doc/release_notes/5.67.0.txt +0 -32
  109. data/doc/release_notes/5.68.0.txt +0 -61
  110. data/doc/release_notes/5.69.0.txt +0 -26
  111. data/doc/release_notes/5.7.0.txt +0 -108
  112. data/doc/release_notes/5.70.0.txt +0 -35
  113. data/doc/release_notes/5.71.0.txt +0 -21
  114. data/doc/release_notes/5.72.0.txt +0 -33
  115. data/doc/release_notes/5.73.0.txt +0 -66
  116. data/doc/release_notes/5.74.0.txt +0 -45
  117. data/doc/release_notes/5.75.0.txt +0 -35
  118. data/doc/release_notes/5.76.0.txt +0 -86
  119. data/doc/release_notes/5.77.0.txt +0 -63
  120. data/doc/release_notes/5.78.0.txt +0 -67
  121. data/doc/release_notes/5.79.0.txt +0 -28
  122. data/doc/release_notes/5.8.0.txt +0 -170
  123. data/doc/release_notes/5.80.0.txt +0 -40
  124. data/doc/release_notes/5.81.0.txt +0 -31
  125. data/doc/release_notes/5.82.0.txt +0 -61
  126. data/doc/release_notes/5.9.0.txt +0 -99
  127. data/doc/schema_modification.rdoc +0 -679
  128. data/doc/security.rdoc +0 -443
  129. data/doc/sharding.rdoc +0 -286
  130. data/doc/sql.rdoc +0 -648
  131. data/doc/testing.rdoc +0 -204
  132. data/doc/thread_safety.rdoc +0 -15
  133. data/doc/transactions.rdoc +0 -250
  134. data/doc/validations.rdoc +0 -558
  135. data/doc/virtual_rows.rdoc +0 -265
@@ -1,679 +0,0 @@
1
- = Schema modification methods
2
-
3
- Here's a brief description of the most common schema modification methods:
4
-
5
- == +create_table+
6
-
7
- +create_table+ is the most common schema modification method, and it's used for adding new tables
8
- to the database. You provide it with the name of the table as a symbol, as well a block:
9
-
10
- create_table(:artists) do
11
- primary_key :id
12
- String :name
13
- end
14
-
15
- Note that if you want a primary key for the table, you need to specify it, Sequel does not create one
16
- by default.
17
-
18
- === Column types
19
-
20
- Most method calls inside the create_table block will create columns, since +method_missing+ calls +column+.
21
- Columns are generally created by specifying the column type as the method
22
- name, followed by the column name symbol to use, and after that any options that should be used.
23
- If the method is a ruby class name that Sequel recognizes, Sequel will transform it into the appropriate
24
- type for the given database. So while you specified +String+, Sequel will actually use +varchar+ or
25
- +text+ depending on the underlying database. Here's a list of all ruby classes that Sequel will
26
- convert to database types:
27
-
28
- create_table(:columns_types) do # common database type used
29
- Integer :a0 # integer
30
- String :a1 # varchar(255)
31
- String :a2, size: 50 # varchar(50)
32
- String :a3, fixed: true # char(255)
33
- String :a4, fixed: true, size: 50 # char(50)
34
- String :a5, text: true # text
35
- File :b # blob
36
- Fixnum :c # integer
37
- Bignum :d # bigint
38
- Float :e # double precision
39
- BigDecimal :f # numeric
40
- BigDecimal :f2, size: 10 # numeric(10)
41
- BigDecimal :f3, size: [10, 2] # numeric(10, 2)
42
- Date :g # date
43
- DateTime :h # timestamp
44
- Time :i # timestamp
45
- Time :i2, only_time: true # time
46
- Numeric :j # numeric
47
- TrueClass :k # boolean
48
- FalseClass :l # boolean
49
- end
50
-
51
- Note that in addition to the ruby class name, Sequel also pays attention to the column options when
52
- determining which database type to use. Also note that for boolean columns, you can use either
53
- TrueClass or FalseClass, they are treated the same way (ruby doesn't have a Boolean class).
54
-
55
- Also note that this conversion is only done if you use a supported ruby class name. In all other
56
- cases, Sequel uses the type specified verbatim:
57
-
58
- create_table(:columns_types) do # database type used
59
- string :a1 # string
60
- datetime :a2 # datetime
61
- blob :a3 # blob
62
- inet :a4 # inet
63
- end
64
-
65
- In addition to specifying the types as methods, you can use the +column+ method and specify the types
66
- as the second argument, either as ruby classes, symbols, or strings:
67
-
68
- create_table(:columns_types) do # database type used
69
- column :a1, :string # string
70
- column :a2, String # varchar(255)
71
- column :a3, 'string' # string
72
- column :a4, :datetime # datetime
73
- column :a5, DateTime # timestamp
74
- column :a6, 'timestamp(6)' # timestamp(6)
75
- end
76
-
77
- If you use a ruby class as the type, Sequel will try to guess the appropriate type name for the
78
- database you are using. If a symbol or string is used as the type, it is used verbatim as the type
79
- name in SQL, with the exception of :Bignum. Using the symbol :Bignum as a type will use the
80
- appropriate 64-bit integer type for the database you are using.
81
-
82
- === Column options
83
-
84
- When using the type name as method, the second argument is an options hash, and when using the +column+
85
- method, the third argument is the options hash. The following options are supported:
86
-
87
- :default :: The default value for the column.
88
- :index :: Create an index on this column. If given a hash, use the hash as the
89
- options for the index.
90
- :null :: Mark the column as allowing NULL values (if true),
91
- or not allowing NULL values (if false). If unspecified, will default
92
- to whatever the database default is (usually true).
93
- :primary_key :: Mark this column as the primary key. This is used instead of the
94
- primary key method if you want a non-autoincrementing primary key.
95
- :primary_key_constraint_name :: The name to give the primary key constraint.
96
- :type :: Overrides the type given as the method name or a separate argument.
97
- Not usually used by +column+ itself, but often by other methods such
98
- as +primary_key+ or +foreign_key+.
99
- :unique :: Mark the column as unique, generally has the same effect as
100
- creating a unique index on the column.
101
- :unique_constraint_name :: The name to give the unique constraint.
102
-
103
- === Other methods
104
-
105
- In addition to the +column+ method and other methods that create columns, there are other methods that can be used:
106
-
107
- ==== +primary_key+
108
-
109
- You've seen this one used already. It's used to create an autoincrementing integer primary key column.
110
-
111
- create_table(:a0){primary_key :id}
112
-
113
- If you want an autoincrementing 64-bit integer:
114
-
115
- create_table(:a0){primary_key :id, type: :Bignum}
116
-
117
- If you want to create a primary key column that doesn't use an autoincrementing integer, you should
118
- not use this method. Instead, you should use the :primary_key option to the +column+ method or type
119
- method:
120
-
121
- create_table(:a1){Integer :id, primary_key: true} # Non autoincrementing integer primary key
122
- create_table(:a2){String :name, primary_key: true} # varchar(255) primary key
123
-
124
- If you want to create a composite primary key, you should call the +primary_key+ method with an
125
- array of column symbols. You can provide a specific name to use for the primary key constraint
126
- via the :name option:
127
-
128
- create_table(:items) do
129
- Integer :group_id
130
- Integer :position
131
- primary_key [:group_id, :position], name: :items_pk
132
- end
133
-
134
- If provided with an array, +primary_key+ does not create a column, it just sets up the primary key constraint.
135
-
136
- ==== +foreign_key+
137
-
138
- +foreign_key+ is used to create a foreign key column that references a column in another table (or the same table).
139
- It takes the column name as the first argument, the table it references as the second argument, and an options hash
140
- as its third argument. A simple example is:
141
-
142
- create_table(:albums) do
143
- primary_key :id
144
- foreign_key :artist_id, :artists
145
- String :name
146
- end
147
-
148
- +foreign_key+ accepts the same options as +column+. For example, to have a unique foreign key with varchar(16) type:
149
-
150
- foreign_key :column_name, :table, unique: true, type: 'varchar(16)'
151
-
152
- +foreign_key+ also accepts some specific options:
153
-
154
- :deferrable :: Makes the foreign key constraint checks deferrable, so they aren't checked
155
- until the end of the transaction.
156
- :foreign_key_constraint_name :: The name to give the foreign key constraint.
157
- :key :: The column in the associated table
158
- that this column references. Unnecessary if this column
159
- references the primary key of the associated table, at least
160
- on most databases.
161
- :on_delete :: Specify the behavior of this foreign key column when the row with the primary key
162
- it references is deleted, can be :restrict, :cascade, :set_null, or :set_default.
163
- You can also use a string, which is used literally.
164
- :on_update :: Specify the behavior of this foreign key column when the row with the primary key
165
- it references modifies the value of the primary key. Takes the same options as
166
- :on_delete.
167
-
168
- Like +primary_key+, if you provide +foreign_key+ with an array of symbols, it will not create a
169
- column, but create a foreign key constraint:
170
-
171
- create_table(:artists) do
172
- String :name
173
- String :location
174
- primary_key [:name, :location]
175
- end
176
- create_table(:albums) do
177
- String :artist_name
178
- String :artist_location
179
- String :name
180
- foreign_key [:artist_name, :artist_location], :artists
181
- end
182
-
183
- When using an array of symbols, you can also provide a :name option to name the constraint:
184
-
185
- create_table(:albums) do
186
- String :artist_name
187
- String :artist_location
188
- String :name
189
- foreign_key [:artist_name, :artist_location], :artists, name: 'albums_artist_name_location_fkey'
190
- end
191
-
192
- If you want to add a foreign key for a single column with a named constraint, you must use
193
- the array form with a single symbol:
194
-
195
- create_table(:albums) do
196
- primary_key :id
197
- Integer :artist_id
198
- String :name
199
- foreign_key [:artist_id], :artists, name: 'albums_artist_id_fkey'
200
- end
201
-
202
- ==== +index+
203
-
204
- +index+ creates indexes on the table. For single columns, calling index is the same as using the
205
- <tt>:index</tt> option when creating the column:
206
-
207
- create_table(:a){Integer :id, index: true}
208
- # Same as:
209
- create_table(:a) do
210
- Integer :id
211
- index :id
212
- end
213
-
214
- create_table(:a){Integer :id, index: {unique: true}}
215
- # Same as:
216
- create_table(:a) do
217
- Integer :id
218
- index :id, unique: true
219
- end
220
-
221
- Similar to the +primary_key+ and +foreign_key+ methods, calling +index+ with an array of symbols
222
- will create a multiple column index:
223
-
224
- create_table(:albums) do
225
- primary_key :id
226
- foreign_key :artist_id, :artists
227
- Integer :position
228
- index [:artist_id, :position]
229
- end
230
-
231
- The +index+ method also accepts some options:
232
-
233
- :name :: The name of the index (generated based on the table and column names if not provided).
234
- :type :: The type of index to use (only supported by some databases)
235
- :unique :: Make the index unique, so duplicate values are not allowed.
236
- :where :: Create a partial index (only supported by some databases)
237
-
238
- ==== +unique+
239
-
240
- The +unique+ method creates a unique constraint on the table. A unique constraint generally
241
- operates identically to a unique index, so the following three +create_table+ blocks are
242
- pretty much identical:
243
-
244
- create_table(:a){Integer :a, unique: true}
245
-
246
- create_table(:a) do
247
- Integer :a
248
- index :a, unique: true
249
- end
250
-
251
- create_table(:a) do
252
- Integer :a
253
- unique :a
254
- end
255
-
256
- Just like +index+, +unique+ can set up a multiple column unique constraint, where the
257
- combination of the columns must be unique:
258
-
259
- create_table(:a) do
260
- Integer :a
261
- Integer :b
262
- unique [:a, :b]
263
- end
264
-
265
- ==== +full_text_index+ and +spatial_index+
266
-
267
- Both of these create specialized index types supported by some databases. They
268
- both take the same options as +index+.
269
-
270
- ==== +constraint+
271
-
272
- +constraint+ creates a named table constraint:
273
-
274
- create_table(:artists) do
275
- primary_key :id
276
- String :name
277
- constraint(:name_min_length){char_length(name) > 2}
278
- end
279
-
280
- Instead of using a block, you can use arguments that will be handled similarly
281
- to <tt>Dataset#where</tt>:
282
-
283
- create_table(:artists) do
284
- primary_key :id
285
- String :name
286
- constraint(:name_length_range, Sequel.function(:char_length, :name)=>3..50)
287
- end
288
-
289
- ==== +check+
290
-
291
- +check+ operates just like +constraint+, except that it doesn't take a name
292
- and it creates an unnamed constraint:
293
-
294
- create_table(:artists) do
295
- primary_key :id
296
- String :name
297
- check{char_length(name) > 2}
298
- end
299
-
300
- It's recommended that you use the +constraint+ method and provide a name for the
301
- constraint, as that makes it easier to drop the constraint later if necessary.
302
-
303
- == +create_join_table+
304
-
305
- +create_join_table+ is a shortcut that you can use to create simple many-to-many join tables:
306
-
307
- create_join_table(artist_id: :artists, album_id: :albums)
308
-
309
- which expands to:
310
-
311
- create_table(:albums_artists) do
312
- foreign_key :album_id, :albums
313
- foreign_key :artist_id, :artists
314
- primary_key [:album_id, :artist_id]
315
- index [:artist_id, :album_id]
316
- end
317
-
318
- == <tt>create_table :as</tt>
319
-
320
- To create a table from the result of a SELECT query, instead of passing a block
321
- to +create_table+, provide a dataset to the :as option:
322
-
323
- create_table(:older_items, as: DB[:items].where{updated_at < Date.today << 6})
324
-
325
- == +alter_table+
326
-
327
- +alter_table+ is used to alter existing tables, changing their columns, indexes,
328
- or constraints. It it used just like +create_table+, accepting a block which
329
- is instance_evaled, and providing its own methods:
330
-
331
- === +add_column+
332
-
333
- One of the most common methods, +add_column+ is used to add a column to the table.
334
- Its API is similar to that of +create_table+'s +column+ method, where the first
335
- argument is the column name, the second is the type, and the third is an options
336
- hash:
337
-
338
- alter_table(:albums) do
339
- add_column :copies_sold, Integer, default: 0
340
- end
341
-
342
- === +drop_column+
343
-
344
- As you may expect, +drop_column+ takes a column name and drops the column. It's
345
- often used in the +down+ block of a migration to drop a column added in an +up+ block:
346
-
347
- alter_table(:albums) do
348
- drop_column :copies_sold
349
- end
350
-
351
- === +rename_column+
352
-
353
- +rename_column+ is used to rename a column. It takes the old column name as the first
354
- argument, and the new column name as the second argument:
355
-
356
- alter_table(:albums) do
357
- rename_column :copies_sold, :total_sales
358
- end
359
-
360
- === +add_primary_key+
361
-
362
- If you forgot to include a primary key on the table, and want to add one later, you
363
- can use +add_primary_key+. A common use of this is to make many_to_many association
364
- join tables into real models:
365
-
366
- alter_table(:albums_artists) do
367
- add_primary_key :id
368
- end
369
-
370
- Just like +create_table+'s +primary_key+ method, if you provide an array of symbols,
371
- Sequel will not add a column, but will add a composite primary key constraint:
372
-
373
- alter_table(:albums_artists) do
374
- add_primary_key [:album_id, :artist_id]
375
- end
376
-
377
- It is possible to specify a name for the primary key constraint: via the :name option:
378
-
379
- alter_table(:albums_artists) do
380
- add_primary_key [:album_id, :artist_id], name: :albums_artists_pkey
381
- end
382
-
383
- If you just want to take an existing single column and make it a primary key, call
384
- +add_primary_key+ with an array with a single symbol:
385
-
386
- alter_table(:artists) do
387
- add_primary_key [:id]
388
- end
389
-
390
- === +add_foreign_key+
391
-
392
- +add_foreign_key+ can be used to add a new foreign key column or constraint to a table.
393
- Like +add_primary_key+, if you provide it with a symbol as the first argument, it
394
- creates a new column:
395
-
396
- alter_table(:albums) do
397
- add_foreign_key :artist_id, :artists
398
- end
399
-
400
- If you want to add a new foreign key constraint to an existing column, you provide an
401
- array with a single element:
402
-
403
- alter_table(:albums) do
404
- add_foreign_key [:artist_id], :artists
405
- end
406
-
407
- It's encouraged to provide a name when adding the constraint, via the :foreign_key_constraint_name
408
- option if adding the column and the constraint:
409
-
410
- alter_table(:albums) do
411
- add_foreign_key :artist_id, :artists, foreign_key_constraint_name: :albums_artist_id_fkey
412
- end
413
-
414
- or via the :name option if just adding the constraint:
415
-
416
- alter_table(:albums) do
417
- add_foreign_key [:artist_id], :artists, name: :albums_artist_id_fkey
418
- end
419
-
420
- To set up a multiple column foreign key constraint, use an array with multiple column symbols:
421
-
422
- alter_table(:albums) do
423
- add_foreign_key [:artist_name, :artist_location], :artists, name: :albums_artist_name_location_fkey
424
- end
425
-
426
- === +drop_foreign_key+
427
-
428
- +drop_foreign_key+ is used to drop foreign keys from tables. If you provide a symbol as
429
- the first argument, it drops both the foreign key constraint and the column:
430
-
431
- alter_table(:albums) do
432
- drop_foreign_key :artist_id
433
- end
434
-
435
- If you want to just drop the foreign key constraint without dropping the column, use
436
- an array. It's encouraged to use the :name option to provide the constraint name to
437
- drop, though on some databases Sequel may be able to find the name through introspection:
438
-
439
- alter_table(:albums) do
440
- drop_foreign_key [:artist_id], name: :albums_artist_id_fkey
441
- end
442
-
443
- An array is also used to drop a composite foreign key constraint:
444
-
445
- alter_table(:albums) do
446
- drop_foreign_key [:artist_name, :artist_location], name: :albums_artist_name_location_fkey
447
- end
448
-
449
- If you do not provide a :name option and Sequel is not able to determine the name
450
- to use, it will probably raise a Sequel::Error exception.
451
-
452
- === +add_index+
453
-
454
- +add_index+ works just like +create_table+'s +index+ method, creating a new index on
455
- the table:
456
-
457
- alter_table(:albums) do
458
- add_index :artist_id
459
- end
460
-
461
- It accepts the same options as +create_table+'s +index+ method, and you can set up
462
- a multiple column index using an array:
463
-
464
- alter_table(:albums_artists) do
465
- add_index [:album_id, :artist_id], unique: true
466
- end
467
-
468
- === +drop_index+
469
-
470
- As you may expect, +drop_index+ drops an existing index:
471
-
472
- alter_table(:albums) do
473
- drop_index :artist_id
474
- end
475
-
476
- Just like +drop_column+, it is often used in the +down+ block of a migration.
477
-
478
- To drop an index with a specific name, use the <tt>:name</tt> option:
479
-
480
- alter_table(:albums) do
481
- drop_index :artist_id, name: :artists_id_index
482
- end
483
-
484
- === +add_full_text_index+, +add_spatial_index+
485
-
486
- Corresponding to +create_table+'s +full_text_index+ and +spatial_index+ methods,
487
- these two methods create new indexes on the table.
488
-
489
- === +add_constraint+
490
-
491
- This adds a named constraint to the table, similar to +create_table+'s +constraint+
492
- method:
493
-
494
- alter_table(:albums) do
495
- add_constraint(:name_min_length){char_length(name) > 2}
496
- end
497
-
498
- There is no method to add an unnamed constraint, but you can pass +nil+ as the first
499
- argument of +add_constraint+ to do so. However, it's not recommended to do that
500
- as it is more difficult to drop such a constraint.
501
-
502
- === +add_unique_constraint+
503
-
504
- This adds a unique constraint to the table, similar to +create_table+'s +unique+
505
- method. This usually has the same effect as adding a unique index.
506
-
507
- alter_table(:albums) do
508
- add_unique_constraint [:artist_id, :name]
509
- end
510
-
511
- You can also specify a name via the :name option when adding the constraint:
512
-
513
- alter_table(:albums) do
514
- add_unique_constraint [:artist_id, :name], name: :albums_artist_id_name_ukey
515
- end
516
-
517
- === +drop_constraint+
518
-
519
- This method drops an existing named constraint:
520
-
521
- alter_table(:albums) do
522
- drop_constraint(:name_min_length)
523
- end
524
-
525
- There is no database independent method to drop an unnamed constraint. Generally, the
526
- database will give it a name automatically, and you will have to figure out what it is.
527
- For that reason, you should not add unnamed constraints that you ever might need to remove.
528
-
529
- On some databases, you must specify the type of constraint via a <tt>:type</tt> option:
530
-
531
- alter_table(:albums) do
532
- drop_constraint(:albums_pk, type: :primary_key)
533
- drop_constraint(:albums_fk, type: :foreign_key)
534
- drop_constraint(:albums_uk, type: :unique)
535
- end
536
-
537
- === +set_column_default+
538
-
539
- This modifies the default value of a column:
540
-
541
- alter_table(:albums) do
542
- set_column_default :copies_sold, 0
543
- end
544
-
545
- To remove a default value for a column, use +nil+ as the value:
546
-
547
- alter_table(:albums) do
548
- set_column_default :copies_sold, nil
549
- end
550
-
551
- === +set_column_type+
552
-
553
- This modifies a column's type. Most databases will attempt to convert existing values in
554
- the columns to the new type:
555
-
556
- alter_table(:albums) do
557
- set_column_type :copies_sold, :Bignum
558
- end
559
-
560
- You can specify the type as a string or symbol, in which case it is used verbatim, or as a supported
561
- ruby class or the :Bignum symbol, in which case it gets converted to an appropriate database type.
562
-
563
- === +set_column_allow_null+
564
-
565
- This allows you to set the column as allowing NULL values:
566
-
567
- alter_table(:albums) do
568
- set_column_allow_null :artist_id
569
- end
570
-
571
- === +set_column_not_null+
572
-
573
- This allows you to set the column as not allowing NULL values:
574
-
575
- alter_table(:albums) do
576
- set_column_not_null :artist_id
577
- end
578
-
579
- == Other +Database+ schema modification methods
580
-
581
- <tt>Sequel::Database</tt> has many schema modification instance methods,
582
- most of which are shortcuts to the same methods in +alter_table+. The
583
- following +Database+ instance methods just call +alter_table+ with a
584
- block that calls the method with the same name inside the +alter_table+
585
- block with all arguments after the first argument (which is used as
586
- the table name):
587
-
588
- * +add_column+
589
- * +drop_column+
590
- * +rename_column+
591
- * +add_index+
592
- * +drop_index+
593
- * +set_column_default+
594
- * +set_column_type+
595
-
596
- For example, the following two method calls do the same thing:
597
-
598
- alter_table(:artists){add_column :copies_sold, Integer}
599
- add_column :artists, :copies_sold, Integer
600
-
601
- There are some other schema modification methods that have no +alter_table+
602
- counterpart:
603
-
604
- === +drop_table+
605
-
606
- +drop_table+ takes multiple arguments and treats all arguments as a
607
- table name to drop:
608
-
609
- drop_table(:albums_artists, :albums, :artists)
610
-
611
- Note that when dropping tables, you may need to drop them in a specific order
612
- if you are using foreign keys and the database is enforcing referential
613
- integrity. In general, you need to drop the tables containing the foreign
614
- keys before the tables containing the primary keys they reference.
615
-
616
- === <tt>drop_table?</tt>
617
-
618
- <tt>drop_table?</tt> is similar to drop_table, except that it only drops
619
- the table if the table already exists. On some databases, it uses
620
- <tt>IF NOT EXISTS</tt>, on others it does a separate query to check for
621
- existence.
622
-
623
- === +rename_table+
624
-
625
- You can rename an existing table using +rename_table+. Like +rename_column+,
626
- the first argument is the current name, and the second is the new name:
627
-
628
- rename_table(:artist, :artists)
629
-
630
- === <tt>create_table!</tt>
631
-
632
- <tt>create_table!</tt> drops the table if it exists
633
- before attempting to create it, so:
634
-
635
- create_table!(:artists) do
636
- primary_key :id
637
- end
638
-
639
- is the same as:
640
-
641
- drop_table?(:artists)
642
- create_table(:artists) do
643
- primary_key :id
644
- end
645
-
646
- === <tt>create_table?</tt>
647
-
648
- <tt>create_table?</tt> only creates the table if it does
649
- not already exist, so:
650
-
651
- create_table?(:artists) do
652
- primary_key :id
653
- end
654
-
655
- is the same as:
656
-
657
- unless table_exists?(:artists)
658
- create_table(:artists) do
659
- primary_key :id
660
- end
661
- end
662
-
663
- === +create_view+ and +create_or_replace_view+
664
-
665
- These can be used to create views. The difference between them is that
666
- +create_or_replace_view+ will unconditionally replace an existing view of
667
- the same name, while +create_view+ will probably raise an error. Both methods
668
- take the name as the first argument, and either an string or a dataset as the
669
- second argument:
670
-
671
- create_view(:gold_albums, DB[:albums].where{copies_sold > 500000})
672
- create_or_replace_view(:gold_albums, "SELECT * FROM albums WHERE copies_sold > 500000")
673
-
674
- === +drop_view+
675
-
676
- +drop_view+ drops existing views. Just like +drop_table+, it can accept multiple
677
- arguments:
678
-
679
- drop_view(:gold_albums, :platinum_albums)