sequel 5.80.0 → 5.92.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. checksums.yaml +4 -4
  2. data/bin/sequel +9 -4
  3. data/lib/sequel/adapters/ado.rb +1 -1
  4. data/lib/sequel/adapters/ibmdb.rb +1 -0
  5. data/lib/sequel/adapters/jdbc/db2.rb +2 -2
  6. data/lib/sequel/adapters/jdbc/derby.rb +3 -3
  7. data/lib/sequel/adapters/jdbc/h2.rb +2 -2
  8. data/lib/sequel/adapters/jdbc/hsqldb.rb +2 -2
  9. data/lib/sequel/adapters/jdbc/jtds.rb +2 -2
  10. data/lib/sequel/adapters/jdbc/mysql.rb +1 -1
  11. data/lib/sequel/adapters/jdbc/oracle.rb +5 -5
  12. data/lib/sequel/adapters/jdbc/postgresql.rb +5 -5
  13. data/lib/sequel/adapters/jdbc/sqlanywhere.rb +6 -6
  14. data/lib/sequel/adapters/jdbc/sqlite.rb +2 -2
  15. data/lib/sequel/adapters/jdbc/sqlserver.rb +2 -2
  16. data/lib/sequel/adapters/jdbc.rb +8 -8
  17. data/lib/sequel/adapters/mysql2.rb +8 -1
  18. data/lib/sequel/adapters/shared/access.rb +1 -0
  19. data/lib/sequel/adapters/shared/db2.rb +1 -1
  20. data/lib/sequel/adapters/shared/mssql.rb +18 -5
  21. data/lib/sequel/adapters/shared/mysql.rb +8 -4
  22. data/lib/sequel/adapters/shared/oracle.rb +1 -0
  23. data/lib/sequel/adapters/shared/postgres.rb +106 -13
  24. data/lib/sequel/adapters/shared/sqlite.rb +4 -2
  25. data/lib/sequel/adapters/sqlite.rb +4 -0
  26. data/lib/sequel/adapters/trilogy.rb +1 -2
  27. data/lib/sequel/connection_pool/sharded_threaded.rb +26 -10
  28. data/lib/sequel/connection_pool/threaded.rb +26 -10
  29. data/lib/sequel/connection_pool.rb +2 -2
  30. data/lib/sequel/core.rb +15 -0
  31. data/lib/sequel/database/connecting.rb +20 -26
  32. data/lib/sequel/database/dataset_defaults.rb +3 -3
  33. data/lib/sequel/database/misc.rb +46 -10
  34. data/lib/sequel/database/query.rb +11 -11
  35. data/lib/sequel/database/schema_generator.rb +8 -0
  36. data/lib/sequel/database/schema_methods.rb +17 -1
  37. data/lib/sequel/dataset/actions.rb +9 -1
  38. data/lib/sequel/dataset/deprecated_singleton_class_methods.rb +1 -1
  39. data/lib/sequel/dataset/prepared_statements.rb +2 -1
  40. data/lib/sequel/dataset/query.rb +9 -5
  41. data/lib/sequel/dataset/sql.rb +25 -5
  42. data/lib/sequel/extensions/caller_logging.rb +2 -0
  43. data/lib/sequel/extensions/connection_validator.rb +15 -10
  44. data/lib/sequel/extensions/dataset_run.rb +41 -0
  45. data/lib/sequel/extensions/migration.rb +23 -3
  46. data/lib/sequel/extensions/null_dataset.rb +2 -2
  47. data/lib/sequel/extensions/pg_auto_parameterize.rb +1 -1
  48. data/lib/sequel/extensions/pg_auto_parameterize_in_array.rb +93 -10
  49. data/lib/sequel/extensions/pg_enum.rb +3 -3
  50. data/lib/sequel/extensions/pg_json_ops.rb +642 -9
  51. data/lib/sequel/extensions/pg_row.rb +3 -1
  52. data/lib/sequel/extensions/pg_schema_caching.rb +90 -0
  53. data/lib/sequel/extensions/provenance.rb +2 -0
  54. data/lib/sequel/extensions/query_blocker.rb +172 -0
  55. data/lib/sequel/extensions/schema_caching.rb +24 -9
  56. data/lib/sequel/extensions/schema_dumper.rb +16 -4
  57. data/lib/sequel/extensions/sqlite_json_ops.rb +1 -1
  58. data/lib/sequel/extensions/stdio_logger.rb +48 -0
  59. data/lib/sequel/extensions/string_agg.rb +17 -4
  60. data/lib/sequel/extensions/temporarily_release_connection.rb +178 -0
  61. data/lib/sequel/extensions/virtual_row_method_block.rb +1 -0
  62. data/lib/sequel/model/associations.rb +28 -3
  63. data/lib/sequel/model/base.rb +67 -18
  64. data/lib/sequel/plugins/association_pks.rb +1 -1
  65. data/lib/sequel/plugins/column_encryption.rb +1 -1
  66. data/lib/sequel/plugins/composition.rb +1 -1
  67. data/lib/sequel/plugins/defaults_setter.rb +16 -4
  68. data/lib/sequel/plugins/enum.rb +1 -1
  69. data/lib/sequel/plugins/forbid_lazy_load.rb +14 -1
  70. data/lib/sequel/plugins/input_transformer.rb +1 -1
  71. data/lib/sequel/plugins/inspect_pk.rb +44 -0
  72. data/lib/sequel/plugins/instance_filters.rb +4 -1
  73. data/lib/sequel/plugins/inverted_subsets.rb +1 -0
  74. data/lib/sequel/plugins/lazy_attributes.rb +1 -1
  75. data/lib/sequel/plugins/nested_attributes.rb +10 -5
  76. data/lib/sequel/plugins/optimistic_locking.rb +2 -0
  77. data/lib/sequel/plugins/paged_operations.rb +5 -2
  78. data/lib/sequel/plugins/pg_auto_constraint_validations.rb +6 -1
  79. data/lib/sequel/plugins/pg_auto_validate_enums.rb +88 -0
  80. data/lib/sequel/plugins/pg_eager_any_typed_array.rb +95 -0
  81. data/lib/sequel/plugins/rcte_tree.rb +1 -1
  82. data/lib/sequel/plugins/serialization.rb +11 -5
  83. data/lib/sequel/plugins/sql_comments.rb +7 -2
  84. data/lib/sequel/plugins/static_cache_cache.rb +50 -13
  85. data/lib/sequel/plugins/subset_conditions.rb +85 -5
  86. data/lib/sequel/plugins/subset_static_cache.rb +263 -0
  87. data/lib/sequel/plugins/tactical_eager_loading.rb +6 -2
  88. data/lib/sequel/plugins/validate_associated.rb +1 -1
  89. data/lib/sequel/sql.rb +16 -6
  90. data/lib/sequel/version.rb +1 -1
  91. metadata +12 -234
  92. data/CHANGELOG +0 -1355
  93. data/README.rdoc +0 -936
  94. data/doc/advanced_associations.rdoc +0 -884
  95. data/doc/association_basics.rdoc +0 -1859
  96. data/doc/bin_sequel.rdoc +0 -146
  97. data/doc/cheat_sheet.rdoc +0 -255
  98. data/doc/code_order.rdoc +0 -102
  99. data/doc/core_extensions.rdoc +0 -405
  100. data/doc/dataset_basics.rdoc +0 -96
  101. data/doc/dataset_filtering.rdoc +0 -222
  102. data/doc/extensions.rdoc +0 -77
  103. data/doc/fork_safety.rdoc +0 -84
  104. data/doc/mass_assignment.rdoc +0 -98
  105. data/doc/migration.rdoc +0 -660
  106. data/doc/model_dataset_method_design.rdoc +0 -129
  107. data/doc/model_hooks.rdoc +0 -254
  108. data/doc/model_plugins.rdoc +0 -270
  109. data/doc/mssql_stored_procedures.rdoc +0 -43
  110. data/doc/object_model.rdoc +0 -563
  111. data/doc/opening_databases.rdoc +0 -436
  112. data/doc/postgresql.rdoc +0 -611
  113. data/doc/prepared_statements.rdoc +0 -144
  114. data/doc/querying.rdoc +0 -1070
  115. data/doc/reflection.rdoc +0 -120
  116. data/doc/release_notes/5.0.0.txt +0 -159
  117. data/doc/release_notes/5.1.0.txt +0 -31
  118. data/doc/release_notes/5.10.0.txt +0 -84
  119. data/doc/release_notes/5.11.0.txt +0 -83
  120. data/doc/release_notes/5.12.0.txt +0 -141
  121. data/doc/release_notes/5.13.0.txt +0 -27
  122. data/doc/release_notes/5.14.0.txt +0 -63
  123. data/doc/release_notes/5.15.0.txt +0 -39
  124. data/doc/release_notes/5.16.0.txt +0 -110
  125. data/doc/release_notes/5.17.0.txt +0 -31
  126. data/doc/release_notes/5.18.0.txt +0 -69
  127. data/doc/release_notes/5.19.0.txt +0 -28
  128. data/doc/release_notes/5.2.0.txt +0 -33
  129. data/doc/release_notes/5.20.0.txt +0 -89
  130. data/doc/release_notes/5.21.0.txt +0 -87
  131. data/doc/release_notes/5.22.0.txt +0 -48
  132. data/doc/release_notes/5.23.0.txt +0 -56
  133. data/doc/release_notes/5.24.0.txt +0 -56
  134. data/doc/release_notes/5.25.0.txt +0 -32
  135. data/doc/release_notes/5.26.0.txt +0 -35
  136. data/doc/release_notes/5.27.0.txt +0 -21
  137. data/doc/release_notes/5.28.0.txt +0 -16
  138. data/doc/release_notes/5.29.0.txt +0 -22
  139. data/doc/release_notes/5.3.0.txt +0 -121
  140. data/doc/release_notes/5.30.0.txt +0 -20
  141. data/doc/release_notes/5.31.0.txt +0 -148
  142. data/doc/release_notes/5.32.0.txt +0 -46
  143. data/doc/release_notes/5.33.0.txt +0 -24
  144. data/doc/release_notes/5.34.0.txt +0 -40
  145. data/doc/release_notes/5.35.0.txt +0 -56
  146. data/doc/release_notes/5.36.0.txt +0 -60
  147. data/doc/release_notes/5.37.0.txt +0 -30
  148. data/doc/release_notes/5.38.0.txt +0 -28
  149. data/doc/release_notes/5.39.0.txt +0 -19
  150. data/doc/release_notes/5.4.0.txt +0 -80
  151. data/doc/release_notes/5.40.0.txt +0 -40
  152. data/doc/release_notes/5.41.0.txt +0 -25
  153. data/doc/release_notes/5.42.0.txt +0 -136
  154. data/doc/release_notes/5.43.0.txt +0 -98
  155. data/doc/release_notes/5.44.0.txt +0 -32
  156. data/doc/release_notes/5.45.0.txt +0 -34
  157. data/doc/release_notes/5.46.0.txt +0 -87
  158. data/doc/release_notes/5.47.0.txt +0 -59
  159. data/doc/release_notes/5.48.0.txt +0 -14
  160. data/doc/release_notes/5.49.0.txt +0 -59
  161. data/doc/release_notes/5.5.0.txt +0 -61
  162. data/doc/release_notes/5.50.0.txt +0 -78
  163. data/doc/release_notes/5.51.0.txt +0 -47
  164. data/doc/release_notes/5.52.0.txt +0 -87
  165. data/doc/release_notes/5.53.0.txt +0 -23
  166. data/doc/release_notes/5.54.0.txt +0 -27
  167. data/doc/release_notes/5.55.0.txt +0 -21
  168. data/doc/release_notes/5.56.0.txt +0 -51
  169. data/doc/release_notes/5.57.0.txt +0 -23
  170. data/doc/release_notes/5.58.0.txt +0 -31
  171. data/doc/release_notes/5.59.0.txt +0 -73
  172. data/doc/release_notes/5.6.0.txt +0 -31
  173. data/doc/release_notes/5.60.0.txt +0 -22
  174. data/doc/release_notes/5.61.0.txt +0 -43
  175. data/doc/release_notes/5.62.0.txt +0 -132
  176. data/doc/release_notes/5.63.0.txt +0 -33
  177. data/doc/release_notes/5.64.0.txt +0 -50
  178. data/doc/release_notes/5.65.0.txt +0 -21
  179. data/doc/release_notes/5.66.0.txt +0 -24
  180. data/doc/release_notes/5.67.0.txt +0 -32
  181. data/doc/release_notes/5.68.0.txt +0 -61
  182. data/doc/release_notes/5.69.0.txt +0 -26
  183. data/doc/release_notes/5.7.0.txt +0 -108
  184. data/doc/release_notes/5.70.0.txt +0 -35
  185. data/doc/release_notes/5.71.0.txt +0 -21
  186. data/doc/release_notes/5.72.0.txt +0 -33
  187. data/doc/release_notes/5.73.0.txt +0 -66
  188. data/doc/release_notes/5.74.0.txt +0 -45
  189. data/doc/release_notes/5.75.0.txt +0 -35
  190. data/doc/release_notes/5.76.0.txt +0 -86
  191. data/doc/release_notes/5.77.0.txt +0 -63
  192. data/doc/release_notes/5.78.0.txt +0 -67
  193. data/doc/release_notes/5.79.0.txt +0 -28
  194. data/doc/release_notes/5.8.0.txt +0 -170
  195. data/doc/release_notes/5.80.0.txt +0 -40
  196. data/doc/release_notes/5.9.0.txt +0 -99
  197. data/doc/schema_modification.rdoc +0 -679
  198. data/doc/security.rdoc +0 -443
  199. data/doc/sharding.rdoc +0 -286
  200. data/doc/sql.rdoc +0 -648
  201. data/doc/testing.rdoc +0 -190
  202. data/doc/thread_safety.rdoc +0 -15
  203. data/doc/transactions.rdoc +0 -250
  204. data/doc/validations.rdoc +0 -558
  205. 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)