module Sequel::Model::InstanceMethods

Sequel::Model instance methods that implement basic model functionality.

All of the model before/after/around hooks are implemented as instance methods that are called by Sequel when the appropriate action occurs. For example, when destroying a model object, Sequel will call around_destroy, which will call before_destroy, do the destroy, and then call after_destroy.
The following instance_methods all call the class method of the same name: columns, db, primary_key, db_schema.
The following accessor methods are defined via metaprogramming: raise_on_save_failure, raise_on_typecast_failure, require_modification, strict_param_setting, typecast_empty_string_to_nil, typecast_on_assignment, and use_transactions. The setter methods will change the setting for the instance, and the getter methods will check for an instance setting, then try the class setting if no instance setting has been set.

The hash of attribute values. Keys are symbols with the names of the underlying database columns. The returned hash is a reference to the receiver’s values hash, and modifying it will also modify the receiver’s values.

Artist.new(name: 'Bob').values # => {:name=>'Bob'}
Artist[1].values # => {:id=>1, :name=>'Jim', ...}

to_hash [R]

Artist.new(name: 'Bob').values # => {:name=>'Bob'}
Artist[1].values # => {:id=>1, :name=>'Jim', ...}

values [R]

Artist.new(name: 'Bob').values # => {:name=>'Bob'}
Artist[1].values # => {:id=>1, :name=>'Jim', ...}

Public Class Methods

new (values = OPTS) { |self| ... }

Source

     # File lib/sequel/model/base.rb
1212 def initialize(values = OPTS)
1213   @values = {}
1214   @new = @modified = true
1215   _initialize_nil_instance_variables
1216 
1217   initialize_set(values)
1218   _clear_changed_columns(:initialize)
1219   yield self if defined?(yield)
1220 end

Creates new instance and passes the given values to set. If a block is given, yield the instance to the block.

Arguments:

values: should be a hash to pass to set.

Artist.new(name: 'Bob')

Artist.new do |a|
  a.name = 'Bob'
end

Public Instance Methods

== (obj)

Source

     # File lib/sequel/model/base.rb
1259 def ==(obj)
1260   eql?(obj)
1261 end

Alias of eql?

=== (obj)

Source

     # File lib/sequel/model/base.rb
1269 def ===(obj)
1270   case pkv = pk
1271   when nil
1272     return false
1273   when Array
1274     return false if pkv.any?(&:nil?)
1275   end
1276 
1277   (obj.class == model) && (obj.pk == pkv)
1278 end

Case equality. By default, checks equality of the primary key value, see pk_equal?.

Artist[1] === Artist[1] # => true
Artist.new === Artist.new # => false
Artist[1].set(name: 'Bob') === Artist[1] # => true

Also aliased as: pk_equal?

[] (column)

Source

     # File lib/sequel/model/base.rb
1234 def [](column)
1235   @values[column]
1236 end

Returns value of the column’s attribute.

Artist[1][:id] #=> 1

[]= (column, value)

Source

     # File lib/sequel/model/base.rb
1246 def []=(column, value)
1247   # If it is new, it doesn't have a value yet, so we should
1248   # definitely set the new value.
1249   # If the column isn't in @values, we can't assume it is
1250   # NULL in the database, so assume it has changed.
1251   v = typecast_value(column, value)
1252   vals = @values
1253   if new? || !vals.include?(column) || v != (c = vals[column]) || v.class != c.class
1254     change_column_value(column, v)
1255   end
1256 end

Sets the value for the given column. If typecasting is enabled for this object, typecast the value based on the column’s type. If this is a new record or the typecasted value isn’t the same as the current value for the column, mark the column as changed.

a = Artist.new
a[:name] = 'Bob'
a.values #=> {:name=>'Bob'}

autoincrementing_primary_key ()

Source

     # File lib/sequel/model/base.rb
1301 def autoincrementing_primary_key
1302   primary_key
1303 end

The autoincrementing primary key for this model object. Should be overridden if you have a composite primary key with one part of it being autoincrementing.

cancel_action (msg=nil)

Source

     # File lib/sequel/model/base.rb
1309 def cancel_action(msg=nil)
1310   raise_hook_failure(msg)
1311 end

Cancel the current action. Should be called in before hooks to halt the processing of the action. If a msg argument is given and the model instance is configured to raise exceptions on failure, sets the message to use for the raised HookFailed exception.

changed_columns ()

Source

     # File lib/sequel/model/base.rb
1320 def changed_columns
1321   _changed_columns
1322 end

The columns that have been updated. This isn’t completely accurate, as it could contain columns whose values have not changed.

a = Artist[1]
a.changed_columns # => []
a.name = 'Bob'
a.changed_columns # => [:name]

delete ()

Source

     # File lib/sequel/model/base.rb
1329 def delete
1330   raise Sequel::Error, "can't delete frozen object" if frozen?
1331   _delete
1332   self
1333 end

Deletes and returns self. Does not run destroy hooks. Look into using destroy instead.

