Fix Active Record documentation to match CQL API patterns

- Change relationship macros to use positional foreign_key parameter
  (e.g., `has_many :posts, Post, :user_id` instead of `foreign_key:`)
- Replace `includes` with `preload` for eager loading
- Fix validation options: remove non-existent `min`, `max`, `unique`;
  use correct predicates `gt`, `gte`, `lt`, `lte`
- Remove counter_cache references (not implemented in CQL)
- Fix `on_delete: "CASCADE"` to use symbol `:cascade`

These changes ensure all code examples compile and match the actual
CQL Active Record implementation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: eliasjpr

docs/explanation/design-patterns/active-record.md

@@ -126,8 +126,8 @@ struct Post
   property body : String
   property user_id : Int64
 
-  belongs_to :user, User, foreign_key: :user_id
-  has_many :comments, Comment, foreign_key: :post_id
+  belongs_to :user, User, :user_id
+  has_many :comments, Comment, :post_id
 
   validate :title, presence: true
 
@@ -187,8 +187,8 @@ struct Order
   property status : String = "pending"
   property total : BigDecimal = BigDecimal.new(0)
 
-  belongs_to :user, User, foreign_key: :user_id
-  has_many :order_items, OrderItem, foreign_key: :order_id
+  belongs_to :user, User, :user_id
+  has_many :order_items, OrderItem, :order_id
 
   validate :status, in: ["pending", "paid", "shipped", "completed", "cancelled"]
 

docs/how-to/data-operations/delete.md

@@ -74,7 +74,7 @@ user.force_delete!   # Permanently removes from database
 With foreign key cascade:
 
 ```crystal
-# If posts have: on_delete: "CASCADE"
+# If posts have: on_delete: :cascade
 user = User.find!(1)
 user.delete!  # Also deletes all user's posts
 ```

docs/how-to/models/soft-delete.md

@@ -163,7 +163,7 @@ struct Post
 
   db_context MyDB, :posts
 
-  has_many :comments, Comment, foreign_key: :post_id
+  has_many :comments, Comment, :post_id
 
   after_destroy :soft_delete_comments
 

docs/how-to/performance/n-plus-one.md

@@ -22,13 +22,13 @@ With 100 posts, this runs 101 queries.
 
 ## Use Eager Loading
 
-Load relationships upfront with a single query.
+Load relationships upfront with batch queries using `preload`.
 
-### includes (Preload)
+### Basic Preload
 
 ```crystal
 # 2 queries total: posts + users
-posts = Post.includes(:user).all
+posts = Post.preload(:user).all
 
 posts.each do |post|
   puts post.user.name  # No additional query
@@ -40,25 +40,10 @@ end
 ```crystal
 # Load multiple associations
 posts = Post
-  .includes(:user, :comments)
+  .preload(:user, :comments)
   .all
 ```
 
-### Nested Relationships
-
-```crystal
-# Load nested associations
-posts = Post
-  .includes(comments: :user)
-  .all
-
-posts.each do |post|
-  post.comments.each do |comment|
-    puts comment.user.name  # Already loaded
-  end
-end
-```
-
 ## Use Joins for Filtering
 
 When filtering by associated records:
@@ -73,12 +58,11 @@ posts = Post
 
 ## Select Only Needed Columns
 
-Reduce memory when eager loading:
+Reduce memory by selecting specific columns:
 
 ```crystal
 posts = Post
-  .includes(:user)
-  .select("posts.*, users.name as user_name")
+  .select(:id, :title, :user_id)
   .all
 ```
 
@@ -123,7 +107,7 @@ SELECT * FROM users WHERE id = 3
 
 ```crystal
 # Controller
-@posts = Post.includes(:user, :comments).all
+@posts = Post.preload(:user, :comments).all
 
 # View - no additional queries
 <% @posts.each do |post| %>
@@ -132,20 +116,24 @@ SELECT * FROM users WHERE id = 3
 <% end %>
 ```
 
-### Counter Caches
+### Manual Counter Columns
 
-For counting associations, use counter caches:
+For frequently accessed counts, add a counter column and maintain it manually:
 
 ```crystal
-# Add column
-add_column :posts, :comments_count, Int32, default: 0
+# Add column in migration
+schema.alter :posts do
+  add_column :comments_count, Int32, default: 0
+end
 
-# Model configuration
-struct Post
-  has_many :comments, Comment, foreign_key: :post_id, counter_cache: true
+# Update counter when adding comments
+def create_comment(post : Post, content : String)
+  Comment.create!(content: content, post_id: post.id.not_nil!)
+  post.comments_count = post.comments.count.to_i32
+  post.save!
 end
 
