sqlmodel-pg-kit/AGENTS.md

AGENTS.md

This file contains configuration and guidelines for AI agents working on this project.

Project Overview

sqlmodel-pg-kit is a reusable SQLModel + PostgreSQL toolkit providing:

• Database configuration and connection management (sync/async)
• Generic CRUD repositories for common operations
• CSV import utilities for automatic model generation
• Example workflows for cheminformatics use cases

Testing Commands

After making changes to the code, run these commands to verify:

Fast smoke tests (SQLite only)

make test-sqlite

Full test suite (includes Postgres integration if env vars set)

make test

Postgres integration tests

# Requires environment variables: SQL_HOST, SQL_PORT, SQL_USER, SQL_PASSWORD, SQL_DATABASE, SQL_SSLMODE
make test-pg

Run across multiple Python versions (3.10-3.13)

make test-pg-once

Code Style

• No comments in code (unless explicitly requested)
• Follow existing patterns in the codebase
• Use existing libraries and utilities before adding new dependencies
• Check pyproject.toml for dependencies already available

Key Files

Core Library

• src/sqlmodel_pg_kit/config.py - DatabaseConfig dataclass
• src/sqlmodel_pg_kit/db.py - Engine and session management
• src/sqlmodel_pg_kit/crud.py - Repository and AsyncRepository classes
• src/sqlmodel_pg_kit/csv_import.py - CSV to SQLModel utilities

Examples

• examples/01_sync_crud.py - Basic CRUD operations
• examples/02_bulk_and_filters.py - Bulk insert and filtering
• examples/03_relationships.py - Model relationships
• examples/04_async_crud.py - Async CRUD operations
• examples/05_cheminformatics.py - Cheminformatics use case
• examples/06_csv_to_sqlmodel.py - CSV import workflow

Tests

• tests/test_smoke.py - Fast SQLite tests
• tests/test_pg_integration.py - Postgres integration tests

Database Setup

For local development with Docker:

make db-up    # Start Postgres
make db-down  # Stop Postgres
make db-logs  # View logs

Environment variables (for Postgres):

export SQL_HOST=127.0.0.1
export SQL_PORT=5432
export SQL_USER=postgres
export SQL_PASSWORD=change-me-strong
export SQL_DATABASE=appdb
export SQL_SSLMODE=disable

Common Workflows

Adding a new CRUD operation

1. Add method to Repository or AsyncRepository in src/sqlmodel_pg_kit/crud.py
2. Update __all__ exports in src/sqlmodel_pg_kit/__init__.py if exposing publicly
3. Add test in tests/test_smoke.py (SQLite) or tests/test_pg_integration.py (Postgres)
4. Run make test-sqlite to verify

Adding CSV import features

1. Modify src/sqlmodel_pg_kit/csv_import.py
2. Add example in examples/06_csv_to_sqlmodel.py or create new example
3. Test with: uv run python examples/06_csv_to_sqlmodel.py --csv ./data/molecules.csv --sqlite ./demo.db

Running examples

make examples

Build and Package

• Build: uv build
• Publish to PyPI: uv publish
• Build conda package: conda build conda/

Important Notes

• SQLite in-memory is used for fast smoke tests
• Postgres is recommended for production and integration tests
• The project uses uv for dependency management (PEP 621/517)
• All SQLModel models are registered in SQLModel.metadata for create_all()