active_record.cr

A Crystal port of Rails ActiveRecord 8.1.4 for PostgreSQL — models, Relation querying, validations, callbacks, associations, transactions, migrations, schema dumping, STI, enums/stores and ActiveRecord::Encryption. Namespace ActiveRecord mirrors the original 1:1. Status: 283/283 oracle specs green (crud/dirty/callbacks/validations/associations/ transactions/persistence/proxy, through + polymorphic + HABTM + counter_cache/touch/inverse_of, includes/preload/eager_load, optimistic locking, STI, enum/store/alias_attribute/attr_readonly/cache_key/ has_secure_token, nested attributes, serialize, autosave), plus migrations, db/schema.cr dump (byte-identical to the schema.rb oracle) and encryption.

⚠️ EXPERIMENTAL FRAMEWORK, DO NOT USE IN PRODUCTION YET.

How it works

1. bin/ar_schema_dump dumps the DB schema to db/schema.yml (columns/types/nullability) — input for compile-time codegen.
2. A model class < ActiveRecord::Base registers itself at compile time (macro inherited); at the end of the program a {{ run(...) }} runner reads db/schema.yml (env CRAILS_SCHEMA) and generates attributes, the row mapper, initialize(**attrs), attributes/[]/inspect/reload!. Ruby's runtime define_method becomes compile-time code generation — this is the key mechanism of the whole port.
3. PostgreSQL → Crystal type mapping: int* → Int64, float8 → Float64, numeric → PG::Numeric, timestamp* → Time, json/jsonb → JSON::Any, bytea → Bytes, arrays → Array(...). Caveat: columns named after Crystal keywords (until) get getters/ setters but are excluded from new(**kwargs).

Quick start

shards install

# 1) dump the DB schema to db/schema.yml (needed for codegen)
DATABASE_URL='postgres://root@/data_lake_development?host=/var/run/postgresql' \
  bin/ar_schema_dump

# 2) demo read
crystal run examples/datalake_read.cr

Feature comparison vs activerecord 8.1.4

Connections & schema

Relation / querying

Validations

Callbacks

Associations

Persistence & dirty

Transactions & locking

Migrations & schema

Enums, stores, STI, misc

Encryption (phase G)

Deviations & Crystal-specific notes

• No method_missing, no runtime Symbols, no constantize, static typing — these power most ❌ rows above; equivalents are compile-time registries and codegen.
• Nilable finders cannot be unwrapped into a chain; persistence methods accept Hash, not keywords; virtual attributes via direct setters (details in the linked SEMANTICS doc of the umbrella project).
• Class variables are not shared with subclasses — state is accessed via explicit Base. receivers; transactions pin a connection to the fiber.

Testing

# fixture DB crails_ar_test + datalake read-only
psql -h /var/run/postgresql -U root -d postgres -c 'create database crails_ar_test owner root'
psql -h /var/run/postgresql -U root -d crails_ar_test -f spec/fixtures/seed.sql
crystal spec

Oracle-first development: oracle/cases.rb + oracle/migrations.rb / oracle/schema.rb are recorded against real activerecord 8.1.4; mirror specs in spec/oracle_spec.cr / spec/migrations_spec.cr / spec/schema_spec.cr reproduce the expected files without editing the cases. Encryption parity: 26 Ruby cases + a reverse check where the real gem decrypts port ciphertexts (oracle/verify_encryption.rb).