sequel 5.83.1 → 5.85.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (127) hide show
  1. checksums.yaml +4 -4
  2. data/lib/sequel/adapters/shared/sqlite.rb +3 -1
  3. data/lib/sequel/connection_pool.rb +2 -2
  4. data/lib/sequel/database/schema_methods.rb +2 -0
  5. data/lib/sequel/dataset/actions.rb +9 -1
  6. data/lib/sequel/extensions/dataset_run.rb +41 -0
  7. data/lib/sequel/extensions/pg_json_ops.rb +642 -9
  8. data/lib/sequel/sql.rb +8 -5
  9. data/lib/sequel/version.rb +2 -2
  10. metadata +4 -237
  11. data/CHANGELOG +0 -1397
  12. data/README.rdoc +0 -936
  13. data/doc/advanced_associations.rdoc +0 -884
  14. data/doc/association_basics.rdoc +0 -1859
  15. data/doc/bin_sequel.rdoc +0 -146
  16. data/doc/cheat_sheet.rdoc +0 -255
  17. data/doc/code_order.rdoc +0 -104
  18. data/doc/core_extensions.rdoc +0 -405
  19. data/doc/dataset_basics.rdoc +0 -96
  20. data/doc/dataset_filtering.rdoc +0 -222
  21. data/doc/extensions.rdoc +0 -77
  22. data/doc/fork_safety.rdoc +0 -84
  23. data/doc/mass_assignment.rdoc +0 -98
  24. data/doc/migration.rdoc +0 -660
  25. data/doc/model_dataset_method_design.rdoc +0 -129
  26. data/doc/model_hooks.rdoc +0 -254
  27. data/doc/model_plugins.rdoc +0 -270
  28. data/doc/mssql_stored_procedures.rdoc +0 -43
  29. data/doc/object_model.rdoc +0 -563
  30. data/doc/opening_databases.rdoc +0 -439
  31. data/doc/postgresql.rdoc +0 -611
  32. data/doc/prepared_statements.rdoc +0 -144
  33. data/doc/querying.rdoc +0 -1070
  34. data/doc/reflection.rdoc +0 -120
  35. data/doc/release_notes/5.0.0.txt +0 -159
  36. data/doc/release_notes/5.1.0.txt +0 -31
  37. data/doc/release_notes/5.10.0.txt +0 -84
  38. data/doc/release_notes/5.11.0.txt +0 -83
  39. data/doc/release_notes/5.12.0.txt +0 -141
  40. data/doc/release_notes/5.13.0.txt +0 -27
  41. data/doc/release_notes/5.14.0.txt +0 -63
  42. data/doc/release_notes/5.15.0.txt +0 -39
  43. data/doc/release_notes/5.16.0.txt +0 -110
  44. data/doc/release_notes/5.17.0.txt +0 -31
  45. data/doc/release_notes/5.18.0.txt +0 -69
  46. data/doc/release_notes/5.19.0.txt +0 -28
  47. data/doc/release_notes/5.2.0.txt +0 -33
  48. data/doc/release_notes/5.20.0.txt +0 -89
  49. data/doc/release_notes/5.21.0.txt +0 -87
  50. data/doc/release_notes/5.22.0.txt +0 -48
  51. data/doc/release_notes/5.23.0.txt +0 -56
  52. data/doc/release_notes/5.24.0.txt +0 -56
  53. data/doc/release_notes/5.25.0.txt +0 -32
  54. data/doc/release_notes/5.26.0.txt +0 -35
  55. data/doc/release_notes/5.27.0.txt +0 -21
  56. data/doc/release_notes/5.28.0.txt +0 -16
  57. data/doc/release_notes/5.29.0.txt +0 -22
  58. data/doc/release_notes/5.3.0.txt +0 -121
  59. data/doc/release_notes/5.30.0.txt +0 -20
  60. data/doc/release_notes/5.31.0.txt +0 -148
  61. data/doc/release_notes/5.32.0.txt +0 -46
  62. data/doc/release_notes/5.33.0.txt +0 -24
  63. data/doc/release_notes/5.34.0.txt +0 -40
  64. data/doc/release_notes/5.35.0.txt +0 -56
  65. data/doc/release_notes/5.36.0.txt +0 -60
  66. data/doc/release_notes/5.37.0.txt +0 -30
  67. data/doc/release_notes/5.38.0.txt +0 -28
  68. data/doc/release_notes/5.39.0.txt +0 -19
  69. data/doc/release_notes/5.4.0.txt +0 -80
  70. data/doc/release_notes/5.40.0.txt +0 -40
  71. data/doc/release_notes/5.41.0.txt +0 -25
  72. data/doc/release_notes/5.42.0.txt +0 -136
  73. data/doc/release_notes/5.43.0.txt +0 -98
  74. data/doc/release_notes/5.44.0.txt +0 -32
  75. data/doc/release_notes/5.45.0.txt +0 -34
  76. data/doc/release_notes/5.46.0.txt +0 -87
  77. data/doc/release_notes/5.47.0.txt +0 -59
  78. data/doc/release_notes/5.48.0.txt +0 -14
  79. data/doc/release_notes/5.49.0.txt +0 -59
  80. data/doc/release_notes/5.5.0.txt +0 -61
  81. data/doc/release_notes/5.50.0.txt +0 -78
  82. data/doc/release_notes/5.51.0.txt +0 -47
  83. data/doc/release_notes/5.52.0.txt +0 -87
  84. data/doc/release_notes/5.53.0.txt +0 -23
  85. data/doc/release_notes/5.54.0.txt +0 -27
  86. data/doc/release_notes/5.55.0.txt +0 -21
  87. data/doc/release_notes/5.56.0.txt +0 -51
  88. data/doc/release_notes/5.57.0.txt +0 -23
  89. data/doc/release_notes/5.58.0.txt +0 -31
  90. data/doc/release_notes/5.59.0.txt +0 -73
  91. data/doc/release_notes/5.6.0.txt +0 -31
  92. data/doc/release_notes/5.60.0.txt +0 -22
  93. data/doc/release_notes/5.61.0.txt +0 -43
  94. data/doc/release_notes/5.62.0.txt +0 -132
  95. data/doc/release_notes/5.63.0.txt +0 -33
  96. data/doc/release_notes/5.64.0.txt +0 -50
  97. data/doc/release_notes/5.65.0.txt +0 -21
  98. data/doc/release_notes/5.66.0.txt +0 -24
  99. data/doc/release_notes/5.67.0.txt +0 -32
  100. data/doc/release_notes/5.68.0.txt +0 -61
  101. data/doc/release_notes/5.69.0.txt +0 -26
  102. data/doc/release_notes/5.7.0.txt +0 -108
  103. data/doc/release_notes/5.70.0.txt +0 -35
  104. data/doc/release_notes/5.71.0.txt +0 -21
  105. data/doc/release_notes/5.72.0.txt +0 -33
  106. data/doc/release_notes/5.73.0.txt +0 -66
  107. data/doc/release_notes/5.74.0.txt +0 -45
  108. data/doc/release_notes/5.75.0.txt +0 -35
  109. data/doc/release_notes/5.76.0.txt +0 -86
  110. data/doc/release_notes/5.77.0.txt +0 -63
  111. data/doc/release_notes/5.78.0.txt +0 -67
  112. data/doc/release_notes/5.79.0.txt +0 -28
  113. data/doc/release_notes/5.8.0.txt +0 -170
  114. data/doc/release_notes/5.80.0.txt +0 -40
  115. data/doc/release_notes/5.81.0.txt +0 -31
  116. data/doc/release_notes/5.82.0.txt +0 -61
  117. data/doc/release_notes/5.83.0.txt +0 -56
  118. data/doc/release_notes/5.9.0.txt +0 -99
  119. data/doc/schema_modification.rdoc +0 -679
  120. data/doc/security.rdoc +0 -443
  121. data/doc/sharding.rdoc +0 -286
  122. data/doc/sql.rdoc +0 -648
  123. data/doc/testing.rdoc +0 -204
  124. data/doc/thread_safety.rdoc +0 -15
  125. data/doc/transactions.rdoc +0 -250
  126. data/doc/validations.rdoc +0 -558
  127. data/doc/virtual_rows.rdoc +0 -265
