From 82074d6d8c0c0661c1c3b2b375ee82b165199e0c Mon Sep 17 00:00:00 2001
From: GJ Enosh <enoshgollapalli@gmail.com>
Date: Mon, 11 May 2026 00:13:40 +0530
Subject: [PATCH] docs: create Common Pitfalls Guide

---
 docs/doc/common-pitfalls.mdx | 47 ++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 docs/doc/common-pitfalls.mdx

diff --git a/docs/doc/common-pitfalls.mdx b/docs/doc/common-pitfalls.mdx
new file mode 100644
index 0000000..33dd4c0
--- /dev/null
+++ b/docs/doc/common-pitfalls.mdx
@@ -0,0 +1,47 @@
+# Common Pitfalls
+
+This guide covers common mistakes new Ryx users make and how to fix them.
+
+## 1. Using `select_related` when you need `prefetch_related`
+
+**Problem:** Using `select_related` for many-to-many or reverse foreign key relationships causes errors.
+
+**Solution:** Use `prefetch_related` for many-to-many and reverse foreign key relationships. Use `select_related` only for forward foreign key and one-to-one relationships.
+
+```python
+# Wrong
+users = await User.objects.select_related("posts").all()
+
+# Correct
+users = await User.objects.prefetch_related("posts").all()
+```
+
+## 2. Forgetting to use async context managers
+
+**Problem:** Opening database connections without async context managers causes connection leaks.
+
+**Solution:** Always use `async with` when working with database connections.
+
+```python
+# Wrong
+db = Database()
+await db.connect()
+
+# Correct
+async with Database() as db:
+    await db.query(...)
+```
+
+## 3. Not awaiting async queries
+
+**Problem:** Forgetting `await` on async queries returns a coroutine object instead of results.
+
+**Solution:** Always use `await` with Ryx query methods.
+
+```python
+# Wrong
+users = User.objects.all()
+
+# Correct
+users = await User.objects.all()
+```