feat: update doc

Author: qorzj

README.md

@@ -35,12 +35,17 @@ from commondao.annotation import TableId
 from pydantic import BaseModel
 from typing import Annotated
 
-# Define your Pydantic model with TableId annotation
+# Define your Pydantic models with TableId annotation
 class User(BaseModel):
     id: Annotated[int, TableId('users')]  # First field with TableId is the primary key
     name: str
     email: str
 
+class UserInsert(BaseModel):
+    id: Annotated[Optional[int], TableId('users')] = None  # Optional for auto-increment
+    name: str
+    email: str
+
 async def main():
     # Connect to database
     config = {
@@ -54,7 +59,7 @@ async def main():
 
     async with connect(**config) as db:
         # Insert a new user using Pydantic model
-        user = User(id=1, name='John Doe', email='john@example.com')
+        user = UserInsert(name='John Doe', email='john@example.com')
         await db.insert(user)
 
         # Query the user by key with Pydantic model validation
@@ -91,30 +96,35 @@ from pydantic import BaseModel
 from commondao.annotation import TableId
 from typing import Annotated, Optional
 
-class User(BaseModel):
+class UserInsert(BaseModel):
     id: Annotated[Optional[int], TableId('users')] = None  # Auto-increment primary key
     name: str
     email: str
 
 # Insert using Pydantic model (id will be auto-generated)
-user = User(name='John', email='john@example.com')
+user = UserInsert(name='John', email='john@example.com')
 await db.insert(user)
 print(f"New user id: {db.lastrowid()}")  # Get the auto-generated id
 
 # Insert with ignore option (skips duplicate key errors)
-user2 = User(name='Jane', email='jane@example.com')
+user2 = UserInsert(name='Jane', email='jane@example.com')
 await db.insert(user2, ignore=True)
 ```
 
 ### Update Data (with Pydantic Models)
 
 ```python
+class UserUpdate(BaseModel):
+    id: Optional[int] = None
+    name: Optional[str] = None
+    email: Optional[str] = None
+
 # Update by primary key (id must be provided)
-user = User(id=1, name='John Smith', email='john.smith@example.com')
+user = UserUpdate(id=1, name='John Smith', email='john.smith@example.com')
 await db.update_by_id(user)
 
-# Update by custom key (partial update - only non-None fields)
-user_update = User(name='Jane Doe', email='jane.doe@example.com')  # id can be None
+# Update by custom key (partial update - only specified fields)
+user_update = UserUpdate(name='Jane Doe', email='jane.doe@example.com')
 await db.update_by_key(user_update, key={'email': 'john.smith@example.com'})
 ```
 
@@ -294,23 +304,23 @@ result = await db.execute_query(
 from commondao.annotation import TableId
 from typing import Annotated, Optional
 
-class Order(BaseModel):
+class OrderInsert(BaseModel):
     id: Annotated[Optional[int], TableId('orders')] = None
     customer_id: int
     total: float
 
-class OrderItem(BaseModel):
+class OrderItemInsert(BaseModel):
     id: Annotated[Optional[int], TableId('order_items')] = None
     order_id: int
     product_id: int
 
 async with connect(host='localhost', user='root', db='testdb') as db:
     # Start transaction (autocommit=False by default)
-    order = Order(customer_id=1, total=99.99)
+    order = OrderInsert(customer_id=1, total=99.99)
     await db.insert(order)
     order_id = db.lastrowid()  # Get the auto-generated order id
 
-    item = OrderItem(order_id=order_id, product_id=42)
+    item = OrderItemInsert(order_id=order_id, product_id=42)
     await db.insert(item)
 
     # Commit the transaction

reference.md

@@ -54,7 +54,7 @@ Insert a Pydantic model instance into the database.
 
 **Example:**
 ```python
-user = User(name='John', email='john@example.com')
+user = UserInsert(name='John', email='john@example.com')
 affected_rows = await db.insert(user)
 ```
 
@@ -72,7 +72,7 @@ Update a record by its primary key using a Pydantic model.
 
 **Example:**
 ```python
-user = User(id=1, name='John Updated', email='john.new@example.com')
+user = UserUpdate(id=1, name='John Updated', email='john.new@example.com')
 affected_rows = await db.update_by_id(user)
 ```
 
@@ -88,7 +88,7 @@ Update records matching the specified key conditions.
 
 **Example:**
 ```python
-user_update = User(name='Jane', email='jane@example.com')
+user_update = UserUpdate(name='Jane', email='jane@example.com')
 affected_rows = await db.update_by_key(user_update, key={'id': 1})
 ```
 
@@ -494,7 +494,7 @@ Raised when attempting operations with empty or None primary key values.
 **Example:**
 ```python
 try:
-    user = User(id=None, name="John")
+    user = UserUpdate(id=None, name="John")
     await db.update_by_id(user)
 except EmptyPrimaryKeyError as e:
     print(f"Primary key error: {e}")
@@ -566,7 +566,7 @@ def process_database_row(data: dict):
     assert is_row_dict(data)
     # Type checker now knows data is RowDict
     # Safe to use for database operations
-    user = User(**data)
+    user = UserInsert(**data)
     await db.insert(user)
 
 def process_query_parameters(params: dict):
@@ -619,3 +619,17 @@ def example_function(unknown_data: dict):
         unknown_data  # Type checker knows this is safe
     )
 ```
+
+## Best Practices
+
+### Entity Class Naming Conventions
+
+When designing Pydantic models for database operations, follow these naming conventions to improve code clarity and maintainability:
+
+把dao.insert的实体类命名为以Insert为后缀的类名; 把dao.update的实体类重命名为以Update为后缀的类名; 其他用于查询的类名不变
+
+一般来说, 用于查询的实体类如果字段DDL为not null,则字段就不能optional; 用于insert的实体类如果字段DDL为nullable,或者有默认值,则字段就可以optional;用于update的实体类的字段都是optional
+
+用于insert的实体类只包含可能需要插入的字段;用于update的实体类只包含可能需要修改的字段
+
+用于insert/update的实体类，即使主键字段是optional，也需要注解TableId