data/doc/validations.rdoc DELETED
@@ -1,558 +0,0 @@
1
- = Model Validations
2
-
3
- This guide is based on http://guides.rubyonrails.org/active_record_validations.html
4
-
5
- == Overview
6
-
7
- This guide is designed to teach you how to use Sequel::Model's validation support. It attempts
8
- to explain how Sequel's validation support works, what validations are
9
- useful for, and how to use the +validation_helpers+ plugin to add specific
10
- types of validations to your models.
11
-
12
- == Why Validations?
13
-
14
- Validations are primarily useful for associating error messages to display to the user
15
- with specific attributes on the model. It is also possible to use them to enforce
16
- data integrity for model instances, but that's not recommended unless
17
- the only way to modify the database is through model instances, or you have
18
- complex data integrity requirements that aren't possible to specify via
19
- database-level constraints.
20
-
21
- == Data Integrity
22
-
23
- Data integrity is best handled by the database itself. For example, if you have
24
- a date column that should never contain a NULL value, the column should be
25
- specified in the database as NOT NULL. If you have an integer column that should
26
- only have values from 1 to 10, there should be a CHECK constraint that ensures
27
- that the value of that column is between 1 and 10. And if you have a varchar
28
- column where the length of the entries should be between 2 and 255, you should
29
- be setting the size of the varchar column to 255, and using a CHECK constraint
30
- to ensure that all values have at least two characters.
31
-
32
- Unfortunately, sometimes there are situations where that is not possible. For
33
- example, if you don't have control over the schema and cannot add constraints,
34
- or you are using MySQL (which doesn't support CHECK constraints), it may be necessary to use a model validation
35
- to enforce the database integrity.
36
-
37
- In some cases you may have data integrity requirements that are difficult to
38
- enforce via database constraints, especially if you are targetting multiple
39
- database types.
40
-
41
- Validations are generally easier to write than database constraints,
42
- so if data integrity isn't of great importance, using validations to provide minimal
43
- data integrity may be acceptable.
44
-
45
- == Usage
46
-
47
- Regardless of whether you are using validations for data integrity or just for
48
- error messages, the usage is the same. Whenever you attempt to save a model
49
- instance, before sending the INSERT or UPDATE query to the database,
50
- <tt>Sequel::Model</tt> will attempt to validate the instance by calling
51
- +validate+. If +validate+ does not add any errors to the object, the object is
52
- considered valid, and <tt>valid?</tt> will return true. If +validate+ adds any errors
53
- to the object, <tt>valid?</tt> will return false, and the save will either raise
54
- a <tt>Sequel::ValidationFailed</tt> exception (the default), or return nil (if +raise_on_save_failure+
55
- is false).
56
-
57
- By validating the object before sending the database query, Sequel attempts to
58
- ensure that invalid objects are not saved in the database. However, if you
59
- are not enforcing the same validations in the database via constraints, it's
60
- possible that invalid data can get added to the database via some other method.
61
- This leads to odd cases such as retrieving a model object from the database,
62
- not making any changes to it, attempting to save it, and having the save
63
- raise an error.
64
-
65
- == Skipping Validations
66
-
67
- <tt>Sequel::Model</tt> uses the +save+ method to save model objects, and all
68
- saving of model objects passes through the +save+ method. This means that all
69
- saving of model objects goes through the validation process.
70
-
71
- The only way to skip validations when saving a model object is to pass the
72
- <tt>validate: false</tt> option to +save+. If you use that option, +save+ will
73
- not attempt to validate the object before saving it.
74
-
75
- Note that it's always possible to update the instance's database row without using
76
- +save+, by using a Sequel dataset to update it, or updating it via another program.
77
- Validations will only be run if you call
78
- +save+ on the model object, or another model method that calls +save+. For example,
79
- the +create+ class method instantiates a new instance of the model, and then calls
80
- +save+, so it validates the object. However, the +insert+ class method is a dataset
81
- method that just inserts the raw hash into the database, so it doesn't validate the
82
- object.
83
-
84
- == <tt>valid?</tt> and +validate+
85
-
86
- <tt>Sequel::Model</tt> uses the <tt>valid?</tt> method to check whether or not a
87
- model instance is valid. This method should not be overridden. Instead, the
88
- +validate+ method should be overridden to add validations to the model:
89
-
90
- class Album < Sequel::Model
91
- def validate
92
- super
93
- errors.add(:name, 'cannot be empty') if !name || name.empty?
94
- end
95
- end
96
-
97
- Album.new.valid? # false
98
- Album.new(name: '').valid? # false
99
- Album.new(name: 'RF').valid? # true
100
-
101
- If the <tt>valid?</tt> method returns false, you can call the +errors+ method to
102
- get an instance of <tt>Sequel::Model::Errors</tt> describing the errors on the model:
103
-
104
- a = Album.new
105
- # => #<Album @values={}>
106
- a.valid?
107
- # => false
108
- a.errors
109
- # => {:name=>["cannot be empty"]}
110
-
111
- You may notice that the +errors+ method appears to return a hash. That's because
112
- <tt>Sequel::Model::Errors</tt> is a subclass of Hash.
113
-
114
- Note that calling the +errors+ method before the <tt>valid?</tt> method will result
115
- in an +errors+ being empty:
116
-
117
- Album.new.errors
118
- # => {}
119
-
120
- So just remember that you shouldn't check +errors+ until after you call <tt>valid?</tt>.
121
-
122
- <tt>Sequel::Model::Errors</tt> has some helper methods that make it easy to get an array of
123
- all of the instance's errors, or for checking for errors on a specific attribute. These
124
- will be covered later in this guide.
125
-
126
- == +validation_helpers+
127
-
128
- While <tt>Sequel::Model</tt> does provide a validations framework, it does not define
129
- any built-in validation helper methods that you can call. However, Sequel ships with a
130
- plugin called +validation_helpers+ that handles most basic validation needs. So instead of
131
- specifying validations like this:
132
-
133
- class Album < Sequel::Model
134
- def validate
135
- super
136
- errors.add(:name, 'cannot be empty') if !name || name.empty?
137
- errors.add(:name, 'is already taken') if name && new? && Album[{name: name}]
138
- errors.add(:website, 'cannot be empty') if !website || website.empty?
139
- errors.add(:website, 'is not a valid URL') unless website =~ /\Ahttps?:\/\//
140
- end
141
- end
142
-
143
- You can call simple methods such as:
144
-
145
- class Album < Sequel::Model
146
- plugin :validation_helpers
147
- def validate
148
- super
149
- validates_presence [:name, :website]
150
- validates_unique :name
151
- validates_format /\Ahttps?:\/\//, :website, message: 'is not a valid URL'
152
- end
153
- end
154
-
155
- Other than +validates_unique+, which has its own API, the methods defined by
156
- +validation_helpers+ have one of the following two APIs:
157
-
158
- <tt>(atts, opts={})</tt>:: For methods such as +validates_presence+, which do not
159
- take an additional argument.
160
- <tt>(arg, atts, opts={})</tt>:: For methods such as +validates_format+, which take an
161
- additional argument.
162
-
163
- For both of these APIs, +atts+ is either a column symbol or array of column symbols,
164
- and +opts+ is an optional options hash.
165
-
166
- The following methods are provided by +validation_helpers+:
167
-
168
- === +validates_presence+
169
-
170
- This method checks that the specified attributes are not blank. In general, if an object responds to <tt>blank?</tt>, it calls the method to determine if the object is blank. Otherwise, nil is considered blank, empty strings or strings that just contain whitespace are blank, and objects that respond to <tt>empty?</tt> and return true are considered blank. All other objects are considered non-blank for the purposes of +validates_presence+. This means that +validates_presence+ is safe to use on boolean columns where you want to ensure that either true or false is used, but not NULL.
171
-
172
- class Album < Sequel::Model
173
- def validate
174
- super
175
- validates_presence [:name, :website, :debut_album]
176
- end
177
- end
178
-
179
- === +validates_not_null+
180
-
181
- This is similar to +validates_presence+, but only checks for NULL/nil values, allowing other blank objects such as empty strings or strings with just whitespace.
182
-
183
- === +validates_format+
184
-
185
- +validates_format+ is used to ensure that the string value of the specified attributes matches the specified regular expression. It's useful for checking that fields such as email addresses, URLs, UPC codes, ISBN codes, and the like, are in a specific format. It can also be used to validate that only certain characters are used in the string.
186
-
187
- class Album < Sequel::Model
188
- def validate
189
- super
190
- validates_format /\A\d\d\d-\d-\d{7}-\d-\d\z/, :isbn
191
- validates_format /\A[0-9a-zA-Z:' ]+\z/, :name
192
- end
193
- end
194
-
195
- === +validates_exact_length+, +validates_min_length+, +validates_max_length+, +validates_length_range+
196
-
197
- These methods all deal with ensuring that the length of the specified attribute matches the criteria specified by the first argument to the method. +validates_exact_length+ is for checking that the length of the attribute is equal to that value, +validates_min_length+ is for checking that the length of the attribute is greater than or equal to that value, +validates_max_length+ is for checking that the length of the attribute is less than or equal to that value, and +validates_length_range+ is for checking that the length of the attribute falls in the value, which should be a range or an object that responds to <tt>include?</tt>.
198
-
199
-
200
- class Album < Sequel::Model
201
- def validate
202
- super
203
- validates_exact_length 17, :isbn
204
- validates_min_length 3, :name
205
- validates_max_length 100, :name
206
- validates_length_range 3..100, :name
207
- end
208
- end
209
-
210
- === +validates_integer+, +validates_numeric+
211
-
212
- These methods check that the specified attributes can be valid integers or valid floats. +validates_integer+ tests the attribute value using <tt>Kernel.Integer</tt> and +validates_numeric+ tests the attribute using <tt>Kernel.Float</tt>. If the Kernel methods raise an exception, the validation fails, otherwise it succeeds.
213
-
214
- class Album < Sequel::Model
215
- def validate
216
- super
217
- validates_integer :copies_sold
218
- validates_numeric :replaygain
219
- end
220
- end
221
-
222
- === +validates_includes+
223
-
224
- +validates_includes+ checks that the specified attributes are included in the first argument to the method, which is usually an array, but can be any object that responds to <tt>include?</tt>.
225
-
226
- class Album < Sequel::Model
227
- def validate
228
- super
229
- validates_includes [1, 2, 3, 4, 5], :rating
230
- end
231
- end
232
-
233
- === +validates_operator+
234
-
235
- +validates_operator+ checks that a given +operator+ method returns a truthy value when called on attribute with a specified value for comparison. Generally, this is used for inequality checks (>, >=, etc.) but any method that can be called on the attribute that accepts an argument and returns a truthy value may be used.
236
-
237
- class Album < Sequel::Model
238
- def validate
239
- super
240
- validates_operator(:>, 3, :tracks)
241
- end
242
- end
243
-
244
- === +validates_type+
245
-
246
- +validates_type+ checks that the specified attributes are instances of the class specified in the first argument. The class can be specified as the class itself, or as a string or symbol with the class name, or as a an array of classes.
247
-
248
- class Album < Sequel::Model
249
- def validate
250
- super
251
- validates_type String, [:name, :website]
252
- validates_type :Artist, :artist
253
- validates_type [String, Integer], :foo
254
- end
255
- end
256
-
257
- === +validates_schema_types+
258
-
259
- +validates_schema_types+ uses the database metadata for the model's table to determine which ruby type(s) should be used for the given database type, and calls +validates_type+ with that ruby type. It's designed to be used with the default <tt>raise_on_typecast_failure = false</tt> setting, where Sequel will attempt to typecast values, but silently ignore any errors raised:
260
-
261
- album = Album.new
262
- album.copies_sold = '1'
263
- album.copies_sold # => 1
264
- album.copies_sold = 'banana'
265
- album.copies_sold # => 'banana'
266
-
267
- In general, you can call +validates_schema_types+ with all columns. If any of those columns has a value that doesn't match the type that Sequel expects, it's probably because the column was set and Sequel was not able to typecast it correctly, which means it probably isn't valid. For example, let's say that you want to check that a couple of columns contain valid dates:
268
-
269
- class Album < Sequel::Model
270
- def validate
271
- super
272
- validates_schema_types [:release_date, :record_date]
273
- end
274
- end
275
-
276
- album = Album.new
277
- album.release_date = 'banana'
278
- album.release_date # => 'banana'
279
- album.record_date = '2010-05-17'
280
- album.record_date # => #<Date: 4910667/2,0,2299161>
281
- album.valid? # => false
282
- album.errors # => {:release_date=>["is not a valid date"]}
283
-
284
- For web applications, you usually want the default setting, so that you can accept all of the input without raising an error, and then present the user with all error messages. If <tt>raise_on_typecast_failure = true</tt> is set and the user submits any invalid data, Sequel will immediately raise an error. +validates_schema_types+ is helpful because it allows you to check for typecasting errors on columns, and provides a good default error message stating that the attribute is not of the expected type.
285
-
286
- === +validates_unique+
287
-
288
- +validates_unique+ has a similar but different API than the other +validation_helpers+ methods. It takes an arbitrary number of arguments, which should be column symbols or arrays of column symbols. If any argument is a symbol, Sequel sets up a unique validation for just that column. If any argument is an array of symbols, Sequel sets up a unique validation for the combination of the columns. This means that you get different behavior depending on whether you call the object with an array or with separate arguments. For example:
289
-
290
- validates_unique(:name, :artist_id)
291
-
292
- Will set up a 2 separate uniqueness validations. It will make it so that no two albums can have the same name, and that each artist can only be associated with one album. In general, that's probably not what you want. You probably want it so that two albums can have the same name, unless they are by the same artist. To do that, you need to use an array:
293
-
294
- validates_unique([:name, :artist_id])
295
-
296
- That sets up a single uniqueness validation for the combination of the fields.
297
-
298
- You can mix and match the two approaches. For example, if all albums should have a unique UPC, and no artist can have duplicate album names:
299
-
300
- validates_unique(:upc, [:name, :artist_id])
301
-
302
- +validates_unique+ also accepts a block to scope the uniqueness constraint. For example, if you want to ensure that all active albums have a unique name, but inactive albums can duplicate the name:
303
-
304
- validates_unique(:name){|ds| ds.where(:active)}
305
-
306
- If you provide a block, it is called with the dataset to use for the uniqueness check, which you can then filter to scope the uniqueness validation to a subset of the model's dataset.
307
-
308
- You can also include an options hash as the last argument. Unlike the other validations, the options hash for +validates_unique+ only recognizes for these options:
309
-
310
- :dataset :: The base dataset to use for the unique query, defaults to the model's dataset
311
- :message :: The message to use
312
- :only_if_modified :: Only check the uniqueness if the object is new or one of the columns has been modified (true by default).
313
- :where :: A callable object where call takes three arguments, a dataset,
314
- the current object, and an array of columns, and should return
315
- a modified dataset that is filtered to include only rows with
316
- the same values as the current object for each column in the array.
317
- This is useful any time the unique constraints are derived from
318
- the columns and not the columns themselves (such as unique constraints
319
- on lower(column)).
320
-
321
- +validates_unique+ is the only method in +validation_helpers+ that checks with the database. Attempting to validate uniqueness outside of the database suffers from a race condition, so any time you want to add a uniqueness validation, you should make sure to add a uniqueness constraint or unique index on the underlying database table. See the {"Migrations and Schema Modification" guide}[rdoc-ref:doc/migration.rdoc] for details on how to do that.
322
-
323
- == +validation_helpers+ Options
324
-
325
- All other +validation_helpers+ methods accept the following options:
326
-
327
- === <tt>:message</tt>
328
-
329
- The <tt>:message</tt> option overrides the default validation error message. Can be either a string or a proc. If a string, it is used directly. If a proc, the proc is called and should return a string. If the validation method takes an argument before the array of attributes, that argument is passed as an argument to the proc.
330
-
331
- class Album < Sequel::Model
332
- def validate
333
- super
334
- validates_presence :copies_sold, message: 'was not given'
335
- validates_min_length 3, :name, message: lambda{|s| "should be more than #{s} characters"}
336
- end
337
- end
338
-
339
- === <tt>:allow_nil</tt>
340
-
341
- The <tt>:allow_nil</tt> option skips the validation if the attribute value is nil or if the attribute is not present. It's commonly used when you have a +validates_presence+ method already on the attribute, and don't want multiple validation errors for the same attribute:
342
-
343
- class Album < Sequel::Model
344
- def validate
345
- super
346
- validates_presence :copies_sold
347
- validates_integer :copies_sold, allow_nil: true
348
- end
349
- end
350
-
351
- Without the <tt>:allow_nil</tt> option to +validates_integer+, if the copies_sold attribute was nil, you would get two separate validation errors, instead of a single validation error.
352
-
353
- === <tt>:allow_blank</tt>
354
-
355
- The <tt>:allow_blank</tt> is similar to the <tt>:allow_nil</tt> option, but instead of just skipping the attribute for nil values, it skips the attribute for all blank values. For example, let's say that artists can have a website. If they have one, it should be formatted like a URL, but it can be nil or an empty string if they don't have one.
356
-
357
- class Album < Sequel::Model
358
- def validate
359
- super
360
- validates_format /\Ahttps?:\/\//, :website, allow_blank: true
361
- end
362
- end
363
- a = Album.new
364
- a.website = ''
365
- a.valid? # true
366
-
367
- === <tt>:allow_missing</tt>
368
-
369
- The <tt>:allow_missing</tt> option is different from the <tt>:allow_nil</tt> option, in that instead of checking if the attribute value is nil, it checks if the attribute is present in the model instance's values hash. <tt>:allow_nil</tt> will skip the validation when the attribute is in the values hash and has a nil value and when the attribute is not in the values hash. <tt>:allow_missing</tt> will only skip the validation when the attribute is not in the values hash. If the attribute is in the values hash but has a nil value, <tt>:allow_missing</tt> will not skip it.
370
-
371
- The purpose of this option is to work correctly with missing columns when inserting or updating records. Sequel only sends the attributes in the values hash when doing an insert or update. If the attribute is not present in the values hash, Sequel doesn't specify it, so the database will use the table's default value when inserting the record, or not modify the value when saving it. This is different from having an attribute in the values hash with a value of nil, which Sequel will send as NULL. If your database table has a non NULL default, this may be a good option to use. You don't want to use allow_nil, because if the attribute is in values but has a value nil, Sequel will attempt to insert a NULL value into the database, instead of using the database's default.
372
-
373
- == Conditional Validation
374
-
375
- Because Sequel uses the +validate+ instance method to handle validation, making validations conditional is easy as it works exactly the same as ruby's standard conditionals. For example, if you only want to validate an attribute when creating an object:
376
-
377
- validates_presence :name if new?
378
-
379
- If you only want to validate the attribute when updating an existing object:
380
-
381
- validates_integer :copies_sold unless new?
382
-
383
- Let's say you only to make a validation conditional on the status of the object:
384
-
385
- validates_presence :name if status_id > 1
386
- validates_integer :copies_sold if status_id > 3
387
-
388
- You can use all the standard ruby conditional expressions, such as +case+:
389
-
390
- case status_id
391
- when 1
392
- validates_presence :name
393
- when 2
394
- validates_presence [:name, :artist_id]
395
- when 3
396
- validates_presence [:name, :artist_id, :copies_sold]
397
- end
398
-
399
- You can make the input to some validations dependent on the values of another attribute:
400
-
401
- validates_min_length(status_id > 2 ? 5 : 10, [:name])
402
- validates_presence(status_id < 2 ? :name : [:name, :artist_id])
403
-
404
- Basically, there's no special syntax you have to use for conditional validations. Just handle conditionals the way you would in other ruby code.
405
-
406
- == Default Error Messages
407
-
408
- These are the default error messages for all of the helper methods in +validation_helpers+:
409
-
410
- :exact_length :: is not #{arg} characters
411
- :format :: is invalid
412
- :includes :: is not in range or set: #{arg.inspect}
413
- :integer :: is not a number
414
- :length_range :: is too short or too long
415
- :max_length :: is longer than #{arg} characters
416
- :min_length :: is shorter than #{arg} characters
417
- :not_null :: is not present
418
- :numeric :: is not a number
419
- :schema_types :: is not a valid #{schema_type}
420
- :type :: is not a #{arg}
421
- :presence :: is not present
422
- :unique :: is already taken
423
-
424
- == Modifying the Default Options
425
-
426
- You can override <tt>Sequel::Model#default_validation_helpers_options</tt> private method to override the default settings on a per validation type basis:
427
-
428
- class Sequel::Model
429
- private
430
-
431
- def default_validation_helpers_options(type)
432
- case type
433
- when :presence
434
- {message: 'cannot be empty'}
435
- when :includes
436
- {message: 'invalid option', allow_nil: true}
437
- when :max_length
438
- {message: lambda{|i| "cannot be more than #{i} characters"}, allow_nil: true}
439
- when :format
440
- {message: 'contains invalid characters', allow_nil: true}
441
- else
442
- super
443
- end
444
- end
445
- end
446
-
447
- == Custom Validations
448
-
449
- Just as the first validation example showed, you aren't limited to the validation methods defined by +validation_helpers+. Inside the +validate+ method, you can add your own validations by adding to the instance's errors using <tt>errors.add</tt> whenever an attribute is not valid:
450
-
451
- class Album < Sequel::Model
452
- def validate
453
- super
454
- errors.add(:release_date, 'cannot be before record date') if release_date < record_date
455
- end
456
- end
457
-
458
- Just like conditional validations, with custom validations you are just using the standard ruby conditionals, and calling <tt>errors.add</tt> with the column symbol and the error message if you detect invalid data.
459
-
460
- It's fairly easy to create your own custom validations that can be reused in all your models. For example, if there is a common need to validate that one column in the model comes before another column:
461
-
462
- class Sequel::Model
463
- def validates_after(col1, col2)
464
- errors.add(col1, "cannot be before #{col2}") if send(col1) < send(col2)
465
- end
466
- end
467
- class Album < Sequel::Model
468
- def validate
469
- super
470
- validates_after(:release_date, :record_date)
471
- end
472
- end
473
-
474
- == Setting Validations for All Models
475
-
476
- Let's say you want to add some default validations that apply to all of your model classes. It's fairly easy to do by overriding the +validate+ method in <tt>Sequel::Model</tt>, adding some validations to it, and if you override +validate+ in your model classes, just make sure to call +super+.
477
-
478
- class Sequel::Model
479
- def self.string_columns
480
- @string_columns ||= columns.reject{|c| db_schema[c][:type] != :string}
481
- end
482
-
483
- def validate
484
- super
485
- validates_format(/\A[^\x00-\x08\x0e-\x1f\x7f\x81\x8d\x8f\x90\x9d]*\z/n,
486
- model.string_columns,
487
- message: "contains invalid characters")
488
- end
489
- end
490
-
491
- This will make sure that all string columns in the model are validated to make sure they don't contain any invalid characters. Just remember that if you override the +validate+ method in your model classes, you need to call +super+:
492
-
493
- class Album < Sequel::Model
494
- def validate
495
- super # Important!
496
- validates_presence :name
497
- end
498
- end
499
-
500
- If you forget to call +super+, the validations that you defined in <tt>Sequel::Model</tt> will not be enforced. It's a good idea to call super whenever you override one of <tt>Sequel::Model</tt>'s methods, unless you specifically do not want the default behavior.
501
-
502
- == <tt>Sequel::Model::Errors</tt>
503
- As mentioned earlier, <tt>Sequel::Model::Errors</tt> is a subclass of Hash with a few special methods, the most common of which are described here:
504
-
505
- === +add+
506
-
507
- +add+ is the method used to add error messages for a given column. It takes the column symbol as the first argument and the error message as the second argument:
508
-
509
- errors.add(:name, 'is not valid')
510
-
511
- === +on+
512
-
513
- +on+ is a method usually used after validation has been completed, to determine if there were any errors on a given attribute. It takes the column value, and returns an array of error messages if there were any, or nil if not:
514
-
515
- errors.on(:name)
516
-
517
- If you want to make some validations dependent upon the results of other validations, you may want to use +on+ inside your validates method:
518
-
519
- validates_integer(:release_date) unless errors.on(:record_date)
520
-
521
- Here, you don't care about validating the release date if there were validation errors for the record date.
522
-
523
- === +full_messages+
524
-
525
- +full_messages+ returns an array of error messages for the object. It's commonly called after validation to get a list of error messages to display to the user:
526
-
527
- album.errors
528
- # => {:name=>["cannot be empty"]}
529
- album.errors.full_messages
530
- # => ["name cannot be empty"]
531
-
532
- Note that the column names used in the errors are used verbatim in the error messages. If you want full control over the error messages, you can use +add+ with a literal string:
533
-
534
- errors.add(:name, Sequel.lit("Album name is not valid"))
535
- errors.full_messages
536
- # => ["Album name is not valid"]
537
-
538
- Alternatively, feel free to override Sequel::Model::Errors#full_messages. As long as it returns an array of strings, overriding it is completely safe.
539
-
540
- === +count+
541
-
542
- +count+ returns the total number of error messages in the errors.
543
-
544
- album.errors.count # => 1
545
-
546
- == Other Validation Plugins
547
-
548
- === +constraint_validations+
549
-
550
- Sequel ships with a +constraint_validations+ plugin and extension, that allows you to setup constraints when creating your database tables, and have Model validations automatically created that mirror those constraints.
551
-
552
- === +auto_validations+
553
-
554
- auto_validations uses the not null and type information obtained from parsing the database schema, and the unique index information from parsing the database's index information, and automatically setting up not_null, string length, schema type, and unique validations. If you don't require customizing validation messages on a per-column basis, it can DRY up a lot of validation code.
555
-
556
- === +validation_class_methods+
557
-
558
- Sequel ships with the +validation_class_methods+ plugin, which uses class methods instead of instance methods to define validations. It exists mostly for legacy compatibility, but it is still supported.