Artist[1].delete # DELETE FROM artists WHERE (id = 1)
# => #<Artist {:id=>1, ...}>

destroy (opts = OPTS)

Source

     # File lib/sequel/model/base.rb
1341 def destroy(opts = OPTS)
1342   raise Sequel::Error, "can't destroy frozen object" if frozen?
1343   checked_save_failure(opts){checked_transaction(opts){_destroy(opts)}}
1344 end

Like delete but runs hooks before and after delete. Uses a transaction if use_transactions is true or if the :transaction option is given and true.

Artist[1].destroy # BEGIN; DELETE FROM artists WHERE (id = 1); COMMIT;
# => #<Artist {:id=>1, ...}>

each (&block)

Source

     # File lib/sequel/model/base.rb
1351 def each(&block)
1352   @values.each(&block)
1353 end

Iterates through all of the current values using each.

Album[1].each{|k, v| puts "#{k} => #{v}"}
# id => 1
# name => 'Bob'

eql? (obj)

Source

     # File lib/sequel/model/base.rb
1360 def eql?(obj)
1361   (obj.class == model) && (obj.values == @values)
1362 end

Compares model instances by values.

Artist[1] == Artist[1] # => true
Artist.new == Artist.new # => true
Artist[1].set(name: 'Bob') == Artist[1] # => false

errors ()

Source

     # File lib/sequel/model/base.rb
1366 def errors
1367   @errors ||= errors_class.new
1368 end

Returns the validation errors associated with this object. See Errors.

exists? ()

Source

     # File lib/sequel/model/base.rb
1383 def exists?
1384   new? ? false : !this.get(EXISTS_SELECT_).nil?
1385 end

Returns true when current instance exists, false otherwise. Generally an object that isn’t new will exist unless it has been deleted. Uses a database query to check for existence, unless the model object is new, in which case this is always false.

Artist[1].exists? # SELECT 1 AS one FROM artists WHERE (id = 1)
# => true
Artist.new.exists?
# => false

extend (mod)

Source

     # File lib/sequel/model/base.rb
1389 def extend(mod)
1390   @singleton_setter_added = true
1391   super
1392 end

Ignore the model’s setter method cache when this instances extends a module, as the module may contain setter methods.

Calls superclass method

freeze ()

Source

     # File lib/sequel/model/base.rb
1397 def freeze
1398   unless errors.frozen?
1399     validate
1400     errors.freeze
1401   end
1402   values.freeze
1403   _changed_columns.freeze
1404   this if !new? && model.primary_key
1405   super
1406 end

Freeze the object in such a way that it is still usable but not modifiable. Once an object is frozen, you cannot modify it’s values, changed_columns, errors, or dataset.

Calls superclass method

hash ()

Source

     # File lib/sequel/model/base.rb
1415 def hash
1416   case primary_key
1417   when Array
1418     [model, !pk.all? ? @values : pk].hash
1419   when Symbol
1420     [model, pk.nil? ? @values : pk].hash
1421   else
1422     [model, @values].hash
1423   end
1424 end

Value that should be unique for objects with the same class and pk (if pk is not nil), or the same class and values (if pk is nil).

Artist[1].hash == Artist[1].hash # true
Artist[1].set(name: 'Bob').hash == Artist[1].hash # true
Artist.new.hash == Artist.new.hash # true
Artist.new(name: 'Bob').hash == Artist.new.hash # false

id ()

Source

     # File lib/sequel/model/base.rb
1430 def id
1431   @values[:id]
1432 end

Returns value for the :id attribute, even if the primary key is not id. To get the primary key value, use pk.

Artist[1].id # => 1

inspect ()

Source

     # File lib/sequel/model/base.rb
1436 def inspect
1437   "#<#{inspect_prefix} @values=#{inspect_values}>"
1438 end

Returns a string representation of the model instance including the class name and values.

keys ()

Source

     # File lib/sequel/model/base.rb
1445 def keys
1446   @values.keys
1447 end

Returns the keys in values. May not include all column names.

Artist.new.keys # => []
Artist.new(name: 'Bob').keys # => [:name]
Artist[1].keys # => [:id, :name]

lock! (style=:update)

Source

     # File lib/sequel/model/base.rb
1471 def lock!(style=:update)
1472   _refresh(this.lock_style(style)) unless new?
1473   self
1474 end

Refresh this record using :update lock style (by default, or the specified style when given), unless this is a new record. Returns self. This can be used to make sure no other process can modify the record during the transaction containing this call. Using this method only makes sense inside transactions.

If style is a string, it will be used directly. You should never pass a string to this method that is derived from user input, as that can lead to SQL injection.

A symbol may be used if the adapter supports that lock style.

a = Artist[1]
Artist.db.transaction do
  a.lock!
  a.update(name: 'A')
end

a = Artist[2]
Artist.db.transaction do
  a.lock!(:no_key_update)
  a.update(name: 'B')
end

marshallable! ()

Source

     # File lib/sequel/model/base.rb
