pgdbm 0.1.0__tar.gz

pgdbm-0.1.0/.claude/settings.local.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python:*)",
+      "Bash(ls:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(source:*)",
+      "Bash(psql:*)",
+      "Bash(timeout:*)",
+      "Bash(pre-commit run:*)",
+      "Bash(ruff check:*)",
+      "Bash(mypy:*)",
+      "Bash(uv run mypy:*)",
+      "Bash(uv run pre-commit run:*)",
+      "Bash(git add:*)",
+      "Bash(git reset:*)",
+      "Bash(uv run ruff:*)",
+      "Bash(uv run isort:*)",
+      "Bash(uv run bandit:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(git commit:*)",
+      "Bash(rm:*)"
+    ],
+    "deny": []
+  }
+}

pgdbm-0.1.0/.gitattributes

@@ -0,0 +1,60 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Python files
+*.py text
+*.pyw text
+*.pyx text
+*.pyi text
+
+# Documentation
+*.md text
+*.rst text
+*.txt text
+LICENSE text
+AUTHORS text
+CHANGELOG text
+CONTRIBUTING text
+README text
+
+# Config files
+*.json text
+*.yaml text
+*.yml text
+*.toml text
+*.ini text
+*.cfg text
+.gitignore text
+.gitattributes text
+
+# Shell scripts
+*.sh text eol=lf
+*.bash text eol=lf
+
+# Windows scripts
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Binary files
+*.db binary
+*.sqlite binary
+*.sqlite3 binary
+*.pyc binary
+*.pyo binary
+*.pyd binary
+*.so binary
+*.dylib binary
+*.dll binary
+*.exe binary
+*.zip binary
+*.tar binary
+*.gz binary
+*.bz2 binary
+*.7z binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

pgdbm-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Environment variables
+.env*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.venv/
+venv/
+
+# Emacs
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+.emacs-bu/
+*.elc
+auto-save-list
+tramp
+.\#*
+.dir-locals.el
+.projectile
+
+# OS
+.DS_Store
+Thumbs.db
+
+Makefile
+tmp

pgdbm-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: detect-private-key
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+      - id: name-tests-test
+        args: ['--pytest-test-first']
+
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+        language_version: python3
+        args: ['--config=pyproject.toml']
+
+  - repo: https://github.com/pycqa/isort
+    rev: 6.0.1
+    hooks:
+      - id: isort
+        args: ['--settings-path=pyproject.toml']
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.12.5
+    hooks:
+      - id: ruff
+        args: ['--fix', '--exit-non-zero-on-fix']
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.17.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [asyncpg-stubs, pydantic, pytest, pytest-asyncio]
+        args: ['--config-file=pyproject.toml', 'src/']
+        files: '^src/'
+        pass_filenames: false
+
+
+ci:
+  autoupdate_schedule: weekly
+  skip: [mypy]  # mypy requires installed dependencies

pgdbm-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

pgdbm-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to pgdbm will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- TLS/SSL support in `DatabaseConfig` with `ssl_enabled`, `ssl_mode`, CA/cert/key options
+- Server-side timeouts in `DatabaseConfig` (`statement_timeout_ms`, `idle_in_transaction_session_timeout_ms`, `lock_timeout_ms`)
+- Advisory locking in migrations to serialize runners per `module_name`
+- Migration version extraction from filenames
+  - Supports numeric prefix (001_), Flyway style (V1__), and timestamp patterns
+  - Automatic version property on Migration model
+  - Better ordering and conflict prevention
+
+### Changed
+- Replace generic exceptions with custom error types throughout codebase
+  - ConfigurationError, PoolError, QueryError, MigrationError, etc.
+  - Enhanced error messages with troubleshooting tips
+  - Better debugging experience
+- `execute_and_return_id` now correctly detects existing RETURNING clauses to avoid duplication
+- **BREAKING**: Minimum Python version raised to 3.9
+  - Python 3.8 reached EOL in October 2024
+  - Allows use of modern type annotations and features
+
+## [0.1.0] - 2025-01-26
+
+### Added
+- Initial public release
+- Core async database management with connection pooling
+- Schema-based multi-tenancy support
+- Built-in migration system
+- Comprehensive testing utilities
+- Connection monitoring and debugging tools
+- Shared connection pool support for microservices
+- Full type hints and py.typed support
+- Pytest fixtures for easy testing
+- Production-ready patterns out of the box
+
+### Features
+- **AsyncDatabaseManager**: Main database interface with connection pooling
+- **DatabaseConfig**: Pydantic-based configuration management
+- **AsyncMigrationManager**: Database migration tracking and execution
+- **MonitoredAsyncDatabaseManager**: Performance monitoring capabilities
+- **Testing utilities**: Automatic test database creation and cleanup
+- **Schema isolation**: Multi-tenant support with `{{tables.name}}` templating
+
+[Unreleased]: https://github.com/juanreyero/pgdbm/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/juanreyero/pgdbm/releases/tag/v0.1.0

