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.

Constants

EXISTS_SELECT_

Attributes

_insert_values[R]

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| ... } click to toggle source

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

     # File lib/sequel/model/base.rb
1136 def initialize(values = OPTS)
1137   @values = {}
1138   @new = true
1139   @modified = true
1140   initialize_set(values)
1141   _clear_changed_columns(:initialize)
1142   yield self if defined?(yield)
1143 end

Public Instance Methods

==(obj) click to toggle source

Alias of eql?

     # File lib/sequel/model/base.rb
1173 def ==(obj)
1174   eql?(obj)
1175 end

===(obj) click to toggle source

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

     # File lib/sequel/model/base.rb
1183 def ===(obj)
1184   case pkv = pk
1185   when nil
1186     return false
1187   when Array
1188     return false if pkv.any?(&:nil?)
1189   end
1190 
1191   (obj.class == model) && (obj.pk == pkv)
1192 end

Also aliased as: pk_equal?

[](column) click to toggle source

Returns value of the column’s attribute.

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

     # File lib/sequel/model/base.rb
1148 def [](column)
1149   @values[column]
1150 end

[]=(column, value) click to toggle source

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'}

     # File lib/sequel/model/base.rb
1160 def []=(column, value)
1161   # If it is new, it doesn't have a value yet, so we should
1162   # definitely set the new value.
1163   # If the column isn't in @values, we can't assume it is
1164   # NULL in the database, so assume it has changed.
1165   v = typecast_value(column, value)
1166   vals = @values
1167   if new? || !vals.include?(column) || v != (c = vals[column]) || v.class != c.class
1168     change_column_value(column, v)
1169   end
1170 end

autoincrementing_primary_key() click to toggle source

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.

     # File lib/sequel/model/base.rb
1215 def autoincrementing_primary_key
1216   primary_key
1217 end

cancel_action(msg=nil) click to toggle source

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.

     # File lib/sequel/model/base.rb
1223 def cancel_action(msg=nil)
1224   raise_hook_failure(msg)
1225 end

changed_columns() click to toggle source

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]

     # File lib/sequel/model/base.rb
1234 def changed_columns
1235   _changed_columns
1236 end

delete() click to toggle source

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, ...}>

     # File lib/sequel/model/base.rb
1243 def delete
1244   raise Sequel::Error, "can't delete frozen object" if frozen?
1245   _delete
1246   self
1247 end

destroy(opts = OPTS) click to toggle source

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, ...}>

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

each(&block) click to toggle source

Iterates through all of the current values using each.

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

     # File lib/sequel/model/base.rb
1265 def each(&block)
1266   @values.each(&block)
1267 end

eql?(obj) click to toggle source

Compares model instances by values.

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

     # File lib/sequel/model/base.rb
1274 def eql?(obj)
1275   (obj.class == model) && (obj.values == @values)
1276 end

errors() click to toggle source

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

     # File lib/sequel/model/base.rb
1280 def errors
1281   @errors ||= errors_class.new
1282 end

exists?() click to toggle source

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

     # File lib/sequel/model/base.rb
1297 def exists?
1298   new? ? false : !this.get(EXISTS_SELECT_).nil?
1299 end

extend(mod) click to toggle source

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

Calls superclass method

     # File lib/sequel/model/base.rb
1303 def extend(mod)
1304   @singleton_setter_added = true
1305   super
1306 end

freeze() click to toggle source

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

     # File lib/sequel/model/base.rb
1311 def freeze
1312   unless errors.frozen?
1313     validate
1314     errors.freeze
1315   end
1316   values.freeze
1317   _changed_columns.freeze
1318   this if !new? && model.primary_key
1319   super
1320 end

hash() click to toggle source

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

     # File lib/sequel/model/base.rb
1329 def hash
1330   case primary_key
1331   when Array
1332     [model, !pk.all? ? @values : pk].hash
1333   when Symbol
1334     [model, pk.nil? ? @values : pk].hash
1335   else
1336     [model, @values].hash
1337   end
1338 end

id() click to toggle source

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

     # File lib/sequel/model/base.rb
1344 def id
1345   @values[:id]
1346 end