1481 def marshallable!
1482   @this = nil
1483   self
1484 end

Remove elements of the model object that make marshalling fail. Returns self.

a = Artist[1]
a.marshallable!
Marshal.dump(a)

modified! (column=nil)

Source

     # File lib/sequel/model/base.rb
1501 def modified!(column=nil)
1502   _add_changed_column(column) if column
1503   @modified = true
1504 end

Explicitly mark the object as modified, so save_changes/update will run callbacks even if no columns have changed.

a = Artist[1]
a.save_changes # No callbacks run, as no changes
a.modified!
a.save_changes # Callbacks run, even though no changes made

If a column is given, specifically marked that column as modified, so that save_changes/update will include that column in the update. This should be used if you plan on mutating the column value instead of assigning a new column value:

a.modified!(:name)
a.name.gsub!(/[aeou]/, 'i')

modified? (column=nil)

Source

     # File lib/sequel/model/base.rb
1521 def modified?(column=nil)
1522   if column
1523     changed_columns.include?(column)
1524   else
1525     @modified || !changed_columns.empty?
1526   end
1527 end

Whether this object has been modified since last saved, used by save_changes to determine whether changes should be saved. New values are always considered modified.

a = Artist[1]
a.modified? # => false
a.set(name: 'Jim')
a.modified? # => true

If a column is given, specifically check if the given column has been modified:

a.modified?(:num_albums) # => false
a.num_albums = 10
a.modified?(:num_albums) # => true

new? ()

Source

     # File lib/sequel/model/base.rb
1533 def new?
1534   @new || false
1535 end

Returns true if the current instance represents a new record.

Artist.new.new? # => true
Artist[1].new? # => false

pk ()

Source

     # File lib/sequel/model/base.rb
1543 def pk
1544   raise(Error, "No primary key is associated with this model") unless key = primary_key
1545   if key.is_a?(Array)
1546     vals = @values
1547     key.map{|k| vals[k]}
1548   else
1549     @values[key]
1550   end
1551 end

Returns the primary key value identifying the model instance. Raises an Error if this model does not have a primary key. If the model has a composite primary key, returns an array of values.

Artist[1].pk # => 1
Artist[[1, 2]].pk # => [1, 2]

pk_equal? (obj)

If the receiver has a primary key value, returns true if the objects have the same class and primary key value. If the receiver’s primary key value is nil or is an array containing nil, returns false.

Artist[1].pk_equal?(Artist[1]) # => true
Artist.new.pk_equal?(Artist.new) # => false
Artist[1].set(name: 'Bob').pk_equal?(Artist[1]) # => true

Alias for: ===

pk_hash ()

Source

     # File lib/sequel/model/base.rb
1557 def pk_hash
1558   model.primary_key_hash(pk)
1559 end

Returns a hash mapping the receivers primary key column(s) to their values.

Artist[1].pk_hash # => {:id=>1}
Artist[[1, 2]].pk_hash # => {:id1=>1, :id2=>2}

qualified_pk_hash (qualifier=model.table_name)

Source

     # File lib/sequel/model/base.rb
1567 def qualified_pk_hash(qualifier=model.table_name)
1568   model.qualified_primary_key_hash(pk, qualifier)
1569 end

Returns a hash mapping the receivers qualified primary key column(s) to their values.

Artist[1].qualified_pk_hash
# => {Sequel[:artists][:id]=>1}
Artist[[1, 2]].qualified_pk_hash
# => {Sequel[:artists][:id1]=>1, Sequel[:artists][:id2]=>2}

refresh ()

Source

     # File lib/sequel/model/base.rb
1579 def refresh
1580   raise Sequel::Error, "can't refresh frozen object" if frozen?
1581   _refresh(this)
1582   self
1583 end

Reloads attributes from database and returns self. Also clears all changed_columns information. Raises an Error if the record no longer exists in the database.

a = Artist[1]
a.name = 'Jim'
a.refresh
a.name # => 'Bob'

reload ()

Source

     # File lib/sequel/model/base.rb
1586 def reload
1587   refresh
1588 end

Alias of refresh, but not aliased directly to make overriding in a plugin easier.

remove_key! (key)

Source

     # File lib/sequel/model/base.rb
1600 def remove_key!(key)
1601   @values.delete(key)
1602 end

Remove a key from the instances values, and return the value of the key.

a = Album[1]
a.values
# => {id: 1, artist_id: 2}
a.remove_key!(:artist_id)
# => 2
a.values
# => {id: 1}

save (opts=OPTS)

Source

     # File lib/sequel/model/base.rb
1629 def save(opts=OPTS)
1630   raise Sequel::Error, "can't save frozen object" if frozen?
1631   set_server(opts[:server]) if opts[:server] 
1632   unless _save_valid?(opts)
1633     raise(validation_failed_error) if raise_on_failure?(opts)
1634     return
1635   end
1636   checked_save_failure(opts){checked_transaction(opts){_save(opts)}}
1637 end

