# Guides Overview

Welcome to the CQL Guides section! Here you'll find practical, focused documentation to help you use CQL (Crystal Query Language) effectively in your Crystal projects.

## What You'll Find

Our guides are organized to help you progress from basic concepts to advanced techniques:

### Getting Started

* [**Getting Started Guide**](getting-started) - Build your first CQL application
* [**Configuration**](configuration) - Set up CQL for all environments
* [**Architecture Overview**](architecture-overview) - Understand how CQL works

### Active Record with CQL

* [**Active Record Overview**](../active-record-with-cql/active-record-with-cql) - Complete guide to the Active Record pattern
* [**Defining Models**](../active-record-with-cql/defining-models) - Create your first models
* [**CRUD Operations**](../active-record-with-cql/crud-operations) - Create, read, update, delete
* [**Querying & Scopes**](../active-record-with-cql/queryable) - Find what you need
* [**Relationships**](../active-record-with-cql/relations) - Connect your data
* [**Validations**](../active-record-with-cql/validations) - Ensure data quality
* [**Callbacks**](../active-record-with-cql/callbacks) - Hook into model lifecycle
* [**Transactions**](../active-record-with-cql/transactions) - Maintain data consistency

### Database Management

* [**Migrations**](../database-management/migrations) - Version control your database
* [**Migration Best Practices**](../database-management/handling-migrations) - Follow proven patterns
* [**Migration Guide**](../database-management/migration-guide) - Transition from other ORMs
* [**Schema Dump**](../database-management/schema-dump) - Export and import schemas

### Advanced Topics

* [**Performance Optimization**](../advanced-topics/performance-optimization) - Make your queries fast
* [**Performance Monitoring**](broken-reference) - Query analysis and N+1 detection
* [**Security Guide**](../advanced-topics/security-guide) - Secure database operations
* [**Testing Strategies**](../advanced-topics/testing-strategies) - Test your database code

### Best Practices & Comparison

* [**Best Practices**](best-practices) - Follow proven patterns
* [**Feature Comparison**](feature-comparison) - See how CQL compares to other ORMs
* [**Community**](../help-and-resources/community) - Connect with other developers

## Learning Paths

### New to CQL?

1. [**Getting Started**](getting-started) - Build your first app
2. [**Active Record Overview**](../active-record-with-cql/active-record-with-cql) - Learn the most popular pattern
3. [**Defining Models**](../active-record-with-cql/defining-models) - Create your models
4. [**CRUD Operations**](../active-record-with-cql/crud-operations) - Basic database operations
5. [**Relationships**](../active-record-with-cql/relations) - Connect your data
6. [**Validations**](../active-record-with-cql/validations) - Ensure data quality

### Coming from Another ORM?

1. [**Feature Comparison**](feature-comparison) - See how CQL compares
2. [**Migration Guide**](../database-management/migration-guide) - Transition smoothly
3. [**Architecture Overview**](architecture-overview) - Understand the design
4. [**Best Practices**](best-practices) - Follow proven patterns

### Ready for Production?

1. [**Configuration**](configuration) - Optimize for your environment
2. [**Performance Optimization**](../advanced-topics/performance-optimization) - Make it fast
3. [**Security Guide**](../advanced-topics/security-guide) - Keep it secure
4. [**Testing Strategies**](../advanced-topics/testing-strategies) - Ensure reliability

## How to Use These Guides

* **Start with the basics** - If you're new to CQL, begin with [Getting Started](getting-started)
* **Follow the learning paths** - Use the paths above to guide your learning
* **Use the sidebar** - Navigate between related topics easily
* **Check examples** - See [Examples](../examples-and-tutorials/examples) for working code samples
* **Get help** - Visit [Troubleshooting](https://github.com/azutoolkit/cql/blob/master/docs/help-and-resources/troubleshooting.md) or [Community](../help-and-resources/community) if you get stuck

## What Makes These Guides Special

Each guide is designed to be:

* **Self-contained** - Complete examples and explanations
* **Practical** - Real-world scenarios and code samples
* **Progressive** - Build on previous knowledge
* **Tested** - All examples work with the latest CQL version
* **Crystal-focused** - Tailored for Crystal developers

Whether you're building your first Crystal app with CQL or looking to master advanced features, these guides are your go-to resource for effective CQL development.

***

> Don't try to read everything at once! Pick a learning path that matches your experience level and goals, then work through it systematically.

> If you get stuck, check the [Troubleshooting Guide](https://github.com/azutoolkit/cql/blob/master/docs/help-and-resources/troubleshooting.md) or ask the [Community](../help-and-resources/community) for help.