inspect() click to toggle source

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

     # File lib/sequel/model/base.rb
1350 def inspect
1351   "#<#{inspect_prefix} @values=#{inspect_values}>"
1352 end

keys() click to toggle source

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]

     # File lib/sequel/model/base.rb
1359 def keys
1360   @values.keys
1361 end

lock!(style=:update) click to toggle source

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

     # File lib/sequel/model/base.rb
1385 def lock!(style=:update)
1386   _refresh(this.lock_style(style)) unless new?
1387   self
1388 end

marshallable!() click to toggle source

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

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

     # File lib/sequel/model/base.rb
1395 def marshallable!
1396   @this = nil
1397   self
1398 end

modified!(column=nil) click to toggle source

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')

     # File lib/sequel/model/base.rb
1415 def modified!(column=nil)
1416   _add_changed_column(column) if column
1417   @modified = true
1418 end

modified?(column=nil) click to toggle source

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

     # File lib/sequel/model/base.rb
1435 def modified?(column=nil)
1436   if column
1437     changed_columns.include?(column)
1438   else
1439     @modified || !changed_columns.empty?
1440   end
1441 end

new?() click to toggle source

Returns true if the current instance represents a new record.

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

     # File lib/sequel/model/base.rb
1447 def new?
1448   defined?(@new) ? @new : (@new = false)
1449 end

pk() click to toggle source

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]

     # File lib/sequel/model/base.rb
1457 def pk
1458   raise(Error, "No primary key is associated with this model") unless key = primary_key
1459   if key.is_a?(Array)
1460     vals = @values
1461     key.map{|k| vals[k]}
1462   else
1463     @values[key]
1464   end
1465 end

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() click to toggle source

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}

     # File lib/sequel/model/base.rb
1471 def pk_hash
1472   model.primary_key_hash(pk)
1473 end

qualified_pk_hash(qualifier=model.table_name) click to toggle source

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}

     # File lib/sequel/model/base.rb
1481 def qualified_pk_hash(qualifier=model.table_name)
1482   model.qualified_primary_key_hash(pk, qualifier)
1483 end

refresh() click to toggle source

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'

     # File lib/sequel/model/base.rb
1493 def refresh
1494   raise Sequel::Error, "can't refresh frozen object" if frozen?
1495   _refresh(this)
1496   self
1497 end

reload() click to toggle source

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

     # File lib/sequel/model/base.rb
1500 def reload
1501   refresh
1502 end

remove_key!(key) click to toggle source

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}

     # File lib/sequel/model/base.rb
1514 def remove_key!(key)
1515   @values.delete(key)
1516 end

save(opts=OPTS) click to toggle source

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

     # File lib/sequel/model/base.rb
1543 def save(opts=OPTS)
1544   raise Sequel::Error, "can't save frozen object" if frozen?
1545   set_server(opts[:server]) if opts[:server] 
1546   unless _save_valid?(opts)
1547     raise(validation_failed_error) if raise_on_failure?(opts)
1548     return
1549   end
1550   checked_save_failure(opts){checked_transaction(opts){_save(opts)}}
1551 end

save_changes(opts=OPTS) click to toggle source

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', ...}

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

set(hash) click to toggle source

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'

     # File lib/sequel/model/base.rb
1573 def set(hash)
1574   set_restricted(hash, :default)
1575 end

set_fields(hash, fields, opts=nil) click to toggle source

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

     # File lib/sequel/model/base.rb
1603 def set_fields(hash, fields, opts=nil)
1604   opts = if opts
1605     model.default_set_fields_options.merge(opts)
1606   else
1607     model.default_set_fields_options
1608   end
1609 
1610   case missing = opts[:missing]
1611   when :skip, :raise
1612     do_raise = true if missing == :raise
1613     fields.each do |f|
1614       if hash.has_key?(f) 
1615         set_column_value("#{f}=", hash[f])
1616       elsif f.is_a?(Symbol) && hash.has_key?(sf = f.to_s)
1617         set_column_value("#{sf}=", hash[sf])
1618       elsif do_raise
1619         raise(Sequel::Error, "missing field in hash: #{f.inspect} not in #{hash.inspect}")
1620       end
1621     end
1622   else
1623     fields.each{|f| set_column_value("#{f}=", hash[f])}
1624   end
1625   self
1626 end