Creates or updates the record, after making sure the record is valid and before hooks execute successfully. Fails if:

the record is not valid, or
before_save calls cancel_action, or
the record is new and before_create calls cancel_action, or
the record is not new and before_update calls cancel_action.

If save fails and either raise_on_save_failure or the :raise_on_failure option is true, it raises ValidationFailed or HookFailed. Otherwise it returns nil.

If it succeeds, it returns self.

Takes the following options:

:changed: save all changed columns, instead of all columns or the columns given
:columns: array of specific columns that should be saved.
:raise_on_failure: set to true or false to override the current raise_on_save_failure setting
:server: set the server/shard on the object before saving, and use that server/shard in any transaction.
:transaction: set to true or false to override the current use_transactions setting
:validate: set to false to skip validation

save_changes (opts=OPTS)

Source

     # File lib/sequel/model/base.rb
1648 def save_changes(opts=OPTS)
1649   save(Hash[opts].merge!(:changed=>true)) || false if modified? 
1650 end

Saves only changed columns if the object has been modified. If the object has not been modified, returns nil. If unable to save, returns false unless raise_on_save_failure is true.

a = Artist[1]
a.save_changes # => nil
a.name = 'Jim'
a.save_changes # UPDATE artists SET name = 'Bob' WHERE (id = 1)
# => #<Artist {:id=>1, :name=>'Jim', ...}

set (hash)

Source

     # File lib/sequel/model/base.rb
1659 def set(hash)
1660   set_restricted(hash, :default)
1661 end

Updates the instance with the supplied values with support for virtual attributes, raising an exception if a value is used that doesn’t have a setter method (or ignoring it if strict_param_setting = false). Does not save the record.

artist.set(name: 'Jim')
artist.name # => 'Jim'

set_fields (hash, fields, opts=nil)

Source

     # File lib/sequel/model/base.rb
1689 def set_fields(hash, fields, opts=nil)
1690   opts = if opts
1691     model.default_set_fields_options.merge(opts)
1692   else
1693     model.default_set_fields_options
1694   end
1695 
1696   case missing = opts[:missing]
1697   when :skip, :raise
1698     do_raise = true if missing == :raise
1699     fields.each do |f|
1700       if hash.has_key?(f) 
1701         set_column_value("#{f}=", hash[f])
1702       elsif f.is_a?(Symbol) && hash.has_key?(sf = f.to_s)
1703         set_column_value("#{sf}=", hash[sf])
1704       elsif do_raise
1705         raise(Sequel::Error, "missing field in hash: #{f.inspect} not in #{hash.inspect}")
1706       end
1707     end
1708   else
1709     fields.each{|f| set_column_value("#{f}=", hash[f])}
1710   end
1711   self
1712 end

For each of the fields in the given array fields, call the setter method with the value of that hash entry for the field. Returns self.

You can provide an options hash, with the following options currently respected:

:missing: Can be set to :skip to skip missing entries or :raise to raise an Error for missing entries. The default behavior is not to check for missing entries, in which case the default value is used. To be friendly with most web frameworks, the missing check will also check for the string version of the argument in the hash if given a symbol.

Examples:

artist.set_fields({name: 'Jim'}, [:name])
artist.name # => 'Jim'

artist.set_fields({hometown: 'LA'}, [:name])
artist.name # => nil
artist.hometown # => 'Sac'

artist.name # => 'Jim'
artist.set_fields({}, [:name], missing: :skip)
artist.name # => 'Jim'

artist.name # => 'Jim'
artist.set_fields({}, [:name], missing: :raise)
# Sequel::Error raised

set_server (s)

Source

     # File lib/sequel/model/base.rb
1715 def set_server(s)
1716   @server = s
1717   @this = @this.server(s) if @this
1718   self
1719 end

Set the shard that this object is tied to. Returns self.

singleton_method_added (meth)

Source

     # File lib/sequel/model/base.rb
1722 def singleton_method_added(meth)
1723   @singleton_setter_added = true if meth.to_s.end_with?('=')
1724   super
1725 end

Clear the setter_methods cache when a method is added

Calls superclass method

skip_validation_on_next_save! ()

Source

     # File lib/sequel/model/base.rb
1732 def skip_validation_on_next_save!
1733   @skip_validation_on_next_save = true
1734 end

Skip all validation of the object on the next call to save, including the running of validation hooks. This is designed for and should only be used in cases where valid? is called before saving and the validate: false option cannot be passed to save.

this ()

Source

     # File lib/sequel/model/base.rb
1740 def this
1741   return @this if @this
1742   raise Error, "No dataset for model #{model}" unless ds = model.instance_dataset
1743   @this = use_server(ds.where(pk_hash))
1744 end

Returns naked dataset that should return only the row related to this instance.

Artist[1].this
# SELECT * FROM artists WHERE (id = 1) LIMIT 1

update (hash)

Source

     # File lib/sequel/model/base.rb
1749 def update(hash)
1750   update_restricted(hash, :default)
1751 end

