keayl

ORM::ActiveRecord

Every page of the ORM::ActiveRecord manual, in reading order.

  • Overview The latest version of this documentation lives at https://gdonald.github.io/ORM-ActiveRecord/.
  • Conventions ORM::ActiveRecord follows a small set of naming conventions. Once you know the two rules Raku imposes on method names, the rest of the API reads the way...
  • Adapters ORM::ActiveRecord supports three database backends: PostgreSQL, MySQL, and SQLite. Tests run against all three on every CI build. Application code is the...
  • Migrations ORM::ActiveRecord includes commands to migrate your database. Migrations include adding and removing tables as well as adding and removing columns and...
  • Generators active-record generate scaffolds the files you would otherwise hand-write, and active-record destroy removes what a matching generate produced. Both take...
  • Database tasks The active-record db:* tasks manage the database lifecycle: creating and dropping it, running and inspecting migrations, and seeding. They act on the...
  • Runtime tasks The active-record runtime subcommands run code against the app, open a database client, and report on the source tree.
  • Info ORM::ActiveRecord supports model relationships, the layer of your app that is responsible for managing data and business logic.
  • Attribute types On top of the adapter's column-type coercion, models can declare a per-attribute type — a small casting layer that converts values at three points:
  • Enums An enum maps a column's stored value to a set of symbolic names. The column holds the backing value (an integer or a string); the model works in terms of...
  • Normalisation normalizes declares a transform applied to an attribute before validation and save, so the stored value is always canonical. Declare it in submethod BUILD.
  • Serialization A small family of methods that answer "how do I identify this record?" and "how do I turn it into a hash/string?" — used for URL helpers, cache keys, JSON...
  • Inheritance Single-table inheritance (STI) stores a whole class hierarchy in one table. A base model owns the table; subclasses share it. A row's type column records...
  • Finders ORM::ActiveRecord provides a range of class-level finder methods for locating records.
  • Relations User.where(...), User.order(...), and friends return a chainable relation that defers running SQL until you ask for results. Relations compose: every...
  • Queries This page covers the filtering and relation-modification vocabulary that builds on the basics in Relations. Everything here returns a new relation — the...
  • Joins joins and left-outer-joins add SQL JOIN clauses to a relation. They accept several forms:
  • Aggregation Beyond filtering, relations expose set-shaping operations: deduplication, grouping, subquery sources, and per-relation flags.
  • Batching Loading every row of a large table at once is expensive. The batching methods walk the table in fixed-size chunks, keyed off the primary key, so memory...
  • Async queries Every read method has an -async variant that runs the query on a worker thread and returns a Raku Promise. await it (or call .result) when you need the...
  • Raw SQL & CTEs When the chainable relation DSL is not enough, ORM::ActiveRecord exposes a handful of escape hatches that let you reach for raw SQL or Common Table...
  • Inspection A small family of methods for asking *about* a relation rather than running it. They live on both Model (where they apply to Model.all) and on a Query...
  • Persistence ORM::ActiveRecord exposes both quiet (return False on failure) and loud (raise an exception on failure) variants of the persistence methods. Use whichever...
  • Callbacks ORM::ActiveRecord supports callbacks that can be performed during various life cycle events.
  • Transactions ORM::ActiveRecord exposes transactions through a block helper that opens a SQL transaction, runs the block, and commits if the block returns normally. If...
  • Soft deletes soft-deletes turns destruction into a reversible flag. Instead of issuing a DELETE, a discarded record stamps a timestamp column and stays in the table,...
  • Data ORM::ActiveRecord supports many forms of data validations, when they occur and if they occur at all.
  • Conditionals Validations can be made conditional based on some other method call or criteria. The available conditionals are if, unless, and on. With on a create or...
  • Options Beyond the per-validator settings (min:, max:, with:, etc.) every validator accepts a small set of shared options that change *when* the validator runs or...
  • Messages & locales Validation messages are templates. When a validator fails it renders a template into a string, substituting tokens drawn from the record and the validator...
  • Tokens & secure data Helpers for passwords, random tokens, and signed ids. Declare them in submethod BUILD. Signed ids and purpose tokens need a signing secret:
  • Encryption encrypts stores a column's value encrypted at rest. Declare it in submethod BUILD. Encryption needs at least one key:
  • Through associations A :through association reaches a second model by way of a join model. A user subscribes to magazines through subscriptions; the subscription is a real...
  • Polymorphic associations A polymorphic belongs-to can point at more than one kind of parent. A picture is imageable — it might belong to a user or to a post. The row stores both...
  • Single-table inheritance One table holds several related classes, told apart by a type column. A Vehicle table stores cars and motorcycles; each row remembers which class it is...
  • Custom validators When the built-in validators don't fit, write your own. There are two shapes: a validator class for reusable rules, and an inline block for one-off...
  • Transactions and savepoints Wrap a unit of work in a transaction so it commits all-or-nothing. Nested transactions become savepoints, so an inner failure can be contained without...
  • Eager loading Accessing an association in a loop runs one query per record — the N+1 problem. Eager loading fixes it by fetching the associations up front. Three...
  • Errors ORM::ActiveRecord exposes two complementary error surfaces:
  • Reflection Public class-level introspection so tools (a console, a serializer, a factory) can build, stub, and describe records without reaching into model...
  • Logging ORM::ActiveRecord uses Log::Async. Loading the library configures the INFO-level handler to write to $*OUT (stdout). That is the only log destination set...
  • Instrumentation ORM::ActiveRecord publishes events as it works: every query, every model load, and every transaction. Subscribe to those events to time queries, trace...
  • Tests The suite has two halves: the prove6 tests under t/ and the behave specs under specs/. Both run against PostgreSQL, MySQL, and SQLite.
  • Test helpers Three helpers under ORM::ActiveRecord::Testing keep test data isolated and easy to set up: a transactional wrapper, a YAML fixture loader, and a database...