Module: Sequel::Plugins::Serialization

Defined in:
lib/sequel/plugins/serialization.rb

Overview

Sequel’s built in Serialization plugin allows you to keep serialized ruby objects in the database, while giving you deserialized objects when you call an accessor.

This plugin works by keeping the serialized value in the values, and adding a @deserialized_values hash. The reader method for serialized columns will check the @deserialized_values for the value, return it if present, or deserialized the entry in @values and return it. The writer method will set the @deserialized_values entry. This plugin adds a before_save hook that serializes all @deserialized_values to @values.

You can specify the serialization format as a pair of serializer/deserializer callable objects. You can also specify the serialization format as a single symbol, if such a symbol has a registered serializer/deserializer pair in the plugin. By default, the plugin registers the :marshal, :yaml, and :json serialization formats. To register your own serialization formats, use Sequel::Plugins::Serialization.register_format. If you use yaml or json format, you need to require the libraries, Sequel does not do the requiring for you.

You can specify the columns to serialize when loading the plugin, or later using the serialize_attributes class method.

Because of how this plugin works, it must be used inside each model class that needs serialization, after any set_dataset method calls in that class. Otherwise, it is possible that the default column accessors will take precedence.

Example

# Require json if you plan to use it, as the plugin doesn't require it for you.
require 'json'

# Register custom serializer/deserializer pair, if desired
require 'sequel/plugins/serialization'
Sequel::Plugins::Serialization.register_format(:reverse,
  lambda(&:reverse),
  lambda(&:reverse))

class User < Sequel::Model
  # Built-in format support when loading the plugin
  plugin :serialization, :json, :permissions

  # Built-in format support after loading the plugin using serialize_attributes
  plugin :serialization
  serialize_attributes :marshal, :permissions

  # Use custom registered serialization format just like built-in format
  serialize_attributes :reverse, :password

  # Use a custom serializer/deserializer pair without registering
  serialize_attributes [lambda(&:reverse), lambda(&:reverse)], :password
end
user = User.create
user.permissions = { :global => 'read-only' }
user.save

Note that if you mutate serialized column values without reassigning them, those changes won’t be picked up by Model#save_changes or Model#update. Example:

user = User[1]
user.permissions[:global] = 'foo'
user.save_changes # Will not pick up changes to permissions

You can use the serialization_modification_detection plugin to pick up such changes.

Defined Under Namespace

Modules: ClassMethods, InstanceMethods

Constant Summary collapse

REGISTERED_FORMATS =

The default serializers supported by the serialization module. Use register_format to add serializers to this hash.

{}

Class Method Summary collapse

Class Method Details

.apply(model, *args) ⇒ Object

Set up the column readers to do deserialization and the column writers to save the value in deserialized_values.



77
78
79
80
81
82
 
# File 'lib/sequel/plugins/serialization.rb', line 77

def self.apply(model, *args)
  model.instance_eval do
    @deserialization_map = {}
    @serialization_map = {}
  end
end

.configure(model, format = nil, *columns) ⇒ Object

Automatically call serialize_attributes with the format and columns unless no columns were provided.



86
87
88
 
# File 'lib/sequel/plugins/serialization.rb', line 86

def self.configure(model, format=nil, *columns)
  model.serialize_attributes(format, *columns) unless columns.empty?
end

.register_format(format, serializer, deserializer) ⇒ Object

Register a serializer/deserializer pair with a format symbol, to allow models to pick this format by name. Both serializer and deserializer should be callable objects.



93
94
95
 
# File 'lib/sequel/plugins/serialization.rb', line 93

def self.register_format(format, serializer, deserializer)
  REGISTERED_FORMATS[format] = [serializer, deserializer]
end