Runs set with the passed hash and then runs save_changes.

artist.update(name: 'Jim') # UPDATE artists SET name = 'Jim' WHERE (id = 1)

update_fields (hash, fields, opts=nil)

Source

     # File lib/sequel/model/base.rb
1761 def update_fields(hash, fields, opts=nil)
1762   set_fields(hash, fields, opts)
1763   save_changes
1764 end

Update the instance’s values by calling set_fields with the arguments, then calls save_changes.

artist.update_fields({name: 'Jim'}, [:name])
# UPDATE artists SET name = 'Jim' WHERE (id = 1)

artist.update_fields({hometown: 'LA'}, [:name])
# UPDATE artists SET name = NULL WHERE (id = 1)

valid? (opts = OPTS)

Source

     # File lib/sequel/model/base.rb
1780 def valid?(opts = OPTS)
1781   _valid?(opts)
1782 rescue HookFailed
1783   false
1784 end

Validates the object and returns true if no errors are reported.

artist.set(name: 'Valid').valid? # => true
artist.set(name: 'Invalid').valid? # => false
artist.errors.full_messages # => ['name cannot be Invalid']

validate ()

Source

     # File lib/sequel/model/base.rb
1772 def validate
1773 end

Validates the object. If the object is invalid, errors should be added to the errors attribute. By default, does nothing, as all models are valid by default. See the “Model Validations” guide. for details about validation. Should not be called directly by user code, call valid? instead to check if an object is valid.

Private Instance Methods

_add_changed_column (column)

Source

     # File lib/sequel/model/base.rb
1789 def _add_changed_column(column)
1790   cc = _changed_columns
1791   cc << column unless cc.include?(column)
1792 end

Add a column as a changed column.

_changed_columns ()

Source

     # File lib/sequel/model/base.rb
1795 def _changed_columns
1796   @changed_columns ||= []
1797 end

Internal changed_columns method that just returns stored array.

_clear_changed_columns (_reason)

Source

     # File lib/sequel/model/base.rb
1802 def _clear_changed_columns(_reason)
1803   _changed_columns.clear
1804 end

Clear the changed columns. Reason is the reason for clearing the columns, and should be one of: :initialize, :refresh, :create or :update.

_delete ()

Source

     # File lib/sequel/model/base.rb
1808 def _delete
1809   n = _delete_without_checking
1810   raise(NoExistingObject, "Attempt to delete object did not result in a single row modification (Rows Deleted: #{n}, SQL: #{_delete_dataset.delete_sql})") if require_modification && n != 1
1811   n
1812 end

Do the deletion of the object’s dataset, and check that the row was actually deleted.

_delete_dataset ()

Source

     # File lib/sequel/model/base.rb
1816 def _delete_dataset
1817   this
1818 end

The dataset to use when deleting the object. The same as the object’s dataset by default.

_delete_without_checking ()

Source

     # File lib/sequel/model/base.rb
1822 def _delete_without_checking
1823   if sql = (m = model).fast_instance_delete_sql
1824     sql = sql.dup
1825     ds = use_server(m.dataset)
1826     ds.literal_append(sql, pk)
1827     ds.with_sql_delete(sql)
1828   else
1829     _delete_dataset.delete 
1830   end
1831 end

Actually do the deletion of the object’s dataset. Return the number of rows modified.

_destroy (opts)

Source

     # File lib/sequel/model/base.rb
1835 def _destroy(opts)
1836   called = false
1837   around_destroy do
1838     called = true
1839     before_destroy
1840     _destroy_delete
1841     after_destroy
1842   end
1843   raise_hook_failure(:around_destroy) unless called
1844   self
1845 end

Internal destroy method, separated from destroy to allow running inside a transaction

_destroy_delete ()

Source

     # File lib/sequel/model/base.rb
1850 def _destroy_delete
1851   delete
1852 end

Internal delete method to call when destroying an object, separated from delete to allow you to override destroy’s version without affecting delete.

_insert ()

Source

     # File lib/sequel/model/base.rb
1856 def _insert
1857   ds = _insert_dataset
1858   if _use_insert_select?(ds) && !(h = _insert_select_raw(ds)).nil?
1859     _save_set_values(h) if h
1860     nil
1861   else
1862     iid = _insert_raw(ds)
1863     # if we have a regular primary key and it's not set in @values,
1864     # we assume it's the last inserted id
1865     if (pk = autoincrementing_primary_key) && pk.is_a?(Symbol) && !(vals = @values)[pk]
1866       vals[pk] = iid
1867     end
1868     pk
1869   end
1870 end

Insert the record into the database, returning the primary key if the record should be refreshed from the database.

_insert_dataset ()

Source

     # File lib/sequel/model/base.rb
1874 def _insert_dataset
1875   use_server(model.instance_dataset)
1876 end

The dataset to use when inserting a new object. The same as the model’s dataset by default.

_insert_raw (ds)

Source

     # File lib/sequel/model/base.rb
