Class: ROM::Schema

Inherits:
Object
  • Object
show all
Extended by:
Initializer, Notifications::Listener
Includes:
Enumerable, Memoizable
Defined in:
lib/rom/schema.rb,
lib/rom/schema/dsl.rb,
lib/rom/schema/inferrer.rb,
lib/rom/schema/associations_dsl.rb

Overview

Relation schema

Schemas hold detailed information about relation tuples, including their primitive types (String, Integer, Hash, etc. or custom classes), as well as various meta information like primary/foreign key and literally any other information that a given database adapter may need.

Adapters can extend this class and it can be used in adapter-specific relations. In example rom-sql extends schema with Association DSL and many additional SQL-specific APIs in schema types.

Schemas are used for projecting canonical relations into other relations and every relation object maintains its schema. This means that we always have all information about relation tuples, even when a relation was projected and diverged from its canonical form.

Furthermore schema attributes know their source relations, which makes it possible to merge schemas from multiple relations and maintain information about the source relations. In example when two relations are joined, their schemas are merged, and we know which attributes belong to which relation.

rubocop:disable Metrics/ClassLength

Direct Known Subclasses

Memory::Schema

Defined Under Namespace

Classes: AssociationsDSL, DSL, Inferrer

Constant Summary collapse

EMPTY_ASSOCIATION_SET = 
AssociationSet.build(EMPTY_HASH).freeze
DEFAULT_INFERRER = 
Inferrer.new(enabled: false).freeze
HASH_SCHEMA = 
Types::Coercible::Hash
.schema(EMPTY_HASH)
.with_type_transform(type_transformation)

Constants included from Memoizable

Memoizable::MEMOIZED_HASH

Instance Attribute Summary collapse

Attributes included from Memoizable

#__memoized__

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Notifications::Listener

subscribe

Methods included from Initializer

extended

Methods included from Memoizable

included

Constructor Details

#initialize {|_self| ... } ⇒ Schema

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Schema.

Yields:

  • (_self)

Yield Parameters:

  • _self (ROM::Schema) —

    the object that the method was called on



164
165
166
167
168
 
# File 'lib/rom/schema.rb', line 164

def initialize(*, **)
  super

  yield(self) if block_given?
end

Instance Attribute Details

#associations ⇒ AssociationSet (readonly)

Returns Optional association set (this is adapter-specific).

Returns:

  • (AssociationSet) —

    Optional association set (this is adapter-specific)



94
 
# File 'lib/rom/schema.rb', line 94

option :associations, default: -> { EMPTY_ASSOCIATION_SET }

#attributes ⇒ Array (readonly)

Returns Array with schema attributes.

Returns:

  • (Array) —

    Array with schema attributes



90
 
# File 'lib/rom/schema.rb', line 90

option :attributes, default: -> { EMPTY_ARRAY }

#canonical ⇒ Symbol (readonly)

Returns The canonical schema which is carried in all schema instances.

Returns:

  • (Symbol) —

    The canonical schema which is carried in all schema instances



105
 
# File 'lib/rom/schema.rb', line 105

option :canonical, default: -> { self }

#inferrer ⇒ #call (readonly)

Returns An optional inferrer object used in ‘finalize!`.

Returns:

  • (#call) —

    An optional inferrer object used in ‘finalize!`



98
 
# File 'lib/rom/schema.rb', line 98

option :inferrer, default: -> { DEFAULT_INFERRER }

#name ⇒ Symbol (readonly)

Returns The name of this schema.

Returns:

  • (Symbol) —

    The name of this schema



86
 
# File 'lib/rom/schema.rb', line 86

param :name

#primary_key_name ⇒ Symbol (readonly)

Returns The name of the primary key. This is set because in most of the cases relations don’t have composite pks.

Returns:

  • (Symbol) —

    The name of the primary key. This is set because in most of the cases relations don’t have composite pks



113
 
# File 'lib/rom/schema.rb', line 113

option :primary_key_name, optional: true

#primary_key_names ⇒ Array<Symbol> (readonly)

Returns A list of all pk names.

Returns:

  • (Array<Symbol>) —

    A list of all pk names



117
 
# File 'lib/rom/schema.rb', line 117

option :primary_key_names, optional: true

Class Method Details

.attributes(attributes, attr_class) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



157
158
159
160
161
 
# File 'lib/rom/schema.rb', line 157

def self.attributes(attributes, attr_class)
  attributes.map do |attr|
    attr_class.new(attr[:type], **attr.fetch(:options))
  end
end

