rhosocial-activerecord-postgres 1.0.0.dev2__tar.gz → 1.0.0.dev4__tar.gz

{rhosocial_activerecord_postgres-1.0.0.dev2 → rhosocial_activerecord_postgres-1.0.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhosocial_activerecord_postgres
-Version: 1.0.0.dev2
+Version: 1.0.0.dev4
 Summary: postgres backend implementation for rhosocial-activerecord, providing a robust and optimized postgres database support.
 Author-email: vistart <i@vistart.me>
 License:                                  Apache License
@@ -255,456 +255,290 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/rhosocial-activerecord-postgres.svg)](https://pypi.org/project/rhosocial-activerecord-postgres/)
 [![Tests](https://github.com/rhosocial/python-activerecord-postgres/actions/workflows/test.yml/badge.svg)](https://github.com/rhosocial/python-activerecord-postgres/actions)
 [![Coverage Status](https://codecov.io/gh/rhosocial/python-activerecord-postgres/branch/main/graph/badge.svg)](https://app.codecov.io/gh/rhosocial/python-activerecord-postgres/tree/main)
-[![License](https://img.shields.io/github/license/rhosocial/python-activerecord-postgres.svg)](https://github.com/rhosocial/python-activerecord-postgres/blob/main/LICENSE)
+[![Apache 2.0 License](https://img.shields.io/github/license/rhosocial/python-activerecord-postgres.svg)](https://github.com/rhosocial/python-activerecord-postgres/blob/main/LICENSE)
 [![Powered by vistart](https://img.shields.io/badge/Powered_by-vistart-blue.svg)](https://github.com/vistart)
 
 <div align="center">
     <img src="https://raw.githubusercontent.com/rhosocial/python-activerecord/main/docs/images/logo.svg" alt="rhosocial ActiveRecord Logo" width="200"/>
-    <p>postgres backend implementation for rhosocial-activerecord, providing a robust and optimized postgres database support.</p>
+    <h3>PostgreSQL Backend for rhosocial-activerecord</h3>
+    <p><b>Native Array & JSONB Support · Advanced Types · Sync & Async</b></p>
 </div>
 
-# Postgres Backend Implementation Guide
+> **Note**: This is a backend implementation for [rhosocial-activerecord](https://github.com/rhosocial/python-activerecord). It cannot be used standalone.
 
-## Overview
+## Why This Backend?
 
-This postgres backend implementation provides both **synchronous** and **asynchronous** support using the `psycopg` (psycopg3) driver.
+### 1. PostgreSQL's Unique Type System
 
-## Key Features
+| Feature | PostgreSQL Backend | MySQL Backend | SQLite Backend |
+|---------|-------------------|---------------|----------------|
+| **Native Arrays** | ✅ `INTEGER[]`, `TEXT[]` | ❌ Serialize to string | ❌ Serialize to string |
+| **JSONB** | ✅ Binary JSON, indexed | ✅ JSON (text-based) | ⚠️ JSON1 extension |
+| **UUID** | ✅ Native type | ⚠️ CHAR(36) | ⚠️ TEXT |
+| **Range Types** | ✅ `DATERANGE`, `INT4RANGE` | ❌ | ❌ |
+| **RETURNING** | ✅ All operations | ❌ | ✅ |
 
-- ✅ **Dual Implementation**: Both sync (`PostgresBackend`) and async (`AsyncPostgresBackend`)
-- ✅ **Shared Logic**: Common functionality in `PostgresBackendMixin`
-- ✅ **Full Transaction Support**: Including savepoints and DEFERRABLE mode
-- ✅ **Rich Type Support**: Arrays, JSONB, UUID, ranges, network types, geometry
-- ✅ **Complete Capability Declaration**: CTEs, window functions, JSON operations, etc.
-- ✅ **Native Driver**: Uses psycopg3 directly, no ORM dependencies
+### 2. No Adapter Overhead for Arrays
 
-## Installation
+Unlike databases without native arrays, PostgreSQL stores and queries arrays directly:
 
-```bash
-pip install rhosocial-activerecord-postgres
-```
+```python
+# PostgreSQL: Native array - no serialization needed
+class Article(ActiveRecord):
+    tags: list[str]  # Maps directly to TEXT[]
 
-**Dependencies**:
-- `rhosocial-activerecord>=1.0.0,<2.0.0`
-- `psycopg>=3.2.12`
+# MySQL/SQLite: Requires adapter
+class Article(ActiveRecord):
+    tags: Annotated[list[str], UseAdapter(ListToStringAdapter(), str)]
+```
 
-## Usage Examples
+### 3. Powerful Array Operators
 
-### Synchronous Usage
+Query arrays with native PostgreSQL operators:
 
 ```python
-from rhosocial.activerecord.model import ActiveRecord
-from rhosocial.activerecord.backend.impl.postgres import (
-    PostgresBackend,
-    PostgresConnectionConfig
-)
+# Contains
+Article.query().where("tags @> ARRAY[?]", ('python',)).all()
 
-# Configure connection
-config = PostgresConnectionConfig(
-    host="localhost",
-    port=5432,
-    database="mydb",
-    username="user",
-    password="password",
-    options={
-        "sslmode": "prefer",
-        "connect_timeout": 10,
-        "application_name": "my_app"
-    }
-)
-
-# Create backend
-backend = PostgresBackend(connection_config=config)
+# Overlaps (any element matches)
+Article.query().where("tags && ARRAY[?, ?]", ('python', 'database')).all()
 
-# Configure model
-class User(ActiveRecord):
-    __table_name__ = "users"
-    name: str
-    email: str
+# Any element equals
+Article.query().where("? = ANY(tags)", ('python',)).all()
+```
 
-User.configure(backend)
+> 💡 **AI Prompt**: "Show me all PostgreSQL array operators with examples"
 
-# Use the model
-user = User(name="John", email="john@example.com")
-user.save()
+## Quick Start
 
-# Query with CTEs (postgres 8.4+)
-results = User.query().with_cte(
-    "active_users",
-    User.query().where(is_active=True)
-).from_cte("active_users").all()
+### Installation
 
-# Use JSONB operations (postgres 9.4+)
-users = User.query().where(
-    "metadata->>'role' = ?", ("admin",)
-).all()
+```bash
+pip install rhosocial-activerecord-postgres
 ```
 
-### Asynchronous Usage
+### Basic Usage
 
 ```python
-import asyncio
-from rhosocial.activerecord.async_model import ActiveRecord
-from rhosocial.activerecord.backend.impl.postgres import (
-    AsyncPostgresBackend,
-    PostgresConnectionConfig
-)
+from rhosocial.activerecord.model import ActiveRecord
+from rhosocial.activerecord.backend.impl.postgres import PostgresBackend
+from rhosocial.activerecord.backend.impl.postgres.config import PostgresConnectionConfig
+from typing import Optional
+from uuid import UUID
 
-async def main():
-    # Configure connection
-    config = PostgresConnectionConfig(
-        host="localhost",
-        port=5432,
-        database="mydb",
-        username="user",
-        password="password",
-    )
-
-    # Create async backend
-    backend = ActiveRecord(connection_config=config)
-    
-    # Connect explicitly for async
-    await backend.connect()
-
-    # Configure model
-    class User(ActiveRecord):
-        __table_name__ = "users"
-        name: str
-        email: str
-
-    User.configure(backend)
-
-    # Use the model asynchronously
-    user = User(name="Jane", email="jane@example.com")
-    await user.save()
-
-    # Async queries
-    users = await User.query().where(is_active=True).all()
-
-    # Cleanup
-    await backend.disconnect()
-
-# Run async code
-asyncio.run(main())
-```
+class User(ActiveRecord):
+    __table_name__ = "users"
+    id: Optional[UUID] = None  # Native UUID type
+    name: str
+    tags: list[str]  # Native array type
+    metadata: dict  # JSONB type
 
-### Transaction Usage
+# Configure
+config = PostgresConnectionConfig(
+    host="localhost",
+    port=5432,
+    database="myapp",
+    username="user",
+    password="password"
+)
+User.configure(config, PostgresBackend)
 
-**Synchronous Transactions**:
+# Use
+user = User(name="Alice", tags=["python", "postgres"])
+user.save()
 
-```python
-# Get transaction manager
-tm = backend.transaction_manager
-
-# Basic transaction
-with tm:
-    user1 = User(name="Alice")
-    user1.save()
-    user2 = User(name="Bob")
-    user2.save()
-# Auto-commit on context exit
-
-# Explicit control
-tm.begin()
-try:
-    user = User(name="Charlie")
-    user.save()
-    tm.commit()
-except Exception:
-    tm.rollback()
-    raise
-
-# With savepoints
-tm.begin()
-user1 = User(name="Dave")
-user1.save()
-
-savepoint = tm.savepoint()
-try:
-    user2 = User(name="Eve")
-    user2.save()
-    tm.release_savepoint(savepoint)
-except Exception:
-    tm.rollback_savepoint(savepoint)
-
-tm.commit()
-
-# With isolation level and deferrable mode
-tm.set_isolation_level(IsolationLevel.SERIALIZABLE)
-tm.set_deferrable(True)
-with tm:
-    # Deferrable serializable transaction
-    pass
+# Query with array operators
+python_users = User.query().where("tags @> ARRAY[?]", ('python',)).all()
 ```
 
-**Asynchronous Transactions**:
+> 💡 **AI Prompt**: "How do I configure connection pooling for PostgreSQL?"
 
-```python
-async def async_transaction_example():
-    # Get async transaction manager
-    tm = backend.transaction_manager
-
-    # Basic async transaction
-    async with tm:
-        user1 = User(name="Alice")
-        await user1.save()
-        user2 = User(name="Bob")
-        await user2.save()
-    # Auto-commit on context exit
-
-    # Explicit control
-    await tm.begin()
-    try:
-        user = User(name="Charlie")
-        await user.save()
-        await tm.commit()
-    except Exception:
-        await tm.rollback()
-        raise
-
-    # With savepoints
-    await tm.begin()
-    user1 = User(name="Dave")
-    await user1.save()
-
-    savepoint = await tm.savepoint()
-    try:
-        user2 = User(name="Eve")
-        await user2.save()
-        await tm.release_savepoint(savepoint)
-    except Exception:
-        await tm.rollback_savepoint(savepoint)
-
-    await tm.commit()
-```
+## PostgreSQL-Specific Features
 
-### Postgres-Specific Features
+### Array Types
 
-**Array Types**:
+Native array support without adapters:
 
 ```python
-from rhosocial.activerecord.model import ActiveRecord
-
 class Article(ActiveRecord):
     __table_name__ = "articles"
     title: str
-    tags: list  # Will use postgres array type
-
-article = Article(
-    title="postgres Arrays",
-    tags=["database", "postgres", "arrays"]
-)
-article.save()
+    tags: list[str]      # TEXT[]
+    scores: list[int]    # INTEGER[]
 
-# Query arrays
-articles = Article.query().where(
-    "? = ANY(tags)", ("postgres",)
-).all()
+# Query with array operators
+Article.query().where("tags @> ARRAY[?]", ('python',)).all()
+Article.query().where("? = ANY(tags)", ('database',)).all()
+Article.query().where("array_length(tags, 1) > ?", (3,)).all()
 ```
 
-**JSONB Operations**:
+> See [Array Type Comparison](docs/en_US/type_adapters/array_comparison.md) for differences with other databases.
 
-```python
-from rhosocial.activerecord.model import ActiveRecord
+### JSONB Operations
 
+Binary JSON with indexing support:
+
+```python
 class Product(ActiveRecord):
     __table_name__ = "products"
     name: str
-    attributes: dict  # Will use JSONB type
-
-product = Product(
-    name="Laptop",
-    attributes={
-        "brand": "Dell",
-        "specs": {
-            "cpu": "Intel i7",
-            "ram": "16GB"
-        }
-    }
-)
-product.save()
+    attributes: dict  # JSONB
 
 # Query JSONB
-products = Product.query().where(
-    "attributes->>'brand' = ?", ("Dell",)
-).all()
-
-# JSONB contains
-products = Product.query().where(
-    "attributes @> ?", ('{"brand": "Dell"}',)
-).all()
+Product.query().where("attributes->>'brand' = ?", ("Dell",)).all()
+
+# JSONB contains (@>)
+Product.query().where("attributes @> ?", ('{"brand": "Dell"}',)).all()
 ```
 
-**Range Types**:
+### UUID Type
+
+Native UUID storage and querying:
+
+```python
+from uuid import UUID, uuid4
+
+class User(ActiveRecord):
+    __table_name__ = "users"
+    id: UUID
+    name: str
+
+user = User(id=uuid4(), name="Alice")
+user.save()
+```
+
+### Range Types
+
+Built-in support for range types:
 
 ```python
 from datetime import date
-from rhosocial.activerecord.model import ActiveRecord
 
 class Booking(ActiveRecord):
     __table_name__ = "bookings"
     room_id: int
-    date_range: tuple  # Will use DATERANGE type
-
-booking = Booking(
-    room_id=101,
-    date_range=(date(2024, 1, 1), date(2024, 1, 7))
-)
-booking.save()
+    date_range: tuple  # DATERANGE
 
-# Query ranges
-bookings = Booking.query().where(
-    "date_range @> ?", (date(2024, 1, 3),)
-).all()
+# Query with range operators
+Booking.query().where("date_range @> ?", (date(2024, 1, 15),)).all()
 ```
 
-## Configuration Options
+### RETURNING Clause
 
-### Connection Options
+Retrieve data after INSERT/UPDATE/DELETE:
 
 ```python
-config = PostgresConnectionConfig(
-    host="localhost",
-    port=5432,
-    database="mydb",
-    username="user",
-    password="password",
-    options={
-        # SSL/TLS
-        "sslmode": "prefer",  # disable, allow, prefer, require, verify-ca, verify-full
-        
-        # Connection timeout
-        "connect_timeout": 10,
-        
-        # Application identification
-        "application_name": "my_app",
-        
-        # Client encoding
-        "client_encoding": "UTF8",
-        
-        # Connection pooling (if supported)
-        "pool_min_size": 1,
-        "pool_max_size": 10,
-        "pool_timeout": 30.0,
-    }
-)
+# INSERT with RETURNING
+user = User(name="Alice")
+user.save()
+print(user.id)  # Populated automatically via RETURNING
+
+# Works for all operations (unlike MySQL)
 ```
 
-## Postgres Version Compatibility
+## Requirements
+
+- **Python**: 3.8+ (including 3.13t/3.14t free-threaded builds)
+- **Core**: `rhosocial-activerecord>=1.0.0`
+- **Driver**: `psycopg>=3.2.12`
 
-| Feature | Minimum Version | Notes |
-|---------|----------------|-------|
+## PostgreSQL Version Compatibility
+
+| Feature | Min Version | Notes |
+|---------|-------------|-------|
 | Basic operations | 8.0+ | Core functionality |
+| RETURNING | 8.2+ | INSERT/UPDATE/DELETE RETURNING |
 | CTEs | 8.4+ | WITH clauses |
 | Window functions | 8.4+ | ROW_NUMBER, RANK, etc. |
-| RETURNING clause | 8.2+ | INSERT/UPDATE/DELETE RETURNING |
-| JSON type | 9.2+ | Basic JSON support |
-| JSONB type | 9.4+ | Binary JSON, better performance |
-| UPSERT (ON CONFLICT) | 9.5+ | INSERT ... ON CONFLICT |
+| TRUNCATE RESTART IDENTITY | 8.4+ | Reset sequences on truncate |
+| JSON | 9.2+ | Basic JSON support |
+| LATERAL joins | 9.3+ | LATERAL keyword |
+| JSONB | 9.4+ | Binary JSON, indexed |
+| FILTER clause | 9.4+ | Aggregate FILTER |
+| Ordered-set aggregates | 9.4+ | PERCENTILE_CONT, etc. |
+| UPSERT | 9.5+ | INSERT ... ON CONFLICT |
+| Advanced grouping | 9.5+ | ROLLUP, CUBE, GROUPING SETS |
+| SKIP LOCKED | 9.5+ | FOR UPDATE SKIP LOCKED |
+| MATERIALIZED CTE hints | 12.0+ | MATERIALIZED/NOT MATERIALIZED |
+| JSON_TABLE | 12.0+ | JSON table function |
+| MERGE | 15.0+ | MERGE statement |
 
-**Recommended**: Postgres 12+ for optimal feature support and performance.
+**Supported SQL Protocols:**
+- ✅ SetOperationSupport (UNION, INTERSECT, EXCEPT) — All versions
+- ✅ TruncateSupport (TRUNCATE TABLE) — All versions; RESTART IDENTITY ≥ 8.4
 
-## Architecture Notes
+**Recommended**: PostgreSQL 12+ for optimal feature support.
 
-### Backend Structure
+See [PROTOCOL_SUPPORT.md](docs/PROTOCOL_SUPPORT.md) for complete protocol support matrix.
 
-```
-PostgresBackendMixin (Shared Logic)
-    ├── Configuration validation
-    ├── Version parsing
-    ├── Capability initialization
-    ├── Type converter registration
-    └── Error mapping
-
-PostgresBackend (Sync)           AsyncPostgresBackend (Async)
-    ├── Inherits Mixin                 ├── Inherits Mixin
-    ├── Inherits StorageBackend        ├── Inherits AsyncStorageBackend
-    ├── Sync connection management     ├── Async connection management
-    ├── Sync query execution           ├── Async query execution
-    └── Sync transaction manager       └── Async transaction manager
-```
+## Get Started with AI Code Agents
 
-### Transaction Structure
+This project supports AI-assisted development:
 
+```bash
+git clone https://github.com/rhosocial/python-activerecord-postgres.git
+cd python-activerecord-postgres
 ```
-PostgresTransactionMixin (Shared Logic)
-    ├── Isolation level mapping
-    ├── Savepoint name generation
-    ├── SQL statement building
-    └── Deferrable mode support
-
-PostgresTransactionManager       AsyncPostgresTransactionManager
-    ├── Inherits Mixin                 ├── Inherits Mixin
-    ├── Inherits TransactionManager    ├── Inherits AsyncTransactionManager
-    ├── Sync transaction operations    ├── Async transaction operations
-    └── Sync constraint management     └── Async constraint management
-```
-
-## Testing
 
-The backend includes comprehensive test coverage for both sync and async implementations:
+### Example AI Prompts
 
-- Connection lifecycle tests
-- CRUD operation tests
-- Transaction tests (with savepoints)
-- Type conversion tests
-- Capability declaration verification
-- Error handling tests
-- Concurrent operation tests
+- "How do I use array operators to query tags?"
+- "What's the difference between JSON and JSONB in PostgreSQL?"
+- "Show me how to create a GIN index on an array column"
+- "How do I use range types for scheduling?"
 
-**Run sync tests**:
-```bash
-pytest tests/rhosocial/activerecord_test/feature/backend/postgres/test_backend_sync.py
-```
+### For Any LLM
 
-**Run async tests**:
-```bash
-pytest tests/rhosocial/activerecord_test/feature/backend/postgres/test_backend_async.py
-```
+Feed the documentation files in `docs/` for context-aware assistance.
 
-## Migration from Old Implementation
+## Testing
 
-If you have an existing postgres backend implementation, here's how to migrate:
+> ⚠️ **CRITICAL**: Tests MUST run serially. Do NOT use `pytest -n auto` or parallel execution.
 
-**Old code**:
-```python
-from rhosocial.activerecord.backend.impl.postgres import PostgresBackend
+```bash
+# Run all tests
+PYTHONPATH=src pytest tests/
 
-backend = PostgresBackend(...)
+# Run specific feature tests
+PYTHONPATH=src pytest tests/rhosocial/activerecord_postgres_test/feature/basic/
+PYTHONPATH=src pytest tests/rhosocial/activerecord_postgres_test/feature/query/
 ```
 
-**New code** (no changes needed for sync):
-```python
-from rhosocial.activerecord.backend.impl.postgres import PostgresBackend
+See the [Testing Documentation](https://github.com/rhosocial/python-activerecord/blob/main/.claude/testing.md) for details.
 
-backend = PostgresBackend(...)  # Same API
-```
+## Documentation
 
-**New async support**:
-```python
-from rhosocial.activerecord.backend.impl.postgres import AsyncPostgresBackend
+- **[Getting Started](docs/en_US/getting_started/)** — Installation and configuration
+- **[PostgreSQL Features](docs/en_US/postgres_specific_features/)** — PostgreSQL-specific capabilities
+- **[Type Adapters](docs/en_US/type_adapters/)** — Data type handling
+- **[Array Comparison](docs/en_US/type_adapters/array_comparison.md)** — Array support across databases
+- **[Transaction Support](docs/en_US/transaction_support/)** — Transaction management
 
-backend = AsyncPostgresBackend(...)
-await backend.connect()
-```
+## Comparison with Other Backends
 
-## Known Limitations
+| Feature | PostgreSQL | MySQL | SQLite |
+|---------|------------|-------|--------|
+| **Native Arrays** | ✅ | ❌ | ❌ |
+| **JSONB (indexed)** | ✅ | ⚠️ JSON only | ⚠️ Extension |
+| **UUID Type** | ✅ Native | ⚠️ CHAR(36) | ⚠️ TEXT |
+| **Range Types** | ✅ | ❌ | ❌ |
+| **RETURNING** | ✅ | ❌ | ✅ |
+| **CTEs** | ✅ 8.4+ | ✅ 8.0+ | ✅ 3.8.3+ |
+| **Full-Text Search** | ✅ | ✅ | ⚠️ FTS5 |
 
-1. **Connection Pooling**: Basic implementation, consider using external pooling (pgbouncer) for production
-2. **Async Context**: Async backend requires explicit `await backend.connect()` call
-3. **Type Converters**: Some postgres-specific types may need custom converters
+> 💡 **AI Prompt**: "When should I choose PostgreSQL over MySQL for my project?"
 
 ## Contributing
 
-Contributions are welcome! Please ensure:
-
-- Tests pass for both sync and async implementations
-- Code follows project style guidelines
-- Documentation is updated
-- Changelog fragments are created
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-[![license](https://img.shields.io/github/license/rhosocial/python-activerecord-postgres.svg)](https://github.com/rhosocial/python-activerecord-postgres/blob/main/LICENSE)
+[Apache License 2.0](LICENSE) — Copyright © 2026 [vistart](https://github.com/vistart)
 
-Copyright © 2025 [vistart](https://github.com/vistart)
+---
+
+<div align="center">
+    <p><b>Built with ❤️ by the rhosocial team</b></p>
+    <p><a href="https://github.com/rhosocial/python-activerecord-postgres">GitHub</a> · <a href="https://docs.python-activerecord.dev.rho.social/backends/postgres.html">Documentation</a> · <a href="https://pypi.org/project/rhosocial-activerecord-postgres/">PyPI</a></p>
+</div>