# 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.