# 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](https://azutopia.gitbook.io/cql/tutorials/tutorials)       |
| Accomplish a specific task | [How-to Guides](https://azutopia.gitbook.io/cql/how-to-guides/how-to)  |
| Look up API details        | [Reference](https://azutopia.gitbook.io/cql/reference/reference)       |
| Understand concepts        | [Explanation](https://azutopia.gitbook.io/cql/explanation/explanation) |

## Installation

Add CQL to your `shard.yml`:

```yaml
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:

```shell
shards install
```

[Full installation guide](https://azutopia.gitbook.io/cql/installation)

## Quick Start

```crystal
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](https://azutopia.gitbook.io/cql/tutorials/your-first-cql-app) - Build your first application
* [Building a Blog](https://azutopia.gitbook.io/cql/tutorials/01-project-setup) - Complete multi-part tutorial

### How-to Guides

**Task-oriented** - Practical steps to accomplish specific goals

* [Models](https://azutopia.gitbook.io/cql/models/define-model) - Define, validate, and enhance models
* [Relationships](https://azutopia.gitbook.io/cql/relationships/belongs-to) - Set up associations
* [Querying](https://azutopia.gitbook.io/cql/querying/find-records) - Find and filter data
* [Migrations](https://azutopia.gitbook.io/cql/migrations/create-migration) - Manage schema changes

### Reference

**Information-oriented** - Technical descriptions and specifications

* [Quick Reference](https://azutopia.gitbook.io/cql/reference/quick-reference) - Common patterns at a glance
* [Glossary](https://azutopia.gitbook.io/cql/resources/glossary) - Terminology definitions
* [Error Codes](https://azutopia.gitbook.io/cql/resources/error-codes) - Error messages explained

### Explanation

**Understanding-oriented** - Conceptual discussions

* [What is an ORM?](https://azutopia.gitbook.io/cql/explanation/what-is-orm) - ORM fundamentals
* [Active Record Pattern](https://azutopia.gitbook.io/cql/explanation/active-record) - 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](https://azutopia.gitbook.io/cql/resources-1/faq) - Frequently asked questions
* [Troubleshooting](https://azutopia.gitbook.io/cql/troubleshooting/connection-errors) - Common issues
* [Community](https://azutopia.gitbook.io/cql/resources-1/community) - Get support
* [GitHub Issues](https://github.com/azutoolkit/cql/issues) - Report bugs

## License

CQL is available under the MIT license.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://azutopia.gitbook.io/cql/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.