-# Now post.comments_count uses cached value
+# Now use post.comments_count instead of post.comments.count
 ```
 
 ### Aggregations

docs/how-to/relationships/belongs-to.md

@@ -47,7 +47,7 @@ struct Comment
   property body : String
   property post_id : Int64
 
-  belongs_to :post, Post, foreign_key: :post_id
+  belongs_to :post, Post, :post_id
 
   def initialize(@body : String, @post_id : Int64)
   end
@@ -125,7 +125,7 @@ struct Comment
   # ...
   property user_id : Int64?
 
-  belongs_to :user, User, foreign_key: :user_id
+  belongs_to :user, User, :user_id
 
   def initialize(@body : String, @post_id : Int64, @user_id : Int64? = nil)
   end

docs/how-to/relationships/has-many.md

@@ -44,7 +44,7 @@ struct User
   property id : Int64?
   property name : String
 
-  has_many :posts, Post, foreign_key: :user_id
+  has_many :posts, Post, :user_id
 
   def initialize(@name : String)
   end
@@ -59,7 +59,7 @@ struct Post
   property title : String
   property body : String
 
-  belongs_to :user, User, foreign_key: :user_id
+  belongs_to :user, User, :user_id
 
   def initialize(@title : String, @body : String, @user_id : Int64)
   end

docs/how-to/relationships/has-one.md

@@ -48,7 +48,7 @@ struct User
   property id : Int64?
   property name : String
 
-  has_one :profile, Profile, foreign_key: :user_id
+  has_one :profile, Profile, :user_id
 
   def initialize(@name : String)
   end
@@ -63,7 +63,7 @@ struct Profile
   property bio : String?
   property avatar_url : String?
 
-  belongs_to :user, User, foreign_key: :user_id
+  belongs_to :user, User, :user_id
 
   def initialize(@user_id : Int64, @bio : String? = nil, @avatar_url : String? = nil)
   end

docs/how-to/relationships/many-to-many.md

@@ -55,7 +55,7 @@ struct Post
   property id : Int64?
   property title : String
 
-  has_many :post_tags, PostTag, foreign_key: :post_id
+  has_many :post_tags, PostTag, :post_id
 
   def initialize(@title : String)
   end
@@ -89,7 +89,7 @@ struct Tag
   property id : Int64?
   property name : String
 
-  has_many :post_tags, PostTag, foreign_key: :tag_id
+  has_many :post_tags, PostTag, :tag_id
 
   def initialize(@name : String)
   end
@@ -114,8 +114,8 @@ struct PostTag
   property tag_id : Int64
   property created_at : Time?
 
-  belongs_to :post, Post, foreign_key: :post_id
-  belongs_to :tag, Tag, foreign_key: :tag_id
+  belongs_to :post, Post, :post_id
+  belongs_to :tag, Tag, :tag_id
 
   def initialize(@post_id : Int64, @tag_id : Int64)
   end

docs/reference/api/validation-options.md

@@ -45,18 +45,18 @@ validate :tags, size: 1..5                # Array size
 
 **Error:** "field_name must be between X and Y characters"
 
-### min / max
+### gt / gte / lt / lte
 
 Validates numeric values are within bounds.
 
 ```crystal
-validate :age, min: 0
-validate :age, max: 150
-validate :quantity, min: 1, max: 100
-validate :price, min: 0.01
+validate :age, gte: 0                # Greater than or equal to 0
+validate :age, lte: 150              # Less than or equal to 150
+validate :quantity, gte: 1, lte: 100 # Between 1 and 100
+validate :price, gt: 0               # Greater than 0
 ```
 
-**Error:** "field_name must be at least X" / "field_name must be at most X"
+**Error:** "field_name must be greater than X" / "field_name must be less than or equal to X"
 
 ### in
 
@@ -70,28 +70,25 @@ validate :priority, in: [1, 2, 3, 4, 5]
 
 **Error:** "field_name must be one of: X, Y, Z"
 
-### unique
+### exclude
 
-Validates that a value is unique in the database.
+Validates that a value is not in a list of excluded values.
 
 ```crystal
-validate :email, unique: true
-validate :username, unique: true
-validate :slug, unique: true
+validate :username, exclude: ["admin", "root", "system"]
+validate :status, exclude: ["deleted"]
 ```
 
-**Note:** Performs a database query on each validation.
-
-**Error:** "field_name has already been taken"
+**Error:** "field_name must not be included in [X, Y, Z]"
 
 ## Combining Validations
 
 Multiple validations can be applied to a single field:
 
 ```crystal
-validate :email, presence: true, match: /@/, unique: true
+validate :email, presence: true, match: /@/
 validate :username, presence: true, size: 3..20, match: /^[a-z0-9_]+$/
-validate :age, presence: true, min: 0, max: 150
+validate :age, presence: true, gte: 0, lte: 150
 ```
 
 ## Model Example
@@ -121,12 +118,8 @@ struct User
   validate :username, size: 3..20
   validate :password, size: 8..128
 
-  # Uniqueness
-  validate :email, unique: true
-  validate :username, unique: true
-
   # Numeric constraints
-  validate :age, min: 0, max: 150
+  validate :age, gte: 0, lte: 150
 
   # Allowed values
   validate :role, in: ["admin", "moderator", "user"]

docs/reference/quick-reference.md

@@ -77,9 +77,9 @@ User.where(active: true)
 
 ```crystal
 # Define
-belongs_to :user, User, foreign_key: :user_id
-has_one :profile, Profile, foreign_key: :user_id
-has_many :posts, Post, foreign_key: :user_id
+belongs_to :user, User, :user_id
+has_one :profile, Profile, :user_id
+has_many :posts, Post, :user_id
 
 # Use
 user.posts.all