The Cql::Record
module in the CQL toolkit is a crucial part of the Object-Relational Mapping (ORM) system in Crystal. It allows you to define models that map to tables in your database and provides a wide array of functionalities for querying, inserting, updating, and deleting records. In this guide, we'll explore how the Cql::Record
module works and how to use it effectively.
Record
Module?The Cql::Record
module is a mixin that provides your Crystal structs with the ability to interact with database tables, treating them as Active Record-style models. This means that each model represents a table in your database, and each instance of that model represents a row within that table.
To start working with CQL models, you first need to define your database schema and map models (Crystal structs) to tables within that schema.
Let's assume we have two tables: posts
and comments
. Each post can have many comments, and each comment belongs to one post.
posts table: Contains columns id
, title
, body
, and published_at
.
comments table: Contains columns id
, post_id
(foreign key), and body
.
Record
Now, let's define the Post
and Comment
models that map to the posts
and comments
tables.
Record
ModuleThe Cql::Record
module adds several useful methods and features to your model:
1. Defining Models with define
Each model must be linked to a schema and a table using the define
method.
This associates the Post
struct with the posts
table in the AcmeDB
schema.
The Record
module provides convenient methods for querying the database.
Fetching All Records:
This retrieves all the records from the posts
table.
Fetching a Record by ID:
This retrieves the post with ID 1
. If the record is not found, nil
is returned.
Fetching the First or Last Record:
These methods fetch the first and last records in the table, respectively.
Fetching Records with Conditions:
These methods allow you to filter records by specific fields.
You can create new records using the create
method.
This creates a new post and returns the id
of the newly created record.
You can update existing records by passing the record’s id
and the fields to update.
This updates the post with ID 1
to have the new title "Updated Post Title".
To delete records, you can use the delete
method:
This deletes the post with ID 1
.
The Record
module also allows you to define associations between models. In our example, we defined a belongs_to
relationship in the Comment
model:
This means that each comment is associated with one post.
You can also define other associations like has_many
and has_one
:
This would go into the Post
model to define that each post can have multiple comments.
The Record
module also provides instance-level methods for interacting with individual records:
To insert a new record into the database or update an existing one, you can use the save
method:
If the record has an id
, it will update the record. Otherwise, it will create a new record.
You can also update specific fields on an existing record using the update
method:
To delete a record from the database:
This deletes the current record.
You can reload the current state of the record from the database using reload!
:
This updates the attributes of the record with the latest values from the database.
You can access and manipulate the record’s attributes using the attributes
method:
You can also set the attributes:
Let's combine everything we've learned to build a simple blog system where posts can have many comments.
Creating a Post:
Adding Comments to the Post:
Fetching Comments for a Post:
The Cql::Record
module provides powerful tools for working with database records in a Crystal application. It simplifies the process of defining models, querying records, and managing associations. By leveraging the capabilities of CQL's Active Record-style ORM, you can build complex applications with ease.
With Cql::Record
, you have access to:
Easy schema and model definition.
A rich set of query and manipulation methods.
Powerful association handling (belongs_to
, has_many
,