.build_attribute_info(type, **options) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds a representation of the information needed to create an attribute.

This representation is consumed by ‘Schema.define` in order to create the actual attributes.

Returns:

  • (Hash) —

    A hash with ‘:type` and `:options` keys.



149
150
151
152
153
154
 
# File 'lib/rom/schema.rb', line 149

def self.build_attribute_info(type, **options)
  {
    type: type,
    options: options
  }
end

.define(name, attributes: EMPTY_ARRAY, attr_class: Attribute, **options) ⇒ Schema

Define a relation schema from plain rom types and optional options

Resulting schema will decorate plain rom types with adapter-specific types By default ‘Attribute` will be used

Parameters:

  • name (Relation::Name, Symbol) —

    The schema name, typically ROM::Relation::Name

Returns:



131
132
133
134
135
136
137
138
 
# File 'lib/rom/schema.rb', line 131

def self.define(name, attributes: EMPTY_ARRAY, attr_class: Attribute, **options)
  new(
    name,
    attr_class: attr_class,
    attributes: attributes(attributes, attr_class),
    **options
  ) { |schema| yield(schema) if block_given? }
end

Instance Method Details

#[](key, src = name.to_sym) ⇒ Object

Return attribute

Parameters:

  • key (Symbol) —

    The attribute name

  • src (Symbol, Relation::Name) (defaults to: name.to_sym) —

    The source relation (for merged schemas)

Raises:

  • KeyError



220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/rom/schema.rb', line 220

def [](key, src = name.to_sym)
  attr =
    if count_index[key].equal?(1)
      name_index[key]
    else
      source_index[src][key]
    end

  raise(KeyError, "#{key.inspect} attribute doesn't exist in #{src} schema") unless attr

  attr
end

#append(*new_attributes) ⇒ Schema

Append more attributes to the schema

This returns a new schema instance

Parameters:

Returns:



329
330
331
 
# File 'lib/rom/schema.rb', line 329

def append(*new_attributes)
  new(attributes + new_attributes)
end

#call(relation) ⇒ Relation

Abstract method for creating a new relation based on schema definition

This can be used by views to generate a new relation automatically. In example a schema can project a relation, join any additional relations if it includes attributes from other relations etc.

Default implementation is a no-op and it simply returns back untouched relation

Parameters:

Returns:



183
 
# File 'lib/rom/schema.rb', line 183

def call(relation) = relation

#canonical? ⇒ Boolean

Return if a schema is canonical

Returns:

  • (Boolean) 


362
 
# File 'lib/rom/schema.rb', line 362

def canonical? = equal?(canonical)

#each {|Attribute| ... } ⇒ Object

Iterate over schema’s attributes

Yields:



190
 
# File 'lib/rom/schema.rb', line 190

def each(&) = attributes.each(&)

#empty? ⇒ TrueClass, FalseClass

Check if schema has any attributes

Returns:

  • (TrueClass, FalseClass) 


197
 
# File 'lib/rom/schema.rb', line 197

def empty? = attributes.empty?

#exclude(*names) ⇒ Schema

Exclude provided attributes from a schema

Parameters:

  • names (*Array) —

    Attribute names

Returns:



251
 
# File 'lib/rom/schema.rb', line 251

def exclude(*names) = project(*(map(&:name) - names))

#finalize!(**_opts) ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Finalize a schema

Returns:

  • (self) 


369
370
371
372
373
 
# File 'lib/rom/schema.rb', line 369

def finalize!(**_opts)
  return self if frozen?

  freeze
end

#finalize_associations! ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Finalize associations defined in a schema

Parameters:

Returns:

  • (self) 


400
401
402
403
 
# File 'lib/rom/schema.rb', line 400

def finalize_associations!(**)
  set!(:associations, yield) if associations.any?
  self
end

#finalize_attributes!(gateway: nil) ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This hook is called when relation is being build during container finalization

When block is provided it’ll be called just before freezing the instance so that additional ivars can be set

Returns:

  • (self) 


383
384
385
386
387
388
389
390
391
 
# File 'lib/rom/schema.rb', line 383

def finalize_attributes!(gateway: nil, **)
  inferrer.(self, gateway).each { |key, value| set!(key, value) }

  yield if block_given?

  initialize_primary_key_names

  self
end

#foreign_key(relation) ⇒ Attribute

Return FK attribute for a given relation name

Returns:



299
300
301
 
# File 'lib/rom/schema.rb', line 299

def foreign_key(relation)
  detect { |attr| attr.foreign_key? && attr.target == relation }
end

#key?(name) ⇒ Boolean

Return if a schema includes an attribute with the given name

Parameters:

  • name (Symbol) —

    The name of the attribute

Returns:

  • (Boolean) 


353
354
355
 
# File 'lib/rom/schema.rb', line 353

def key?(name)
  !attributes.detect { |attr| attr.name == name }.nil?
end

#merge(other) ⇒ Schema Also known as: +

Merge with another schema

Parameters:

  • other (Schema) —

    Other schema

Returns:



317
 
# File 'lib/rom/schema.rb', line 317

def merge(other) = append(*other)

#prefix(prefix) ⇒ Schema

Project a schema with renamed attributes using provided prefix

Parameters:

  • prefix (Symbol) —

    The name of the prefix

Returns:



276
277
278
 
# File 'lib/rom/schema.rb', line 276

def prefix(prefix)
  new(map { |attr| attr.prefixed(prefix) })
end

#primary_key ⇒ Array<Attribute>

Return primary key attributes

Returns:



308
 
# File 'lib/rom/schema.rb', line 308

def primary_key = select(&:primary_key?)

#project(*names) ⇒ Schema

Project a schema to include only specified attributes

Parameters:

  • names (*Array<Symbol, Attribute>) —

    Attribute names

Returns:



240
241
242
 
# File 'lib/rom/schema.rb', line 240

def project(*names)
  new(names.map { |name| name.is_a?(Symbol) ? self[name] : name })
end

#rename(mapping) ⇒ Schema

Project a schema with renamed attributes

Parameters:

  • mapping (Hash) —

    The attribute mappings

Returns:



260
261
262
263
264
265
266
267
 
# File 'lib/rom/schema.rb', line 260

def rename(mapping)
  new_attributes = map do |attr|
    alias_name = mapping[attr.name]
    alias_name ? attr.aliased(alias_name) : attr
  end

  new(new_attributes)
end

#set!(key, value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



440
441
442
443
 
# File 'lib/rom/schema.rb', line 440

def set!(key, value)
  instance_variable_set("@#{key}", value)
  options[key] = value
end

#to_ary ⇒ Array

Returns Array with schema attributes.

Returns:

  • (Array) —

    Array with schema attributes



119
 
# File 'lib/rom/schema.rb', line 119

option :attributes, default: -> { EMPTY_ARRAY }

#to_ast ⇒ Array

Return AST for the schema

Returns:

  • (Array) 


437
 
# File 'lib/rom/schema.rb', line 437

def to_ast = [:schema, [name, attributes.map(&:to_ast)]]

#to_h ⇒ Hash

Coerce schema into a <AttributeName=>Attribute> Hash

Returns:

  • (Hash) 


204
205
206
207
208
209
210
 
# File 'lib/rom/schema.rb', line 204

def to_h
  if block_given?
    super
  else
    super { [_1.name, _1] }
  end
end

#to_input_hash ⇒ Dry::Types::Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return coercion function using attribute types

This is used for ‘input_schema` in relations, typically commands use it for processing input

