module

PgORM::Associations

Macros

__process_assoc_serialization__
Source
belongs_to(name, class_name = nil, foreign_key = nil, autosave = nil, dependent = nil)

Declares a belongs to relationship.

The foreign key attribute is not declared by this macro and must be declared on the model (e.g. attribute author_id : Int64?).

This will add the following methods:

  • association returns the associated object (raises ::PgORM::Error::RecordNotFound if it doesn't exist);
  • association? returns the associated object, or nil if it doesn't exist;
  • association= assigns the associated object, assigning the foreign key if the object is persisted;
  • build_association builds the associated object, assigning the foreign key if the parent record is persisted, or delaying it to when the new record is saved;
  • create_association creates the associated object with create, assigning the foreign key;
  • create_association! same as create_association but uses create!. Both raise ::PgORM::Error::RecordInvalid when validation fails;
  • reload_association to reload the associated object.

For example a Book class declares belongs_to :author which will add:

  • Book#author (similar to Author.find(author_id))
  • Book#author=(author) (similar to book.author_id = author.id)
  • Book#build_author (similar to book.author = Author.new)
  • Book#create_author (similar to book.author = Author.create)
  • Book#create_author! (similar to book.author = Author.create!)
  • Book#reload_author (force reload book.author)

Options

  • class_name overrides the association class name (inferred as name.camelcase by default);
  • foreign_key overrides the foreign key on the association (inferred as name + "_id" by default);
  • autosave can be either:
    • nil (default) to only save newly built associations when the parent record is saved,
    • true to always save the associations (new or already persisted),
    • false to never save the associations automatically.
  • dependent can be either:
    • nil (default) to do nothing,
    • :delete to delete the associated record in SQL,
    • :destroy to call #destroy on the associated object.
Source
has_many(name, class_name = nil, foreign_key = nil, autosave = nil, dependent = nil, serialize = false)

Declares a has many relationship.

Adds an association method returning a ::PgORM::Relation of the associated records. The foreign key attribute is not declared by this macro and must be declared on the associated model.

Options

  • class_name overrides the association class name (inferred as name with a trailing "s" removed, camelcased, by default);
  • foreign_key overrides the foreign key for the association (inferred as the name of this class with a trailing "s" removed, underscored, + "_id" by default);
  • autosave can be either:
    • nil (default) to only save newly built associations when the parent record is saved,
    • true to always save loaded or built associations,
    • false to never save the associations automatically.
  • dependent can be either:
    • nil (default) to do nothing,
    • :nullify to set the foreign key to nil in SQL,
    • :delete_all to delete the associated records in SQL,
    • :destroy to call #destroy on each associated object.
  • serialize when true includes the associated records in to_json when they have been loaded (e.g. by a join or by iterating the relation).
Source
has_one(name, class_name = nil, foreign_key = nil, autosave = nil, dependent = nil)

Declares a has one relationship.

The foreign key attribute is not declared by this macro and must be declared on the associated model.

This will add the following methods:

  • association returns the associated object (raises ::PgORM::Error::RecordNotFound if it doesn't exist);
  • association? returns the associated object, or nil if it doesn't exist;
  • association= assigns the associated object. If this record is persisted, the previously associated record is deleted (dependent: :delete), destroyed (dependent: :destroy) or otherwise has its foreign key set to nil, then the new object's foreign key is assigned and it is saved;
  • build_association builds the associated object, assigning its foreign key if this record is persisted;
  • create_association and create_association! build and save the associated object, raising ::PgORM::Error::RecordInvalid when validation fails, like create. Both raise ::PgORM::Error::RecordNotSaved if this record has no id;
  • reload_association to reload the associated object.

For example an Account class declares has_one :supplier which will add:

  • Account#supplier (similar to Supplier.find_by(account_id: account.id))
  • Account#supplier=(supplier) (similar to supplier.account_id = account.id)
  • Account#build_supplier
  • Account#create_supplier
  • Account#create_supplier!
  • Account#reload_supplier

Options

  • class_name overrides the association class name (inferred as name.camelcase by default);
  • foreign_key overrides the foreign key for the association (inferred as the name of this class + "_id" by default);
  • autosave can be either:
    • nil (default) to only save newly built associations when the parent record is saved,
    • true to always save the associations (new or already persisted),
    • false to never save the associations automatically.
  • dependent can be either:
    • nil (default) to do nothing,
    • :nullify to set the foreign key to nil in SQL,
    • :delete to delete the associated record in SQL,
    • :destroy to call #destroy on the associated object.
Source