sqlobjects 1.0.9__tar.gz → 1.0.11__tar.gz

sqlobjects-1.0.11/CHANGELOG.md

@@ -0,0 +1,97 @@
+## 1.0.11 (2025-11-18)
+
+### Feat
+
+- add AI assistant rules with auto-install support
+
+## 1.0.10 (2025-11-17)
+
+### Feat
+
+- support Model class in join methods for cleaner API
+
+## 1.0.9 (2025-11-14)
+
+### Feat
+
+- add optional tables parameter to create_tables/drop_tables
+
+## 1.0.8 (2025-11-11)
+
+### Feat
+
+- add model-level relationship loading methods
+- improve relation field type inference
+- refactor relationship proxies
+
+## 1.0.7 (2025-10-14)
+
+### Feat
+
+- add upsert support for PostgreSQL
+
+### Fix
+
+- identity support for PostgreSQL
+
+### Refactor
+
+- consolidate bulk and queryset logic
+
+### Perf
+
+- improve bulk delete performance
+
+## 1.0.6 (2025-10-08)
+
+### Feat
+
+- optimize field cache and state manager
+- implement relationship prefetch support
+- add kwargs parameter support to filter/exclude/get methods
+
+### Refactor
+
+- unify cascade for model and queryset operations
+
+## 1.0.5 (2025-09-25)
+
+### Fix
+
+- generate DDL using column definition order
+
+## 1.0.4 (2025-09-25)
+
+### Feat
+
+- remove unnecessary exception catching
+- implement insert or update using database upsert
+
+### Fix
+
+- use pk column name instead of column instance for pgsql upsert
+
+### Refactor
+
+- move field default value related methods to DataConversionMixin
+
+## 1.0.3 (2025-09-25)
+
+### Fix
+
+- field default/default_factory not working
+
+## 1.0.2 (2025-09-24)
+
+### Feat
+
+- add type support for StringColumn
+- add support for cascade delete in relationships
+- add cascade support to relationship fields
+- add type checking for __registry__
+- use base model to create database tables
+- init public commit
+
+### Fix
+
+- foreign key type inference issue

sqlobjects-1.0.11/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include docs/rules *.md

