docs

CQL (Crystal Query Language)

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: "alice@example.com")
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.