set_server(s) click to toggle source

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

     # File lib/sequel/model/base.rb
1629 def set_server(s)
1630   @server = s
1631   @this = @this.server(s) if @this
1632   self
1633 end

singleton_method_added(meth) click to toggle source

Clear the setter_methods cache when a method is added

Calls superclass method

     # File lib/sequel/model/base.rb
1636 def singleton_method_added(meth)
1637   @singleton_setter_added = true if meth.to_s.end_with?('=')
1638   super
1639 end

skip_validation_on_next_save!() click to toggle source

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.

     # File lib/sequel/model/base.rb
1646 def skip_validation_on_next_save!
1647   @skip_validation_on_next_save = true
1648 end

this() click to toggle source

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

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

     # File lib/sequel/model/base.rb
1654 def this
1655   return @this if @this
1656   raise Error, "No dataset for model #{model}" unless ds = model.instance_dataset
1657   @this = use_server(ds.where(pk_hash))
1658 end

update(hash) click to toggle source

Runs set with the passed hash and then runs save_changes.

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

     # File lib/sequel/model/base.rb
1663 def update(hash)
1664   update_restricted(hash, :default)
1665 end

update_fields(hash, fields, opts=nil) click to toggle source

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)

     # File lib/sequel/model/base.rb
1675 def update_fields(hash, fields, opts=nil)
1676   set_fields(hash, fields, opts)
1677   save_changes
1678 end

valid?(opts = OPTS) click to toggle source

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']

     # File lib/sequel/model/base.rb
1694 def valid?(opts = OPTS)
1695   _valid?(opts)
1696 rescue HookFailed
1697   false
1698 end

validate() click to toggle source

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.

     # File lib/sequel/model/base.rb
1686 def validate
1687 end

Private Instance Methods

_add_changed_column(column) click to toggle source

Add a column as a changed column.

     # File lib/sequel/model/base.rb
1703 def _add_changed_column(column)
1704   cc = _changed_columns
1705   cc << column unless cc.include?(column)
1706 end

_changed_columns() click to toggle source

Internal changed_columns method that just returns stored array.

     # File lib/sequel/model/base.rb
1709 def _changed_columns
1710   @changed_columns ||= []
1711 end

_clear_changed_columns(_reason) click to toggle source

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

     # File lib/sequel/model/base.rb
1716 def _clear_changed_columns(_reason)
1717   _changed_columns.clear
1718 end

_delete() click to toggle source

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

     # File lib/sequel/model/base.rb
1722 def _delete
1723   n = _delete_without_checking
1724   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
1725   n
1726 end

_delete_dataset() click to toggle source

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

     # File lib/sequel/model/base.rb
1730 def _delete_dataset
1731   this
1732 end

_delete_without_checking() click to toggle source

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

     # File lib/sequel/model/base.rb
1736 def _delete_without_checking
1737   if sql = (m = model).fast_instance_delete_sql
1738     sql = sql.dup
1739     ds = use_server(m.dataset)
1740     ds.literal_append(sql, pk)
1741     ds.with_sql_delete(sql)
1742   else
1743     _delete_dataset.delete 
1744   end
1745 end

_destroy(opts) click to toggle source

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

     # File lib/sequel/model/base.rb
1749 def _destroy(opts)
1750   called = false
1751   around_destroy do
1752     called = true
1753     before_destroy
1754     _destroy_delete
1755     after_destroy
1756   end
1757   raise_hook_failure(:around_destroy) unless called
1758   self
1759 end

_destroy_delete() click to toggle source

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

     # File lib/sequel/model/base.rb
1764 def _destroy_delete
1765   delete
1766 end

_insert() click to toggle source

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

     # File lib/sequel/model/base.rb
1770 def _insert
1771   ds = _insert_dataset
1772   if _use_insert_select?(ds) && !(h = _insert_select_raw(ds)).nil?
1773     _save_set_values(h) if h
1774     nil
1775   else
1776     iid = _insert_raw(ds)
1777     # if we have a regular primary key and it's not set in @values,
1778     # we assume it's the last inserted id
1779     if (pk = autoincrementing_primary_key) && pk.is_a?(Symbol) && !(vals = @values)[pk]
1780       vals[pk] = iid
1781     end
1782     pk
1783   end
1784 end

