{"id":15713520,"url":"https://github.com/azutoolkit/cql","last_synced_at":"2026-01-18T21:07:15.054Z","repository":{"id":249836294,"uuid":"828022755","full_name":"azutoolkit/cql","owner":"azutoolkit","description":"CQL Toolkit is a comprehensive library designed to simplify and enhance the management and execution of SQL queries in Crystal. This toolkit provides utilities for building, validating, and executing SQL statements with ease, ensuring better performance and code maintainability.","archived":false,"fork":false,"pushed_at":"2025-10-18T17:14:25.000Z","size":3760,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-19T09:55:39.732Z","etag":null,"topics":["crystal","crystalang","db","mapper","query-builder","query-dsl","sql"],"latest_commit_sha":null,"homepage":"https://azutopia.gitbook.io/cql","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azutoolkit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_AUDIT.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-12T23:01:45.000Z","updated_at":"2025-10-18T17:14:28.000Z","dependencies_parsed_at":"2024-10-24T10:51:11.135Z","dependency_job_id":"78837c23-fdab-4fd6-a571-70f34eece4f6","html_url":"https://github.com/azutoolkit/cql","commit_stats":null,"previous_names":["azutoolkit/sql","azutoolkit/cql"],"tags_count":134,"template":false,"template_full_name":null,"purl":"pkg:github/azutoolkit/cql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fcql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fcql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fcql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fcql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azutoolkit","download_url":"https://codeload.github.com/azutoolkit/cql/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fcql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28550581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T20:59:07.572Z","status":"ssl_error","status_checked_at":"2026-01-18T20:59:02.799Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","crystalang","db","mapper","query-builder","query-dsl","sql"],"created_at":"2024-10-03T21:31:53.493Z","updated_at":"2026-01-18T21:07:15.040Z","avatar_url":"https://github.com/azutoolkit.png","language":"Crystal","readme":"[![Crystal CI](https://github.com/azutoolkit/cql/actions/workflows/crystal.yml/badge.svg)](https://github.com/azutoolkit/cql/actions/workflows/crystal.yml)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/a85e29e6b78849c28fb813397cc3eb1a)](https://app.codacy.com/gh/azutoolkit/cql/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n\n# CQL (Crystal Query Language)\n\n\u003cimg width=\"1038\" alt=\"cql-banner\" src=\"https://github.com/user-attachments/assets/ed4e733a-3d37-4d03-a4d8-d15bfd7e6f25\"\u003e\n\nA high-performance, type-safe ORM for Crystal applications that combines compile-time safety with runtime performance. Unlike traditional ORMs that catch errors at runtime, CQL validates your queries, relationships, and data access patterns before your code executes.\n\n\u003e _\"We migrated our Rails API to Crystal + CQL and saw response times drop from 200ms to 45ms while handling 3x more concurrent users.\"_ - Production User\n\n**[Complete Documentation →](https://azutopia.gitbook.io/cql)**\n\n## Why Choose CQL\n\n### Performance\n\n- 4x faster than ActiveRecord and Eloquent in real-world scenarios\n- 75% less memory usage compared to Ruby/PHP ORMs\n- Zero-allocation queries for maximum throughput\n- Compile-time optimizations eliminate runtime overhead\n\n### Type Safety\n\n- Catch errors at compile time - invalid queries fail before deployment\n- Full IDE autocompletion support for queries and relationships\n- Safe refactoring - rename columns/tables with confidence\n- No runtime surprises - association errors caught early\n\n### Developer Experience\n\n- Familiar ActiveRecord-style API - easy migration from Rails/Laravel\n- Rich query DSL with readable, type-safe syntax\n- Automatic schema synchronization - database changes tracked and versioned\n- Built-in performance monitoring with N+1 query detection\n\n## Core Features\n\n- **Type-Safe ORM**: Leverage Crystal's static type system for compile-time safety\n- **High Performance**: 4x faster than traditional ORMs with compile-time optimizations\n- **Active Record Pattern**: Intuitive Active Record API with full CRUD operations\n- **Smart Relationships**: Support for `belongs_to`, `has_one`, `has_many`, and `many_to_many` with automatic N+1 prevention\n- **Comprehensive Validations**: Built-in validation system with custom validator support\n- **Lifecycle Callbacks**: Before/after hooks for validation, save, create, update, and destroy\n- **Intelligent Migrations**: Schema evolution tools with automatic rollback support\n- **Schema Dump**: Reverse-engineer existing databases into CQL schema definitions\n- **Flexible Querying**: Fluent query builder with complex joins, subqueries, and raw SQL support\n- **Transaction Support**: Full ACID transaction support with nested transactions (savepoints)\n- **Optimistic Locking**: Built-in support for optimistic concurrency control\n- **Query Scopes**: Reusable query scopes for common filtering patterns\n- **Advanced Caching**: Multi-layer caching with Redis and memory cache support\n- **Performance Monitoring**: Built-in query profiling, N+1 detection, and optimization suggestions\n- **Multi-Database**: Support for PostgreSQL, MySQL, and SQLite with dialect-specific optimizations\n- **Flexible Primary Keys**: Support for Int32, Int64, UUID, and ULID primary keys\n\n## Performance Comparison\n\nReal-world benchmarks (1M records, complex queries):\n\n| Operation         | CQL   | ActiveRecord | Eloquent | Improvement     |\n| ----------------- | ----- | ------------ | -------- | --------------- |\n| **Simple SELECT** | 0.8ms | 3.2ms        | 4.1ms    | **4x faster**   |\n| **Complex JOIN**  | 2.1ms | 8.7ms        | 12.3ms   | **4-6x faster** |\n| **Bulk INSERT**   | 15ms  | 89ms         | 124ms    | **6-8x faster** |\n| **Memory Usage**  | 12MB  | 48MB         | 67MB     | **75% less**    |\n\n## Database Support\n\n| Database       | Support Level | Special Features                  |\n| -------------- | ------------- | --------------------------------- |\n| **PostgreSQL** | Full          | JSONB, Arrays, Advanced Types     |\n| **MySQL**      | Full          | Complete MySQL support            |\n| **SQLite**     | Full          | Perfect for development \u0026 testing |\n\n## Installation\n\nAdd CQL and your database driver to your `shard.yml`:\n\n```yaml\ndependencies:\n  cql:\n    github: azutoolkit/cql\n    version: \"~\u003e 0.0.435\"\n\n  # Choose your database driver:\n  pg: # For PostgreSQL\n    github: will/crystal-pg\n  mysql: # For MySQL\n    github: crystal-lang/crystal-mysql\n  sqlite3: # For SQLite\n    github: crystal-lang/crystal-sqlite3\n```\n\nThen install dependencies:\n\n```bash\nshards install\n```\n\n## Quick Start\n\n### 1. Define Your Schema\n\n```crystal\nrequire \"cql\"\nrequire \"sqlite3\"  # or \"pg\" or \"mysql\"\n\n# Define your database schema with compile-time validation\nBlogDB = CQL::Schema.define(\n  :blog_database,\n  adapter: CQL::Adapter::SQLite,\n  uri: \"sqlite3://db/blog.db\"\n) do\n  table :users do\n    primary :id, Int64\n    text :username\n    text :email\n    text :first_name, null: true\n    text :last_name, null: true\n    boolean :active, default: \"1\"\n    timestamps\n  end\n\n  table :posts do\n    primary :id, Int64\n    text :title\n    text :content\n    boolean :published, default: \"0\"\n    bigint :user_id\n    timestamps\n\n    # Type-safe foreign key relationships\n    foreign_key [:user_id], references: :users, references_columns: [:id]\n  end\nend\n\n# Create tables (with automatic validation)\nBlogDB.users.create!\nBlogDB.posts.create!\n```\n\n### 2. Create Models\n\n```crystal\nstruct User\n  getter id : Int64?\n  getter username : String\n  getter email : String\n  getter first_name : String?\n  getter last_name : String?\n  getter? active : Bool = true\n  getter created_at : Time?\n  getter updated_at : Time?\n\n  # Compile-time validated relationships\n  has_many :posts, foreign_key: :user_id\n\n  # Built-in validations with clear error messages\n  validate :username, presence: true, size: 2..50\n  validate :email, required: true, match: /\\A[\\w+\\-.]+@[a-z\\d\\-.]+\\.[a-z]+\\z/i\n\n  def initialize(@username : String, @email : String,\n                 @first_name : String? = nil, @last_name : String? = nil)\n  end\n\n  def full_name\n    if first_name \u0026\u0026 last_name\n      \"#{first_name} #{last_name}\"\n    else\n      username\n    end\n  end\nend\n\nstruct Post\n  getter id : Int64?\n  getter title : String\n  getter content : String\n  getter? published : Bool = false\n  getter user_id : Int64\n  getter created_at : Time?\n  getter updated_at : Time?\n\n  # Type-safe relationships prevent association errors\n  belongs_to :user, User, foreign_key: :user_id\n\n  # Comprehensive validations\n  validate :title, presence: true, size: 1..100\n  validate :content, presence: true\n\n  def initialize(@title : String, @content : String, @user_id : Int64)\n  end\nend\n```\n\n### 3. Work with Your Data\n\n```crystal\n# Create with automatic validation\nuser = User.new(\"alice_j\", \"alice@example.com\", \"Alice\", \"Johnson\")\nif user.save\n  puts \"✅ User created with ID: #{user.id}\"\nelse\n  puts \"❌ Validation errors: #{user.errors.map(\u0026.message)}\"\nend\n\n# Type-safe queries with IntelliSense support\nalice = User.find_by(username: \"alice_j\")\nactive_users = User.where(active: true).all\n\n# Create associated records (no N+1 queries!)\npost = user.posts.create(title: \"My First Post\", content: \"Hello, World!\")\n\n# Safe transactions with automatic rollback\nUser.transaction do |tx|\n  user = User.create!(username: \"bob\", email: \"bob@example.com\")\n  post = user.posts.create!(title: \"Bob's Post\", content: \"Content here\")\n\n  # If anything fails, everything rolls back automatically\n  # No partial data corruption!\nend\n\n# Advanced querying with type safety\npublished_posts = Post.where(published: true)\n                     .joins(:user)\n                     .where(users: {active: true})\n                     .order(created_at: :desc)\n                     .limit(10)\n                     .all\n\n# Complex queries made simple\nrecent_active_authors = User.joins(:posts)\n                           .where(\"posts.created_at \u003e ?\", 1.week.ago)\n                           .where(active: true)\n                           .distinct\n                           .count\n\nputs \"Found #{recent_active_authors} active authors this week\"\n```\n\n## Advanced Features\n\n### Type-Safe Schema Definition\n\n```crystal\n# Schema with advanced features\nBlogDB = CQL::Schema.define(:blog, adapter: CQL::Adapter::Postgres, uri: ENV[\"DATABASE_URL\"]) do\n  table :products do\n    primary :id, UUID                    # UUID primary keys\n    text :name\n    decimal :price, precision: 10, scale: 2\n    text :metadata                       # JSON columns\n    timestamps\n\n    # Optimized indexing\n    index :name, unique: true\n    index [:price, :created_at]          # Composite indexes for performance\n  end\nend\n```\n\n### Active Record Pattern\n\n```crystal\nstruct Product\n  include CQL::ActiveRecord::Model(UUID)\n  db_context BlogDB, :products\n\n  getter id : UUID?\n  getter name : String\n  getter price : Float64\n  getter created_at : Time?\n  getter updated_at : Time?\n\n  # Custom validations with clear error messages\n  validate :name, presence: true, size: 2..100\n  validate :price, gt: 0.0, lt: 1_000_000.0\n\n  def initialize(@name : String, @price : Float64)\n  end\nend\n\n# CRUD operations with validation\nproduct = Product.create!(name: \"Laptop\", price: 999.99)\nproduct = Product.find(product.id.not_nil!)\n\n# Efficient querying with type safety\naffordable_products = Product.where(\"price \u003c ?\", 1000.0)\n                             .order(:name)\n                             .limit(50)\n                             .all\n\n# Safe updates with validation\nproduct.price = 899.99\nproduct.save!  # Validates before saving\n\n# Safe deletion\nproduct.destroy!\n```\n\n### Validations\n\n```crystal\nstruct User\n  include CQL::ActiveRecord::Model(Int64)\n\n  # Built-in validations with internationalization support\n  validate :name, presence: true, size: 2..50\n  validate :email, required: true, match: /\\A[\\w+\\-.]+@[a-z\\d\\-.]+\\.[a-z]+\\z/i\n  validate :age, gt: 0, lt: 120\n  validate :password_confirmation, confirmation: :password\n\n  # Custom business logic validators\n  use CustomPasswordValidator\n  use BusinessRuleValidator\nend\n\n# Comprehensive error handling\nuser = User.new(\"\", \"invalid-email\")\nunless user.valid?\n  user.errors.each do |error|\n    puts \"🚫 #{error.field}: #{error.message}\"\n  end\nend\n```\n\n### Smart Relationships\n\n```crystal\nstruct User\n  # Type-safe relationship definitions\n  has_one :profile, UserProfile, foreign_key: :user_id\n  has_many :posts, foreign_key: :user_id\n  has_many :comments, foreign_key: :user_id\nend\n\nstruct Post\n  belongs_to :user, User, foreign_key: :user_id\n  has_many :comments, foreign_key: :post_id\n  many_to_many :tags, Tag, join_through: :post_tags\nend\n\n# Efficient association loading (automatic N+1 prevention)\nuser = User.find(1.to_i64)\nuser.posts.create(title: \"New Post\", content: \"Content\")\nuser.posts.size                         # Efficient count without loading all records\nuser.posts.any?                         # Check existence without memory overhead\n\n# Eager loading with preload (avoids N+1 queries)\nusers_with_posts = User.preload(:posts)\n                      .where(active: true)\n                      .all\n# Only 2 queries instead of N+1 queries!\n```\n\n### Transaction Management\n\n```crystal\n# Simple atomic transactions\nUser.transaction do |tx|\n  user = User.create!(username: \"john\", email: \"john@example.com\")\n  user.posts.create!(title: \"First Post\", content: \"Hello!\")\n\n  # Automatic rollback on any exception\n  raise \"Error!\" if some_condition  # Everything safely rolls back\nend\n\n# Nested transactions with savepoints (PostgreSQL)\nUser.transaction do |outer_tx|\n  user = User.create!(username: \"alice\", email: \"alice@example.com\")\n\n  User.transaction(outer_tx) do |inner_tx|\n    # Independent rollback scope\n    risky_operation()\n  rescue\n    inner_tx.rollback  # Only inner transaction rolls back\n  end\n\n  # Outer transaction continues safely\nend\n```\n\n### Schema Migrations\n\n```crystal\n# Version-controlled database evolution\nclass CreateUsersTable \u003c CQL::Migration(20240101120000)\n  def up\n    schema.users.create!\n  end\n\n  def down\n    schema.users.drop!\n  end\nend\n\nclass AddEmailToUsers \u003c CQL::Migration(20240102120000)\n  def up\n    schema.alter :users do\n      add_column :email, String, null: false\n      create_index :idx_users_email, [:email], unique: true\n    end\n  end\n\n  def down\n    schema.alter :users do\n      drop_index :idx_users_email\n      drop_column :email\n    end\n  end\nend\n\n# Safe migration management\nmigrator = CQL::Migrator.new(BlogDB)\nmigrator.up           # Apply all pending migrations\nmigrator.down(1)      # Rollback last migration safely\nmigrator.status       # Check migration status\n```\n\n### Query Scopes\n\n```crystal\nstruct Post\n  # Define reusable query patterns\n  scope :published, -\u003e{ where(published: true) }\n  scope :recent, -\u003e{ where(\"created_at \u003e ?\", 1.week.ago).order(created_at: :desc) }\n  scope :by_user, -\u003e(user_id : Int64) { where(user_id: user_id) }\n  scope :popular, -\u003e{ where(\"view_count \u003e ?\", 1000) }\nend\n\n# Chainable, composable queries\ntrending_posts = Post.published\n                    .recent\n                    .popular\n                    .limit(10)\n                    .all\n\nuser_content = Post.by_user(user.id.not_nil!)\n                  .published\n                  .order(created_at: :desc)\n                  .all\n```\n\n### Schema Dump\n\n```crystal\n# Import existing databases into CQL\nrequire \"cql\"\n\n# Connect to legacy database\ndumper = CQL::SchemaDump.new(CQL::Adapter::SQLite, \"sqlite3://legacy_app.db\")\n\n# Generate type-safe CQL schema from existing database\ndumper.dump_to_file(\"src/schemas/legacy_schema.cr\", :LegacyDB, :legacy_db)\n\n# Generated schema uses proper CQL methods with type safety:\n# text :name               # instead of generic column definitions\n# integer :user_id         # with proper type inference\n# timestamps               # standardized timestamp handling\n\ndumper.close\n\n# Now use your legacy database with full CQL features!\n```\n\n### Caching\n\n```crystal\n# Caching configuration\ncache_config = CQL::Cache::CacheConfig.new(\n  enabled: true,\n  ttl: 1.hour,\n  max_size: 10_000,\n  compression: true\n)\n\n# Memory cache for lightning-fast access\nmemory_cache = CQL::Cache::MemoryCache.new(max_size: 1000)\n\n# Redis cache for distributed applications\nredis_cache = CQL::Cache::RedisCache.new(\"redis://localhost:6379\")\n\n# Fragment caching for expensive operations\nfragment_cache = CQL::Cache::FragmentCache.new(memory_cache)\n\n# Intelligent caching with automatic invalidation\nresult = fragment_cache.cache_fragment(\"expensive_query\", {\"user_id\" =\u003e user.id}) do\n  # Expensive database operation cached automatically\n  User.join(:posts)\n      .where(active: true)\n      .preload(:profile)\n      .all\nend\n\n# Tag-based cache invalidation\nfragment_cache.invalidate_tags([\"user:#{user.id}\", \"posts\"])\n```\n\n### Performance Monitoring\n\n```crystal\n# Performance monitoring\nmonitor = CQL::Performance::PerformanceMonitor.new\n\n# Real-time query monitoring\nmonitor.on_query_executed do |event|\n  if event.duration \u003e 100.milliseconds\n    puts \"🐌 Slow query detected: #{event.sql} (#{event.duration}ms)\"\n    puts \"💡 Consider adding an index or optimizing the query\"\n  end\nend\n\n# Automatic N+1 query detection\ndetector = CQL::Performance::NPlusOneDetector.new\ndetector.analyze_queries(queries) do |pattern|\n  puts \"⚠️  N+1 Query Pattern Detected:\"\n  puts \"   Model: #{pattern.model}\"\n  puts \"   Association: #{pattern.association}\"\n  puts \"   Suggestion: Use .preload(:#{pattern.association})\"\nend\n\n# Generate beautiful performance reports\nreport_generator = CQL::Performance::Reports::HTMLReportGenerator.new\nreport_generator.generate_report(monitor.events, \"performance_report.html\")\nputs \"📊 Performance report generated: performance_report.html\"\n```\n\n## Use Cases\n\n### High-Performance APIs\n\n- RESTful APIs serving millions of requests\n- GraphQL backends with complex data fetching\n- Real-time applications with WebSocket connections\n- Microservices requiring fast data access\n\n### Enterprise Applications\n\n- Large-scale web applications\n- Complex business logic with data integrity requirements\n- Multi-tenant SaaS platforms\n- Financial and healthcare applications requiring compliance\n\n### Cloud-Native Development\n\n- Container-based deployments\n- Kubernetes-native applications\n- Serverless functions with database access\n- Auto-scaling applications\n\n### Modern Development Workflows\n\n- CI/CD pipelines with database testing\n- Type-safe development practices\n- Large team collaboration\n- Long-term maintenance and refactoring\n\n## Documentation\n\n**[Complete Documentation on GitBook →](https://azutopia.gitbook.io/cql)**\n\nComprehensive guides for every level:\n\n### Getting Started\n\n- **[Installation Guide](./docs/installation.md)** - Set up CQL in your project\n- **[Getting Started](./docs/guides/getting-started.md)** - Your first CQL application\n- **[Schema Definition](./docs/core-concepts/schemas.md)** - Type-safe database schemas\n- **[Configuration](./docs/guides/configuration.md)** - Environment setup and database connections\n\n### Core Features\n\n- **[Defining Models](./docs/guides/active-record-with-cql/defining-models.md)** - Active Record model setup\n- **[CRUD Operations](./docs/guides/active-record-with-cql/crud-operations.md)** - Create, read, update, delete\n- **[Complex Queries](./docs/guides/active-record-with-cql/complex-queries.md)** - Advanced querying and N+1 prevention\n- **[Validations](./docs/guides/active-record-with-cql/validations.md)** - Data validation and integrity\n- **[Relationships](./docs/guides/active-record-with-cql/relations/README.md)** - Model associations and relationships\n\n### Advanced Topics\n\n- **[Transactions](./docs/guides/active-record-with-cql/transactions.md)** - Managing database transactions\n- **[Migrations](./docs/guides/active-record-with-cql/migrations.md)** - Schema evolution and versioning\n- **[Schema Dump](./docs/guides/schema-dump.md)** - Reverse-engineer existing databases\n- **[Callbacks](./docs/guides/active-record-with-cql/callbacks.md)** - Lifecycle hooks and callbacks\n- **[Scopes](./docs/guides/active-record-with-cql/scopes.md)** - Reusable query methods\n- **[Optimistic Locking](./docs/guides/active-record-with-cql/optimistic-locking.md)** - Concurrency control\n\n### Performance \u0026 Production\n\n- **[Advanced Caching](./docs/guides/advanced-caching-architecture.md)** - Multi-layer caching strategies\n- **[Performance Monitoring](./docs/guides/performance-optimization.md)** - Query profiling and optimization\n- **[Security Guide](./docs/guides/security-guide.md)** - Production security best practices\n- **[Testing Strategies](./docs/guides/testing-strategies.md)** - Testing CQL applications\n\n### Reference\n\n- **[Quick Reference](./docs/guides/quick-reference.md)** - Cheat sheet for common operations\n- **[Architecture Overview](./docs/guides/architecture-overview.md)** - Understanding CQL's design\n- **[FAQ](./docs/faqs.md)** - Frequently asked questions\n- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions\n\n## Development \u0026 Testing\n\n### Running Tests\n\n```bash\n# Start PostgreSQL for full test suite\ndocker run --rm -e POSTGRES_DB=spec -e POSTGRES_PASSWORD=password -p 5432:5432 postgres\n\n# Run comprehensive test suite with PostgreSQL\nDATABASE_URL=\"postgres://postgres:password@localhost:5432/spec\" crystal spec\n\n# Quick test with SQLite (default)\ncrystal spec\n\n# Run specific test categories\ncrystal spec spec/patterns/active_record/relations/  # Relationship tests\ncrystal spec spec/cache/                           # Caching tests\ncrystal spec spec/performance/                     # Performance tests\n```\n\n### Database Compatibility\n\nCQL is actively tested and optimized for:\n\n- **PostgreSQL**: 12, 13, 14, 15, 16 with full feature support\n- **MySQL**: 8.0+ with dialect-specific optimizations\n- **SQLite**: 3.35+ perfect for development and testing\n\nEach adapter supports database-specific features and provides optimal performance.\n\n## Contributing\n\nWe welcome contributions! Here's how to get involved:\n\n### Quick Start\n\n1. Fork the repository on GitHub\n2. Clone your fork: `git clone https://github.com/yourusername/cql.git`\n3. Create your feature branch: `git checkout -b my-feature`\n4. Make your changes and add comprehensive tests\n5. Run the test suite: `crystal spec`\n6. Commit your changes: `git commit -am 'Add feature'`\n7. Push to your branch: `git push origin my-feature`\n8. Create a Pull Request with a clear description\n\n### Contribution Ideas\n\n- **Bug Fixes** - Help improve reliability\n- **Performance** - Optimize queries, reduce memory usage, improve speed\n- **Documentation** - Improve guides, add examples, fix typos\n- **Tests** - Add test coverage, create integration scenarios\n- **Features** - Implement new ORM features and database support\n- **Developer Experience** - Improve error messages, add tooling\n\n### Development Guidelines\n\n- Follow Crystal coding conventions and style guidelines\n- Add comprehensive tests for new features and bug fixes\n- Update documentation for API changes and new features\n- Ensure compatibility across all supported databases (PostgreSQL, MySQL, SQLite)\n- Use meaningful commit messages following [conventional commits](https://conventionalcommits.org/)\n- Add performance benchmarks for query-related features\n- Consider security implications for new features\n\n### Areas We Need Help With\n\n- Database adapter improvements and new database support\n- Query optimization and performance enhancements\n- Documentation improvements and examples\n- Testing across different Crystal versions\n- Integration with popular Crystal web frameworks\n\n## License\n\nCQL is released under the [MIT License](./LICENSE). Feel free to use it in personal and commercial projects.\n\n---\n\n## Get Started\n\n```crystal\n# Install CQL and start building your application\nshards install\n\n# Try the interactive examples\ncrystal examples/run_examples.cr\n```\n\n**[Get Started Now →](./docs/guides/getting-started.md) • [Try Examples →](./examples/) • [Join Community →](https://github.com/azutoolkit/cql/discussions)**\n\n---\n\nBuilt for the Crystal community.\n\nCQL provides the productivity of modern ORMs with the performance and type safety that Crystal developers need. Whether you're building a simple web application or a complex enterprise system, CQL gives you the tools to work with your data efficiently and safely.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazutoolkit%2Fcql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazutoolkit%2Fcql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazutoolkit%2Fcql/lists"}