1879 def _insert_raw(ds)
1880   ds.insert(_insert_values)
1881 end

Insert into the given dataset and return the primary key created (if any).

_insert_select_raw (ds)

Source

     # File lib/sequel/model/base.rb
1884 def _insert_select_raw(ds)
1885   ds.insert_select(_insert_values)
1886 end

Insert into the given dataset and return the hash of column values.

_refresh (dataset)

Source

     # File lib/sequel/model/base.rb
1894 def _refresh(dataset)
1895   _refresh_set_values(_refresh_get(dataset) || raise(NoExistingObject, "Record not found"))
1896   _clear_changed_columns(:refresh)
1897 end

Refresh using a particular dataset, used inside save to make sure the same server is used for reading newly inserted values from the database

_refresh_get (dataset)

Source

     # File lib/sequel/model/base.rb
1900 def _refresh_get(dataset)
1901   if (sql = model.fast_pk_lookup_sql) && !dataset.opts[:lock]
1902     sql = sql.dup
1903     ds = use_server(dataset)
1904     ds.literal_append(sql, pk)
1905     ds.with_sql_first(sql)
1906   else
1907     dataset.first
1908   end
1909 end

Get the row of column data from the database.

_refresh_set_values (h)

Source

     # File lib/sequel/model/base.rb
1912 def _refresh_set_values(h)
1913   @values = h
1914 end

Set the values to the given hash after refreshing.

_save (opts)

Source

     # File lib/sequel/model/base.rb
1918 def _save(opts)
1919   pk = nil
1920   called_save = false
1921   called_cu = false
1922   around_save do
1923     called_save = true
1924     before_save
1925 
1926     if new?
1927       around_create do
1928         called_cu = true
1929         before_create
1930         pk = _insert
1931         @this = nil
1932         @new = false
1933         @modified = false
1934         pk ? _save_refresh : _clear_changed_columns(:create)
1935         after_create
1936         true
1937       end
1938       raise_hook_failure(:around_create) unless called_cu
1939     else
1940       around_update do
1941         called_cu = true
1942         before_update
1943         columns = opts[:columns]
1944         if columns.nil?
1945           columns_updated = if opts[:changed]
1946             _save_update_changed_columns_hash
1947           else
1948             _save_update_all_columns_hash
1949           end
1950           _clear_changed_columns(:update)
1951         else # update only the specified columns
1952           columns = Array(columns)
1953           columns_updated = @values.reject{|k, v| !columns.include?(k)}
1954           _changed_columns.reject!{|c| columns.include?(c)}
1955         end
1956         _update_columns(columns_updated)
1957         @this = nil
1958         @modified = false
1959         after_update
1960         true
1961       end
1962       raise_hook_failure(:around_update) unless called_cu
1963     end
1964     after_save
1965     true
1966   end
1967   raise_hook_failure(:around_save) unless called_save
1968   self
1969 end

Internal version of save, split from save to allow running inside it’s own transaction.

_save_refresh ()

Source

     # File lib/sequel/model/base.rb
1974 def _save_refresh
1975   _save_set_values(_refresh_get(this.server?(:default)) || raise(NoExistingObject, "Record not found"))
1976   _clear_changed_columns(:create)
1977 end

Refresh the object after saving it, used to get default values of all columns. Separated from _save so it can be overridden to avoid the refresh.

_save_set_values (h)

Source

     # File lib/sequel/model/base.rb
1981 def _save_set_values(h)
1982   @values = h
1983 end

Set values to the provided hash. Called after a create, to set the full values from the database in the model instance.

_save_update_all_columns_hash ()

Source

     # File lib/sequel/model/base.rb
1991 def _save_update_all_columns_hash
1992   v = Hash[@values]
1993   cc = changed_columns
1994   Array(primary_key).each{|x| v.delete(x) unless cc.include?(x)}
1995   v
1996 end

Return a hash of values used when saving all columns of an existing object (i.e. not passing specific columns to save or using update/save_changes). Defaults to all of the object’s values except unmodified primary key columns, as some databases don’t like you setting primary key values even to their existing values.

_save_update_changed_columns_hash ()

Source

     # File lib/sequel/model/base.rb
2009 def _save_update_changed_columns_hash
2010   cc = changed_columns
2011   @values.reject{|k,v| !cc.include?(k)}
2012 end

Return a hash of values used when saving changed columns of an existing object. Defaults to all of the objects current values that are recorded as modified.

_save_valid? (opts)

Source

     # File lib/sequel/model/base.rb
2018 def _save_valid?(opts)
2019   if @skip_validation_on_next_save
2020     @skip_validation_on_next_save = false
2021     return true
2022   end
2023 
2024   checked_save_failure(opts){_valid?(opts)}
2025 end

Validate the object if validating on save. Skips validation completely (including validation hooks) if skip_validation_on_save! has been called on the object, resetting the flag so that future saves will validate.

_update (columns)

Source

     # File lib/sequel/model/base.rb