_insert_dataset() click to toggle source

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

     # File lib/sequel/model/base.rb
1788 def _insert_dataset
1789   use_server(model.instance_dataset)
1790 end

_insert_raw(ds) click to toggle source

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

     # File lib/sequel/model/base.rb
1793 def _insert_raw(ds)
1794   ds.insert(_insert_values)
1795 end

_insert_select_raw(ds) click to toggle source

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

     # File lib/sequel/model/base.rb
1798 def _insert_select_raw(ds)
1799   ds.insert_select(_insert_values)
1800 end

_refresh(dataset) click to toggle source

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

     # File lib/sequel/model/base.rb
1808 def _refresh(dataset)
1809   _refresh_set_values(_refresh_get(dataset) || raise(NoExistingObject, "Record not found"))
1810   _clear_changed_columns(:refresh)
1811 end

_refresh_get(dataset) click to toggle source

Get the row of column data from the database.

     # File lib/sequel/model/base.rb
1814 def _refresh_get(dataset)
1815   if (sql = model.fast_pk_lookup_sql) && !dataset.opts[:lock]
1816     sql = sql.dup
1817     ds = use_server(dataset)
1818     ds.literal_append(sql, pk)
1819     ds.with_sql_first(sql)
1820   else
1821     dataset.first
1822   end
1823 end

_refresh_set_values(h) click to toggle source

Set the values to the given hash after refreshing.

     # File lib/sequel/model/base.rb
1826 def _refresh_set_values(h)
1827   @values = h
1828 end

_save(opts) click to toggle source

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

     # File lib/sequel/model/base.rb
1832 def _save(opts)
1833   pk = nil
1834   called_save = false
1835   called_cu = false
1836   around_save do
1837     called_save = true
1838     before_save
1839 
1840     if new?
1841       around_create do
1842         called_cu = true
1843         before_create
1844         pk = _insert
1845         @this = nil
1846         @new = false
1847         @modified = false
1848         pk ? _save_refresh : _clear_changed_columns(:create)
1849         after_create
1850         true
1851       end
1852       raise_hook_failure(:around_create) unless called_cu
1853     else
1854       around_update do
1855         called_cu = true
1856         before_update
1857         columns = opts[:columns]
1858         if columns.nil?
1859           columns_updated = if opts[:changed]
1860             _save_update_changed_colums_hash
1861           else
1862             _save_update_all_columns_hash
1863           end
1864           _clear_changed_columns(:update)
1865         else # update only the specified columns
1866           columns = Array(columns)
1867           columns_updated = @values.reject{|k, v| !columns.include?(k)}
1868           _changed_columns.reject!{|c| columns.include?(c)}
1869         end
1870         _update_columns(columns_updated)
1871         @this = nil
1872         @modified = false
1873         after_update
1874         true
1875       end
1876       raise_hook_failure(:around_update) unless called_cu
1877     end
1878     after_save
1879     true
1880   end
1881   raise_hook_failure(:around_save) unless called_save
1882   self
1883 end

_save_refresh() click to toggle source

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.

     # File lib/sequel/model/base.rb
1888 def _save_refresh
1889   _save_set_values(_refresh_get(this.server?(:default)) || raise(NoExistingObject, "Record not found"))
1890   _clear_changed_columns(:create)
1891 end

_save_set_values(h) click to toggle source

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

     # File lib/sequel/model/base.rb
1895 def _save_set_values(h)
1896   @values = h
1897 end

_save_update_all_columns_hash() click to toggle source

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.

     # File lib/sequel/model/base.rb
1905 def _save_update_all_columns_hash
1906   v = Hash[@values]
1907   cc = changed_columns
1908   Array(primary_key).each{|x| v.delete(x) unless cc.include?(x)}
1909   v
1910 end

_save_update_changed_colums_hash() click to toggle source

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.

     # File lib/sequel/model/base.rb