Returns:

  • (Dry::Types::Hash) 


426
427
428
429
430
 
# File 'lib/rom/schema.rb', line 426

def to_input_hash
  HASH_SCHEMA.schema(
    to_h { |attr| [attr.name, attr.to_write_type] }
  )
end

#to_output_hash ⇒ Dry::Types::Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return coercion function using attribute read types

This is used for ‘output_schema` in relations

Returns:

  • (Dry::Types::Hash) 


412
413
414
415
416
 
# File 'lib/rom/schema.rb', line 412

def to_output_hash
  HASH_SCHEMA.schema(
    to_h { |attr| [attr.key, attr.to_read_type] }
  )
end

#uniq ⇒ Schema

Return a new schema with uniq attributes

Returns:



338
339
340
341
342
343
344
 
# File 'lib/rom/schema.rb', line 338

def uniq(&)
  if block_given?
    new(attributes.uniq(&))
  else
    new(attributes.uniq(&:name))
  end
end

#wrap(prefix = name.dataset) ⇒ Schema

Return new schema with all attributes marked as prefixed and wrapped

This is useful when relations are joined and the right side should be marked as wrapped

Parameters:

  • prefix (Symbol) (defaults to: name.dataset) —

    The prefix used for aliasing wrapped attributes

Returns:



290
291
292
 
# File 'lib/rom/schema.rb', line 290

def wrap(prefix = name.dataset)
  new(map { |attr| attr.wrapped? ? attr : attr.wrapped(prefix) })
end