2036 def _update(columns)
2037   n = _update_without_checking(columns)
2038   raise(NoExistingObject, "Attempt to update object did not result in a single row modification (SQL: #{_update_dataset.update_sql(columns)})") if require_modification && n != 1
2039   n
2040 end

Update this instance’s dataset with the supplied column hash, checking that only a single row was modified.

_update_columns (columns)

Source

     # File lib/sequel/model/base.rb
2030 def _update_columns(columns)
2031   _update(columns) unless columns.empty?
2032 end

Call _update with the given columns, if any are present. Plugins can override this method in order to update with additional columns, even when the column hash is initially empty.

_update_dataset ()

Source

     # File lib/sequel/model/base.rb
2044 def _update_dataset
2045   this
2046 end

The dataset to use when updating an object. The same as the object’s dataset by default.

_update_without_checking (columns)

Source

     # File lib/sequel/model/base.rb
2049 def _update_without_checking(columns)
2050   _update_dataset.update(columns)
2051 end

Update this instances dataset with the supplied column hash.

_use_insert_select? (ds)

Source

     # File lib/sequel/model/base.rb
2054 def _use_insert_select?(ds)
2055   (!ds.opts[:select] || ds.opts[:returning]) && ds.supports_insert_select? 
2056 end

Whether to use insert_select when inserting a new row.

_valid? (opts)

Source

     # File lib/sequel/model/base.rb
2059 def _valid?(opts)
2060   return errors.empty? if frozen?
2061   errors.clear
2062   called = false
2063   skip_validate = opts[:validate] == false
2064   around_validation do
2065     called = true
2066     before_validation
2067     validate unless skip_validate
2068     after_validation
2069   end
2070 
2071   return true if skip_validate
2072 
2073   if called
2074     errors.empty?
2075   else
2076     raise_hook_failure(:around_validation)
2077   end
2078 end

Internal validation method, running validation hooks.

change_column_value (column, value)

Source

     # File lib/sequel/model/base.rb
2102 def change_column_value(column, value)
2103   _add_changed_column(column)
2104   @values[column] = value
2105 end

Change the value of the column to given value, recording the change.

checked_save_failure (opts) { || ... }

Source

     # File lib/sequel/model/base.rb
2082 def checked_save_failure(opts)
2083   if raise_on_failure?(opts)
2084     yield
2085   else
2086     begin
2087       yield
2088     rescue HookFailed 
2089       nil
2090     end
2091   end
2092 end

If not raising on failure, check for HookFailed being raised by yielding and swallow it.

checked_transaction (opts=OPTS, &block)

Source

     # File lib/sequel/model/base.rb
2095 def checked_transaction(opts=OPTS, &block)
2096   h = {:server=>this_server}.merge!(opts)
2097   h[:skip_transaction] = true unless use_transaction?(opts)
2098   db.transaction(h, &block)
2099 end

If transactions should be used, wrap the yield in a transaction block.

errors_class ()

Source

     # File lib/sequel/model/base.rb
2108 def errors_class
2109   Errors
2110 end

Default error class used for errors.

hook_failed_error (msg)

Source

     # File lib/sequel/model/base.rb
2113 def hook_failed_error(msg)
2114   HookFailed.new(msg, self)
2115 end

A HookFailed exception for the given message tied to the current instance.

initialize_clone (other)

Source

     # File lib/sequel/model/base.rb
2119 def initialize_clone(other)
2120   super
2121   freeze if other.frozen?
2122   self
2123 end

Clone constructor – freeze internal data structures if the original’s are frozen.

Calls superclass method

initialize_copy (other)

Source

     # File lib/sequel/model/base.rb
2126 def initialize_copy(other)
2127   super
2128   @values = Hash[@values]
2129   @changed_columns = @changed_columns.dup if @changed_columns
2130   @errors = @errors.dup if @errors
2131   self
2132 end

Copy constructor – Duplicate internal data structures.

Calls superclass method

initialize_set (h)

Source

     # File lib/sequel/model/base.rb
2137 def initialize_set(h)
2138   set(h) unless h.empty?
2139 end

Set the columns with the given hash. By default, the same as set, but exists so it can be overridden. This is called only for new records, before changed_columns is cleared.

inspect_prefix ()

Source

     # File lib/sequel/model/base.rb
2142 def inspect_prefix
2143   model.name
2144 end

Default inspect output for the inspect, by default, just showing the class.

inspect_values ()

Source

     # File lib/sequel/model/base.rb
2147 def inspect_values
2148   @values.inspect
2149 end

Default inspect output for the values hash, overwrite to change what inspect displays.

raise_hook_failure (type=nil)

Source

     # File lib/sequel/model/base.rb
2161 def raise_hook_failure(type=nil)
2162   msg = case type
2163   when String
2164     type
2165   when Symbol
2166     "the #{type} hook failed"
2167   else
2168     "a hook failed"
2169   end
2170 
2171   raise hook_failed_error(msg)
2172 end