1915 def _save_update_changed_colums_hash
1916   cc = changed_columns
1917   @values.reject{|k,v| !cc.include?(k)}
1918 end

_save_valid?(opts) click to toggle source

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.

     # File lib/sequel/model/base.rb
1924 def _save_valid?(opts)
1925   if @skip_validation_on_next_save
1926     @skip_validation_on_next_save = false
1927     return true
1928   end
1929 
1930   checked_save_failure(opts){_valid?(opts)}
1931 end

_update(columns) click to toggle source

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

     # File lib/sequel/model/base.rb
1942 def _update(columns)
1943   n = _update_without_checking(columns)
1944   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
1945   n
1946 end

_update_columns(columns) click to toggle source

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.

     # File lib/sequel/model/base.rb
1936 def _update_columns(columns)
1937   _update(columns) unless columns.empty?
1938 end

_update_dataset() click to toggle source

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

     # File lib/sequel/model/base.rb
1950 def _update_dataset
1951   this
1952 end

_update_without_checking(columns) click to toggle source

Update this instances dataset with the supplied column hash.

     # File lib/sequel/model/base.rb
1955 def _update_without_checking(columns)
1956   _update_dataset.update(columns)
1957 end

_use_insert_select?(ds) click to toggle source

Whether to use insert_select when inserting a new row.

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

_valid?(opts) click to toggle source

Internal validation method, running validation hooks.

     # File lib/sequel/model/base.rb
1965 def _valid?(opts)
1966   return errors.empty? if frozen?
1967   errors.clear
1968   called = false
1969   skip_validate = opts[:validate] == false
1970   around_validation do
1971     called = true
1972     before_validation
1973     validate unless skip_validate
1974     after_validation
1975   end
1976 
1977   return true if skip_validate
1978 
1979   if called
1980     errors.empty?
1981   else
1982     raise_hook_failure(:around_validation)
1983   end
1984 end

change_column_value(column, value) click to toggle source

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

     # File lib/sequel/model/base.rb
2008 def change_column_value(column, value)
2009   _add_changed_column(column)
2010   @values[column] = value
2011 end

checked_save_failure(opts) { || ... } click to toggle source

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

     # File lib/sequel/model/base.rb
1988 def checked_save_failure(opts)
1989   if raise_on_failure?(opts)
1990     yield
1991   else
1992     begin
1993       yield
1994     rescue HookFailed 
1995       nil
1996     end
1997   end
1998 end

checked_transaction(opts=OPTS, &block) click to toggle source

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

     # File lib/sequel/model/base.rb
2001 def checked_transaction(opts=OPTS, &block)
2002   h = {:server=>this_server}.merge!(opts)
2003   h[:skip_transaction] = true unless use_transaction?(opts)
2004   db.transaction(h, &block)
2005 end

errors_class() click to toggle source

Default error class used for errors.

     # File lib/sequel/model/base.rb
2014 def errors_class
2015   Errors
2016 end

hook_failed_error(msg) click to toggle source

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

     # File lib/sequel/model/base.rb
2019 def hook_failed_error(msg)
2020   HookFailed.new(msg, self)
2021 end

initialize_clone(other) click to toggle source

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

Calls superclass method

     # File lib/sequel/model/base.rb
2025 def initialize_clone(other)
2026   super
2027   freeze if other.frozen?
2028   self
2029 end

initialize_copy(other) click to toggle source

Copy constructor – Duplicate internal data structures.

Calls superclass method

     # File lib/sequel/model/base.rb
2032 def initialize_copy(other)
2033   super
2034   @values = Hash[@values]
2035   @changed_columns = @changed_columns.dup if @changed_columns
2036   @errors = @errors.dup if @errors
2037   self
2038 end

initialize_set(h) click to toggle source

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.

     # File lib/sequel/model/base.rb
2043 def initialize_set(h)
2044   set(h) unless h.empty?
2045 end

inspect_prefix() click to toggle source

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

     # File lib/sequel/model/base.rb
2048 def inspect_prefix
2049   model.name
2050 end

inspect_values() click to toggle source

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

     # File lib/sequel/model/base.rb
2053 def inspect_values
2054   @values.inspect
2055 end