pgdbm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juan Reyero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pgdbm-0.1.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: pgdbm
+Version: 0.1.0
+Summary: Production-ready async PostgreSQL utilities with connection pooling, migrations, and testing support
+Project-URL: Homepage, https://juanreyero.com/open/pgdbm
+Project-URL: Documentation, https://github.com/juanre/pgdbm
+Project-URL: Repository, https://github.com/juanre/pgdbm
+Project-URL: Issues, https://github.com/juanre/pgdbm/issues
+Project-URL: Changelog, https://github.com/juanre/pgdbm/blob/main/CHANGELOG.md
+Author-email: Juan Reyero <juan@juanreyero.com>
+Maintainer-email: Juan Reyero <juan@juanreyero.com>
+License: MIT
+License-File: LICENSE
+Keywords: async,asyncio,asyncpg,database,migrations,postgresql,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: asyncpg>=0.28.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# pgdbm
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/pypi/pyversions/pgdbm.svg)](https://pypi.org/project/pgdbm/)
+[![PyPI](https://img.shields.io/pypi/v/pgdbm.svg)](https://pypi.org/project/pgdbm/)
+
+A PostgreSQL library for Python that provides high-level async database operations with built-in migration management, connection pooling, and testing utilities. It offers:
+
+- **Connection pooling** with proper resource management
+- **Schema migrations** that are version-controlled and automated
+- **Testing utilities** that provide isolated test databases
+- **Module isolation** when multiple services share a database
+- **Monitoring** for slow queries and connection issues
+
+## Key Features
+
+- **🚀 High Performance** - Built on asyncpg, the fastest PostgreSQL driver for Python
+- **📦 Migration System** - Version-controlled schema migrations with automatic ordering
+- **🧪 Testing Support** - Fixtures and utilities for database testing
+- **🔧 Module Isolation** - Prevent table conflicts when modules share databases
+- **📊 Monitoring** - Track slow queries and connection pool metrics
+- **🔒 Type Safe** - Full type hints and Pydantic integration
+
+### Design intent: dual ownership
+
+pgdbm is designed so a module can either:
+- **Own its database** when run independently (it creates a pool and runs its own migrations), or
+- **Use a database owned by another** component via a shared pool while still running its own migrations into a schema namespace.
+
+This keeps modules portable: the same code can run as a standalone service or as part of a larger app.
+
+## Installation
+
+```bash
+# Install using uv (recommended)
+uv add pgdbm
+
+# Or using pip
+pip install pgdbm
+```
+
+## Quick Start
+
+### 1. Create a migration file
+
+```sql
+-- migrations/001_initial.sql
+CREATE TABLE IF NOT EXISTS {{tables.users}} (
+    id SERIAL PRIMARY KEY,
+    email VARCHAR(255) UNIQUE NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### 2. Use pgdbm
+
+```python
+from pgdbm import AsyncDatabaseManager, DatabaseConfig, AsyncMigrationManager
+
+# Configure and connect
+config = DatabaseConfig(
+    host="localhost",
+    database="myapp",
+    user="postgres",
+    password="secret"
+)
+
+db = AsyncDatabaseManager(config)
+await db.connect()
+
+# Apply migrations
+migrations = AsyncMigrationManager(db, migrations_path="./migrations")
+await migrations.apply_pending()
+
+# Use your database
+user_id = await db.execute_and_return_id(
+    "INSERT INTO {{tables.users}} (email) VALUES ($1)",
+    "user@example.com"
+)
+
+# Clean up
+await db.disconnect()
+```
+
+Standalone vs shared-pool usage:
+
+```python
+# Standalone (owns the DB):
+config = DatabaseConfig(connection_string="postgresql://localhost/app", schema="users")
+db = AsyncDatabaseManager(config)
+await db.connect()
+await AsyncMigrationManager(db, "./migrations", module_name="users").apply_pending()
+
+# Shared pool (uses external DB):
+shared = await AsyncDatabaseManager.create_shared_pool(DatabaseConfig(connection_string="postgresql://localhost/app"))
+db = AsyncDatabaseManager(pool=shared, schema="users")  # Module still runs its own migrations
+await AsyncMigrationManager(db, "./migrations", module_name="users").apply_pending()
+```
+
+## Core Patterns
+
+### 1. Migration Management
+
+pgdbm includes a built-in migration system:
+
+```python
+# Apply all pending migrations
+migrations = AsyncMigrationManager(db, migrations_path="./migrations")
+result = await migrations.apply_pending()
+
+# Check what was applied
+for migration in result['applied']:
+    print(f"Applied {migration['filename']} in {migration['execution_time_ms']}ms")
+```
+
+Migrations are automatically ordered by version number extracted from filenames.
+
+### 2. Module Isolation
+
+When multiple modules share a database, use schemas to prevent table conflicts:
+
+```python
+# Each module can get its own schema
+user_db = AsyncDatabaseManager(
+    config=DatabaseConfig(database="app", schema="user_module")
+)
+blog_db = AsyncDatabaseManager(
+    config=DatabaseConfig(database="app", schema="blog_module")
+)
+
+# Both can have a "users" table without conflict:
+# - user_module.users
+# - blog_module.users
+```
+
+The `{{tables.tablename}}` syntax in queries automatically expands to the correct schema-qualified name.
+
+### 3. Connection Pool Sharing
+
+For applications with multiple services sharing a database:
+
+```python
+# Create shared pool
+shared_pool = await AsyncDatabaseManager.create_shared_pool(config)
+
+# Each service gets its own schema but shares connections
+user_db = AsyncDatabaseManager(pool=shared_pool, schema="users")
+billing_db = AsyncDatabaseManager(pool=shared_pool, schema="billing")
+```
+
+### 4. Testing Support
+
+Built-in fixtures for database tests:
+
+```python
+# conftest.py
+from pgdbm.fixtures.conftest import *
+
+# test_users.py
+async def test_create_user(test_db):
+    # Automatic test database with cleanup
+    await test_db.execute("""
+        CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT)
+    """)
+
+    user_id = await test_db.execute_and_return_id(
+        "INSERT INTO users (email) VALUES ($1)",
+        "test@example.com"
+    )
+    assert user_id == 1
+```
+
+### 5. Monitoring
+
+Track database performance:
+
+```python
+from pgdbm import MonitoredAsyncDatabaseManager
+
+db = MonitoredAsyncDatabaseManager(
+    config=config,
+    slow_query_threshold_ms=100  # Log queries over 100ms
+)
+
+# Get metrics
+metrics = await db.get_query_metrics()
+slow_queries = await db.get_slow_queries(limit=10)
+```
+
+### 6. Production TLS and Timeouts
+
+Enable TLS with certificate verification and enforce server-side timeouts:
+
+```python
+from pgdbm import AsyncDatabaseManager, DatabaseConfig
+
+config = DatabaseConfig(
+    connection_string="postgresql://db.example.com/app",
+    ssl_enabled=True,
+    ssl_mode="verify-full",           # 'require' | 'verify-ca' | 'verify-full'
+    ssl_ca_file="/etc/ssl/certs/ca.pem",
+    # Optional mutual TLS:
+    # ssl_cert_file="/etc/ssl/certs/client.crt",
+    # ssl_key_file="/etc/ssl/private/client.key",
+
+    # Sensible timeouts (ms)
+    statement_timeout_ms=60_000,
+    idle_in_transaction_session_timeout_ms=60_000,
+    lock_timeout_ms=5_000,
+)
+
+db = AsyncDatabaseManager(config)
+await db.connect()
+```
+
+Notes:
+- Use `verify-full` for strict hostname and certificate validation in production.
+- Timeouts are applied via `server_settings`; you can override or disable by passing None.
+
+## Examples
+
+The `examples/` directory contains applications:
+
+- **todo-app/** - REST API with migrations, testing, and error handling
+- **saas-app/** - Multi-tenant SaaS application
+- **microservices/** - Multiple services sharing a connection pool
+
+## Documentation
+
+- [Quickstart Guide](docs/quickstart.md) - Get started
+- [Patterns Guide](docs/patterns.md) - Deployment patterns, schema isolation, and framework integration
+- [Migration Guide](docs/migrations.md) - Schema versioning and {{tables.}} syntax
+- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Testing Guide](docs/testing.md) - Testing best practices
+
+## Contributing
+
+Short version:
+
+- Requirements: Python 3.9+, PostgreSQL 12+, uv (or pip)
+- Setup:
+  - uv: `uv sync`
+  - pip: `pip install -e ".[dev]"`
+  - hooks: `pre-commit install`
+- Run tests: `pytest`
+- Lint/type-check: `pre-commit run --all-files`
+
+Notes:
+
+- Integration tests use ephemeral databases; you can override with env vars like `TEST_DB_HOST`, `TEST_DB_PORT`, `TEST_DB_USER`, `TEST_DB_PASSWORD`.
+- Keep PRs small and focused, include tests/docs for user-visible changes.
+- Style is enforced via Black/Isort/Ruff/Mypy; run pre-commit locally before pushing.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.