Raise an error appropriate to the hook type. May be swallowed by checked_save_failure depending on the raise_on_failure? setting.

raise_on_failure? (opts)

Source

     # File lib/sequel/model/base.rb
2155 def raise_on_failure?(opts)
2156   opts.fetch(:raise_on_failure, raise_on_save_failure)
2157 end

Whether to raise or return false if this action fails. If the :raise_on_failure option is present in the hash, use that, otherwise, fallback to the object’s raise_on_save_failure (if set), or class’s default (if not).

schema_type_class (column)

Source

     # File lib/sequel/model/base.rb
2175 def schema_type_class(column)
2176   if (sch = db_schema[column]) && (type = sch[:type])
2177     db.schema_type_class(type)
2178   end
2179 end

Get the ruby class or classes related to the given column’s type.

set_restricted (hash, type)

Source

     # File lib/sequel/model/base.rb
2183 def set_restricted(hash, type)
2184   return self if hash.empty?
2185   meths = setter_methods(type)
2186   strict = strict_param_setting
2187   hash.each do |k,v|
2188     k = k.to_s
2189     m = "#{k}="
2190     if meths.include?(m)
2191       set_column_value(m, v)
2192     elsif strict
2193       # Avoid using respond_to? or creating symbols from user input
2194       if public_methods.map(&:to_s).include?(m)
2195         if Array(model.primary_key).map(&:to_s).member?(k) && model.restrict_primary_key?
2196           raise MassAssignmentRestriction.create("#{k} is a restricted primary key", self, k)
2197         else
2198           raise MassAssignmentRestriction.create("#{k} is a restricted column", self, k)
2199         end
2200       else
2201         raise MassAssignmentRestriction.create("method #{m} doesn't exist", self, k)
2202       end
2203     end
2204   end
2205   self
2206 end

Call setter methods based on keys in hash, with the appropriate values. Restrict which methods can be called based on the provided type.

setter_methods (type)

Source

     # File lib/sequel/model/base.rb
2214 def setter_methods(type)
2215   if type == :default && !@singleton_setter_added
2216     return model.setter_methods
2217   end
2218 
2219   meths = methods.map(&:to_s).select{|l| l.end_with?('=')} - RESTRICTED_SETTER_METHODS
2220   meths -= Array(primary_key).map{|x| "#{x}="} if primary_key && model.restrict_primary_key?
2221   meths
2222 end

Returns all methods that can be used for attribute assignment (those that end with =), depending on the type:

:default: Use the default methods allowed in the model class.
:all: Allow setting all setters, except those specifically restricted (such as ==).
Array: Only allow setting of columns in the given array.

this_server ()

Source

     # File lib/sequel/model/base.rb
2226 def this_server
2227   if (s = @server)
2228     s
2229   elsif (t = @this)
2230     t.opts[:server] || :default
2231   else
2232     model.dataset.opts[:server] || :default
2233   end
2234 end

The server/shard that the model object’s dataset uses, or :default if the model object’s dataset does not have an associated shard.

typecast_value (column, value)

Source

     # File lib/sequel/model/base.rb
2239 def typecast_value(column, value)
2240   return value unless typecast_on_assignment && db_schema && (col_schema = db_schema[column])
2241   value = nil if '' == value and typecast_empty_string_to_nil and col_schema[:type] and ![:string, :blob].include?(col_schema[:type])
2242   raise(InvalidValue, "nil/NULL is not allowed for the #{column} column") if raise_on_typecast_failure && value.nil? && (col_schema[:allow_null] == false)
2243   begin
2244     model.db.typecast_value(col_schema[:type], value)
2245   rescue InvalidValue
2246     raise_on_typecast_failure ? raise : value
2247   end
2248 end

Typecast the value to the column’s type if typecasting. Calls the database’s typecast_value method, so database adapters can override/augment the handling for database specific column types.

update_restricted (hash, type)

Source

     # File lib/sequel/model/base.rb
2251 def update_restricted(hash, type)
2252   set_restricted(hash, type)
2253   save_changes
2254 end

Set the columns, filtered by the only and except arrays.

use_server (ds)

Source

     # File lib/sequel/model/base.rb
2257 def use_server(ds)
2258   @server ? ds.server(@server) : ds
2259 end

Set the given dataset to use the current object’s shard.

use_transaction? (opts = OPTS)

Source

     # File lib/sequel/model/base.rb
2264 def use_transaction?(opts = OPTS)
2265   opts.fetch(:transaction, use_transactions)
2266 end

Whether to use a transaction for this action. If the :transaction option is present in the hash, use that, otherwise, fallback to the object’s default (if set), or class’s default (if not).

validation_failed_error ()

Source

     # File lib/sequel/model/base.rb
2269 def validation_failed_error
2270   ValidationFailed.new(self)
2271 end

An ValidationFailed exception instance to raise for this instance.

module Sequel::Model::InstanceMethods

Constants

Attributes

Public Class Methods

Public Instance Methods

Private Instance Methods