{sqlobjects-1.0.9/sqlobjects.egg-info → sqlobjects-1.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.0.9
+Version: 1.0.11
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
@@ -26,6 +26,10 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: sqlalchemy[asyncio]>=2.0.43
+Provides-Extra: amazonq
+Provides-Extra: kiro
+Provides-Extra: claude
+Provides-Extra: cursor
 Dynamic: license-file
 
 # SQLObjects
@@ -216,6 +220,21 @@ SQLObjects is built on a solid foundation with clear architectural principles:
 
 ## 📖 Documentation
 
+### AI Assistant Rules (Quick Reference)
+
+Best practices and usage patterns optimized for AI coding assistants:
+
+- [AI Rules Overview](docs/rules/README.md) - Quick navigation and purpose
+- [Database & Session Guide](docs/rules/01-database-session-guide.md) - Connection management and transactions
+- [Model Definition Guide](docs/rules/02-model-definition-guide.md) - Model creation and field configuration
+- [Query Operations Guide](docs/rules/03-query-operations-guide.md) - Filtering, sorting, and data retrieval
+- [CRUD Operations Guide](docs/rules/04-crud-operations-guide.md) - Create, read, update, delete operations
+- [Relationships Guide](docs/rules/05-relationships-guide.md) - Model relationships and loading strategies
+- [Validation & Signals Guide](docs/rules/06-validation-signals-guide.md) - Data validation and lifecycle hooks
+- [Performance Guide](docs/rules/07-performance-guide.md) - Optimization techniques and best practices
+
+**Installation**: Rules are automatically installed with `pip install sqlobjects[amazonq]` (or `[cursor]`, `[claude]`, `[kiro]`)
+
 ### Feature Documentation
 
 - [Database Setup](docs/features/01-database-setup.md) - Database configuration and connection management
@@ -277,7 +296,7 @@ older_users = await User.objects.filter(User.age > avg_age).all()
 
 # Manual joins and locking
 posts = await Post.objects.join(
-    User.__table__, 
+    User,  # Using Model class (recommended)
     Post.author_id == User.id
 ).select_for_update(nowait=True).all()
 

{sqlobjects-1.0.9 → sqlobjects-1.0.11}/README.md

@@ -186,6 +186,21 @@ SQLObjects is built on a solid foundation with clear architectural principles:
 
 ## 📖 Documentation
 
+### AI Assistant Rules (Quick Reference)
+
+Best practices and usage patterns optimized for AI coding assistants:
+
+- [AI Rules Overview](docs/rules/README.md) - Quick navigation and purpose
+- [Database & Session Guide](docs/rules/01-database-session-guide.md) - Connection management and transactions
+- [Model Definition Guide](docs/rules/02-model-definition-guide.md) - Model creation and field configuration
+- [Query Operations Guide](docs/rules/03-query-operations-guide.md) - Filtering, sorting, and data retrieval
+- [CRUD Operations Guide](docs/rules/04-crud-operations-guide.md) - Create, read, update, delete operations
+- [Relationships Guide](docs/rules/05-relationships-guide.md) - Model relationships and loading strategies
+- [Validation & Signals Guide](docs/rules/06-validation-signals-guide.md) - Data validation and lifecycle hooks
+- [Performance Guide](docs/rules/07-performance-guide.md) - Optimization techniques and best practices
+
+**Installation**: Rules are automatically installed with `pip install sqlobjects[amazonq]` (or `[cursor]`, `[claude]`, `[kiro]`)
+
 ### Feature Documentation
 
 - [Database Setup](docs/features/01-database-setup.md) - Database configuration and connection management
@@ -247,7 +262,7 @@ older_users = await User.objects.filter(User.age > avg_age).all()
 
 # Manual joins and locking
 posts = await Post.objects.join(
-    User.__table__, 
+    User,  # Using Model class (recommended)
     Post.author_id == User.id
 ).select_for_update(nowait=True).all()
 

sqlobjects-1.0.11/docs/rules/01-database-session-guide.md

@@ -0,0 +1,278 @@
+# Database & Session Management Guide
+
+## Core Concepts
+
+- **DatabaseManager**: Global singleton managing multiple database connections
+- **Session**: Task-level database session with automatic transaction management
+- **Context Managers**: `ctx_session()` and `ctx_sessions()` for transaction control
+- **using() Pattern**: Bind operations to specific sessions or databases
+
+## Common Usage
+
+### Single Database Setup
+
+```python
+from sqlobjects.database import init_db, create_tables
+from sqlobjects.model import ObjectModel
+
+# Initialize database
+await init_db("sqlite+aiosqlite:///app.db")
+
+# Create tables
+await create_tables(ObjectModel)
+
+# Use default session (automatic)
+user = await User.objects.create(username="alice")
+```
+
+### Multi-Database Setup
+
+```python
+from sqlobjects.database import init_dbs
+
+# Configure multiple databases
+await init_dbs({
+    "main": {"url": "postgresql+asyncpg://localhost/main", "pool_size": 20},
+    "analytics": {"url": "sqlite+aiosqlite:///analytics.db"}
+}, default="main")
+
+# Use specific database
+user = await User.objects.using("analytics").create(username="analyst")
+```
+
+### Transaction Management
+
+```python
+from sqlobjects.session import ctx_session, ctx_sessions
+
+# Single database transaction
+async with ctx_session() as session:
+    user = await User.objects.using(session).create(username="bob")
+    posts = await user.posts.using(session).all()
+    # Auto-commit on success, rollback on exception
+
+# Multi-database transaction
+async with ctx_sessions("main", "analytics") as sessions:
+    user = await User.objects.using(sessions["main"]).create(username="alice")
+    await Log.objects.using(sessions["analytics"]).create(message="User created")
+```
+
+### Session Binding
+
+```python
+# Bind to session
+async with ctx_session() as session:
+    # All operations use the same session
+    user = await User.objects.using(session).get(User.id == 1)
+    user.email = "new@example.com"
+    await user.using(session).save()
+
+# Bind to named database
+user = await User.objects.using("analytics").create(username="test")
+```
+
+## Best Practices
+
+### ✅ Do
+
+- **Use context managers** for explicit transaction control
+- **Bind operations to sessions** in complex transactions
+- **Configure connection pools** based on your workload
+- **Use read-only sessions** for query-only operations
+- **Close databases** properly on application shutdown
+
+```python
+# Good: Explicit transaction
+async with ctx_session() as session:
+    user = await User.objects.using(session).create(username="alice")
+    await Post.objects.using(session).create(title="First Post", author_id=user.id)
+
+# Good: Connection pool configuration
+await init_db(
+    "postgresql://localhost/db",
+    pool_size=20,
+    max_overflow=30,
+    pool_timeout=30,
+    pool_recycle=3600
+)
+```
+
+### ❌ Don't
+
+- **Don't mix sessions** in related operations
+- **Don't forget to close** database connections
+- **Don't use tiny connection pools** in production
+- **Don't create sessions manually** (use context managers)
+
+```python
+# Bad: Mixing sessions
+async with ctx_session() as session1:
+    user = await User.objects.using(session1).create(username="alice")
+    async with ctx_session() as session2:
+        # Different session - may cause issues
+        await Post.objects.using(session2).create(author_id=user.id)
+
+# Bad: No transaction control
+user = await User.objects.create(username="alice")
+# If next operation fails, user is already created
+await Post.objects.create(title="Post", author_id=user.id)
+```
+
+## Performance Tips
+
+### Connection Pooling
+
+```python
+# Production configuration
+await init_db(
+    "postgresql://localhost/db",
+    pool_size=20,           # Base connections
+    max_overflow=30,        # Burst capacity
+    pool_timeout=30,        # Wait time for connection
+    pool_recycle=3600,      # Recycle connections hourly
+    pool_pre_ping=True      # Verify connections
+)
+```
+
+### Session Reuse
+
+```python
+# Reuse session across operations
+async with ctx_session() as session:
+    # All operations share the same connection
+    users = await User.objects.using(session).all()
+    for user in users:
+        await user.posts.using(session).all()
+```
+
+### Read/Write Separation
+
+```python
+# Use readonly parameter for read operations
+from sqlobjects.session import get_session
+
+# Read operations
+session = get_session(readonly=True)
+users = await User.objects.using(session).all()
+
+# Write operations
+session = get_session(readonly=False)
+await User.objects.using(session).create(username="alice")
+```
+
+## Troubleshooting
+
+### Connection Pool Exhausted
+
+**Problem**: `TimeoutError: QueuePool limit exceeded`
+
+**Solution**:
+```python
+# Increase pool size
+await init_db(url, pool_size=30, max_overflow=50)
+
+# Or use context managers to release connections
+async with ctx_session() as session:
+    # Connection released after block
+    pass
+```
+
+### Transaction Deadlock
+
+**Problem**: Operations hang or timeout
+
+**Solution**:
+```python
+# Use shorter transactions
+async with ctx_session() as session:
+    # Keep transaction scope small
+    user = await User.objects.using(session).get(User.id == 1)
+    user.email = "new@example.com"
+    await user.using(session).save()
+# Transaction commits here
+
+# Don't hold transactions during I/O
+async with ctx_session() as session:
+    user = await User.objects.using(session).get(User.id == 1)
+# Transaction ends before external I/O
+await send_email(user.email)  # Outside transaction
+```
+
+### Session Not Found
+
+**Problem**: `RuntimeError: No session available`
+
+**Solution**:
+```python
+# Always use context managers or explicit binding
+async with ctx_session() as session:
+    user = await User.objects.using(session).create(username="alice")
+
+# Or bind to database name
+user = await User.objects.using("main").create(username="alice")
+```
+
+### Database Connection Lost
+
+**Problem**: `OperationalError: connection closed`
+
+**Solution**:
+```python
+# Enable connection health checks
+await init_db(url, pool_pre_ping=True, pool_recycle=3600)
+
+# Handle connection errors gracefully
+try:
+    user = await User.objects.get(User.id == 1)
+except OperationalError:
+    # Reconnect or retry
+    await init_db(url)
+    user = await User.objects.get(User.id == 1)
+```
+
+## Complete Example
+
+```python
+from sqlobjects.database import init_dbs, create_tables, close_all_dbs
+from sqlobjects.session import ctx_session, ctx_sessions
+from sqlobjects.model import ObjectModel
+from sqlobjects.fields import Column, StringColumn
+
+class User(ObjectModel):
+    username: Column[str] = StringColumn(length=50)
+    email: Column[str] = StringColumn(length=100)
+
+class Log(ObjectModel):
+    message: Column[str] = StringColumn(length=500)
+
+async def main():
+    # Setup
+    await init_dbs({
+        "main": {"url": "postgresql://localhost/main", "pool_size": 20},
+        "analytics": {"url": "sqlite:///analytics.db"}
+    }, default="main")
+    
+    await create_tables(ObjectModel, "main")
+    await create_tables(ObjectModel, "analytics")
+    
+    # Single database transaction
+    async with ctx_session() as session:
+        user = await User.objects.using(session).create(
+            username="alice",
+            email="alice@example.com"
+        )
+    
+    # Multi-database transaction
+    async with ctx_sessions("main", "analytics") as sessions:
+        user = await User.objects.using(sessions["main"]).get(User.username == "alice")
+        await Log.objects.using(sessions["analytics"]).create(
+            message=f"User {user.username} logged in"
+        )
+    
+    # Cleanup
+    await close_all_dbs()
+
+# Run
+import asyncio
+asyncio.run(main())
+```