CQL Documentation

A high-performance, type-safe ORM for Crystal applications.

Build fast, reliable database applications with compile-time safety and exceptional performance.

Quick Navigation

I want to...	Go to...
Learn CQL from scratch	Tutorials
Accomplish a specific task	How-to Guides
Look up API details	Reference
Understand concepts	Explanation

Installation

Add CQL to your shard.yml:

dependencies:
  cql:
    github: azutoolkit/cql
    version: ~> 0.0.435

  # Choose your database driver:
  pg:  # PostgreSQL
    github: will/crystal-pg
    version: "~> 0.26.0"

Then run:

shards install

Full installation guide

Quick Start

require "cql"
require "pg"

# Define your database
MyDB = CQL::Schema.define(
  :my_db,
  adapter: CQL::Adapter::Postgres,
  uri: "postgres://localhost/myapp"
) do
end

# Define a model
struct User
  include CQL::ActiveRecord::Model(Int64)
  db_context MyDB, :users

  property id : Int64?
  property name : String
  property email : String

  def initialize(@name : String, @email : String)
  end
end

# Use it
MyDB.init
user = User.create!(name: "Alice", email: "[e-mail]")
puts "Created user #{user.id}: #{user.name}"

Documentation Structure

Tutorials

Learning-oriented - Step-by-step guides for beginners

• Your First CQL App - Build your first application

• Building a Blog - Complete multi-part tutorial

How-to Guides

Task-oriented - Practical steps to accomplish specific goals

• Models - Define, validate, and enhance models

• Relationships - Set up associations

• Querying - Find and filter data

• Migrations - Manage schema changes

Reference

Information-oriented - Technical descriptions and specifications

• Quick Reference - Common patterns at a glance

• Glossary - Terminology definitions

• Error Codes - Error messages explained

Explanation

Understanding-oriented - Conceptual discussions

• What is an ORM? - ORM fundamentals

• Active Record Pattern - Design pattern overview

Key Features

• Type Safety - Catch errors at compile time

• Multiple Databases - PostgreSQL, MySQL, SQLite

• Active Record - Familiar patterns for rapid development

• Migrations - Version-controlled schema changes

• Validations - Built-in data integrity

• Relationships - belongs_to, has_one, has_many, many-to-many

• Soft Deletes - Mark records as deleted

• Optimistic Locking - Prevent concurrent update conflicts

Getting Help

• FAQ - Frequently asked questions

• Troubleshooting - Common issues

• Community - Get support

• GitHub Issues - Report bugs

License

CQL is available under the MIT license.