Imported from JustPersy/Gestor-DB (AGENTS.md). Install upstream with npx skills add JustPersy/Gestor-DB. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

Source lives in schema_sync/: CLI entrypoints in schema_sync/cli/, core diff and DDL logic under schema_sync/core/, and shared helpers in schema_sync/utils/. Test coverage sits in tests/ with fast unit cases and an optional PostgreSQL integration suite. Example JSON specs for local experiments are in examples/. Python packaging metadata and dependency pins reside in pyproject.toml and requirements.txt.

Build, Test, and Development Commands

Create an isolated environment, install deps, and activate tools:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run schema sync against a spec once PG_DSN is configured:

python -m schema_sync.cli.main --json examples/spec.json --dsn "$PG_DSN" --dry-run

Execute the full test suite with pytest; skip integration tests when PostgreSQL is unavailable via pytest -m "not integration".

Coding Style & Naming Conventions

Follow PEP 8 with four-space indentation, descriptive snake_case for functions and modules, and UpperCamelCase for classes. Keep functions small, type hinted, and document non-obvious branches with concise comments. Prefer explicit imports from sibling packages (e.g., from schema_sync.core import ...) and log through schema_sync.utils.logger.get_logger for consistent output.

Testing Guidelines

Use pytest for all new code. Place fast unit tests alongside peers in tests/ and mark database-dependent scenarios with @pytest.mark.integration so they are easy to filter. When adding features, supply both a minimal specification fixture and assertions on generated DDL or introspection results. Ensure integration tests clean up temporary schemas/tables when they manipulate Postgres.

Commit & Pull Request Guidelines

This snapshot does not ship with Git history; mirror the existing tone by writing imperative, succinct commit subjects (e.g., feat: add widening diff guard). Group related changes per commit and include brief context in the body when behavior shifts. Pull requests should link any tracking issue, explain schema impacts, list verification commands (tests run, sample CLI invocations), and, when applicable, mention required environment variables or screenshots of CLI output.

Environment & Secrets

Copy .env.example to .env and populate PG_DSN and SPEC_PATH. Never commit credentials; rely on local env files or CI secrets. Use --dry-run during validation to avoid unintended production DDL.