raise_hook_failure(type=nil) click to toggle source

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

     # File lib/sequel/model/base.rb
2067 def raise_hook_failure(type=nil)
2068   msg = case type
2069   when String
2070     type
2071   when Symbol
2072     "the #{type} hook failed"
2073   else
2074     "a hook failed"
2075   end
2076 
2077   raise hook_failed_error(msg)
2078 end

raise_on_failure?(opts) click to toggle source

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).

     # File lib/sequel/model/base.rb
2061 def raise_on_failure?(opts)
2062   opts.fetch(:raise_on_failure, raise_on_save_failure)
2063 end

schema_type_class(column) click to toggle source

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

     # File lib/sequel/model/base.rb
2081 def schema_type_class(column)
2082   if (sch = db_schema[column]) && (type = sch[:type])
2083     db.schema_type_class(type)
2084   end
2085 end

set_restricted(hash, type) click to toggle source

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

     # File lib/sequel/model/base.rb
2089 def set_restricted(hash, type)
2090   return self if hash.empty?
2091   meths = setter_methods(type)
2092   strict = strict_param_setting
2093   hash.each do |k,v|
2094     k = k.to_s
2095     m = "#{k}="
2096     if meths.include?(m)
2097       set_column_value(m, v)
2098     elsif strict
2099       # Avoid using respond_to? or creating symbols from user input
2100       if public_methods.map(&:to_s).include?(m)
2101         if Array(model.primary_key).map(&:to_s).member?(k) && model.restrict_primary_key?
2102           raise MassAssignmentRestriction.create("#{k} is a restricted primary key", self, k)
2103         else
2104           raise MassAssignmentRestriction.create("#{k} is a restricted column", self, k)
2105         end
2106       else
2107         raise MassAssignmentRestriction.create("method #{m} doesn't exist", self, k)
2108       end
2109     end
2110   end
2111   self
2112 end

setter_methods(type) click to toggle source

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.

     # File lib/sequel/model/base.rb
2120 def setter_methods(type)
2121   if type == :default && !@singleton_setter_added
2122     return model.setter_methods
2123   end
2124 
2125   meths = methods.map(&:to_s).select{|l| l.end_with?('=')} - RESTRICTED_SETTER_METHODS
2126   meths -= Array(primary_key).map{|x| "#{x}="} if primary_key && model.restrict_primary_key?
2127   meths
2128 end

this_server() click to toggle source

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

     # File lib/sequel/model/base.rb
2132 def this_server
2133   if (s = @server)
2134     s
2135   elsif (t = @this)
2136     t.opts[:server] || :default
2137   else
2138     model.dataset.opts[:server] || :default
2139   end
2140 end

typecast_value(column, value) click to toggle source

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.

     # File lib/sequel/model/base.rb
2145 def typecast_value(column, value)
2146   return value unless typecast_on_assignment && db_schema && (col_schema = db_schema[column])
2147   value = nil if '' == value and typecast_empty_string_to_nil and col_schema[:type] and ![:string, :blob].include?(col_schema[:type])
2148   raise(InvalidValue, "nil/NULL is not allowed for the #{column} column") if raise_on_typecast_failure && value.nil? && (col_schema[:allow_null] == false)
2149   begin
2150     model.db.typecast_value(col_schema[:type], value)
2151   rescue InvalidValue
2152     raise_on_typecast_failure ? raise : value
2153   end
2154 end

update_restricted(hash, type) click to toggle source

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

     # File lib/sequel/model/base.rb
2157 def update_restricted(hash, type)
2158   set_restricted(hash, type)
2159   save_changes
2160 end

use_server(ds) click to toggle source

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

     # File lib/sequel/model/base.rb
2163 def use_server(ds)
2164   @server ? ds.server(@server) : ds
2165 end

use_transaction?(opts = OPTS) click to toggle source

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).

     # File lib/sequel/model/base.rb
2170 def use_transaction?(opts = OPTS)
2171   opts.fetch(:transaction, use_transactions)
2172 end

validation_failed_error() click to toggle source

An ValidationFailed exception instance to raise for this instance.

     # File lib/sequel/model/base.rb
2175 def validation_failed_error
2176   ValidationFailed.new(self)
2177 end