driftbrake 0.0.1__tar.gz

driftbrake-0.0.1/.gitignore

@@ -0,0 +1,40 @@
+
+__pycache__/
+*.py[cod]
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+.env
+.venv
+venv/
+ENV/
+
+*.env
+*.db
+*.sqlite
+credentials.json
+secrets.json
+
+.vscode/
+.idea/
+*.swp
+
+.DS_Store
+Thumbs.db
+
+*.log
+logs/
+
+*.tmp
+temp/
+tmp/
+
+*.bak
+*.backup
+
+uv.lock
+examples/
+testes/

driftbrake-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuri Pontes
+
+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.

driftbrake-0.0.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: driftbrake
+Version: 0.0.1
+Summary: Detect, classify, and block schema drift in PostgreSQL before your pipelines break
+Project-URL: Homepage, https://github.com/yurivski/driftbrake
+Project-URL: Repository, https://github.com/yurivski/driftbrake
+Project-URL: Issues, https://github.com/yurivski/driftbrake/issues
+Project-URL: Changelog, https://github.com/yurivski/driftbrake/blob/main/CHANGELOG.md
+Author-email: Yuri Pontes <yurilbrok23@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: contract-testing,data-engineering,database,postgresql,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlalchemy<3.0,>=2.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+```text
+DriftBrake
+==========
+
+DriftBrake is a Python tool that validates schema contracts before data pipelines run.
+
+It reads the current PostgreSQL schema automatically, compares it against a versioned
+contract, classifies changes by impact (BREAKING, WARNING, SAFE), and blocks pipelines
+when incompatible changes are detected, before they cause failures in production.
+
+
+The tool
+========
+
+  DriftBrake is not a migration tool. It does not apply changes to the database and does
+  not generate SQL scripts.
+
+  It runs BEFORE pipelines, verifying that the actual database still respects the
+  contract expected by its data consumers.
+
+
+Example
+=======
+
+  Data pipelines fail silently when the database schema changes without warning:
+
+  - column removed or renamed
+  - data type altered
+  - NOT NULL added without a default
+  - foreign key modified
+
+  This tool runs an automatic validation before the pipeline starts and blocks the
+  execution if the database is no longer compatible with the expected contract.
+
+  Usage:
+
+    driftbrake init     # creates the schema.lock.json contract
+    driftbrake check    # checks whether the database has changed
+    driftbrake diff     # compares two states without touching the contract
+
+
+Documentation
+=============
+
+  - DOCUMENTATION.md - https://github.com/yurivski/driftbrake/blob/main/DOCUMENTATION.md
+  - CHANGELOG.md - https://github.com/yurivski/driftbrake/blob/main/CHANGELOG.md
+  - YML file - https://github.com/yurivski/driftbrake/blob/main/driftbrake.example.yml
+```

driftbrake-0.0.1/README.md

@@ -0,0 +1,48 @@
+```text
+DriftBrake
+==========
+
+DriftBrake is a Python tool that validates schema contracts before data pipelines run.
+
+It reads the current PostgreSQL schema automatically, compares it against a versioned
+contract, classifies changes by impact (BREAKING, WARNING, SAFE), and blocks pipelines
+when incompatible changes are detected, before they cause failures in production.
+
+
+The tool
+========
+
+  DriftBrake is not a migration tool. It does not apply changes to the database and does
+  not generate SQL scripts.
+
+  It runs BEFORE pipelines, verifying that the actual database still respects the
+  contract expected by its data consumers.
+
+
+Example
+=======
+
+  Data pipelines fail silently when the database schema changes without warning:
+
+  - column removed or renamed
+  - data type altered
+  - NOT NULL added without a default
+  - foreign key modified
+
+  This tool runs an automatic validation before the pipeline starts and blocks the
+  execution if the database is no longer compatible with the expected contract.
+
+  Usage:
+
+    driftbrake init     # creates the schema.lock.json contract
+    driftbrake check    # checks whether the database has changed
+    driftbrake diff     # compares two states without touching the contract
+
+
+Documentation
+=============
+
+  - DOCUMENTATION.md - https://github.com/yurivski/driftbrake/blob/main/DOCUMENTATION.md
+  - CHANGELOG.md - https://github.com/yurivski/driftbrake/blob/main/CHANGELOG.md
+  - YML file - https://github.com/yurivski/driftbrake/blob/main/driftbrake.example.yml
+```

driftbrake-0.0.1/driftbrake.example.yml

@@ -0,0 +1,51 @@
+# driftbrake.example.yml
+# Copie este arquivo para driftbrake.yml e personalize conforme necessário.
+#
+# Este arquivo controla como o DriftBrake compara schemas, quais
+# níveis de severidade causam falhas e quais tabelas/colunas ignorar.
+
+# Níveis de severidade que causam código de saída não-zero (falha).
+# Valores possíveis: BREAKING, WARNING, SAFE
+fail_on:
+  - BREAKING
+
+# Níveis de severidade que emitem avisos (mas não causam falha por padrão).
+warn_on:
+  - WARNING
+
+# Filtragem de schemas
+schemas:
+  # Comparar apenas estes schemas (deixe vazio para incluir todos)
+  include:
+    - public
+  # Excluir estes schemas da comparação
+  exclude: []
+
+# Filtragem de tabelas
+tables:
+  # Ignorar completamente estas tabelas (nenhuma comparação realizada)
+  ignore:
+    - alembic_version
+    - django_migrations
+    - flyway_schema_history
+
+# Filtragem de colunas
+columns:
+  # Ignorar colunas específicas por tabela (padrões glob suportados)
+  ignore:
+    # Ignorar 'updated_at' em todas as tabelas que correspondem a 'orders*'
+    orders:
+      - updated_at
+      - created_at
+    customers:
+      - last_login
+
+# Sobrescritas de regras personalizadas
+# Estas substituem a classificação padrão para tipos específicos de alteração.
+rules:
+  # Tratar alterações de posição ordinal como SAFE em vez de WARNING
+  ordinal_position_changed: SAFE
+  # Tratar alterações de valor padrão como WARNING (comportamento padrão)
+  default_changed: WARNING
+  # Tratar alterações de restrição unique como SAFE
+  # unique_changed: SAFE

driftbrake-0.0.1/pyproject.toml

@@ -0,0 +1,119 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "driftbrake"
+version = "0.0.1"
+description = "Detect, classify, and block schema drift in PostgreSQL before your pipelines break"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Yuri Pontes", email = "yurilbrok23@gmail.com" },
+]
+keywords = ["schema", "database", "data-engineering", "postgresql", "contract-testing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "sqlalchemy>=2.0,<3.0",
+    "python-dotenv>=1.0",
+    "pyyaml>=6.0",
+    "jinja2>=3.0",
+    "rich>=13.0",
+    "typer>=0.9",
+]
+
+[project.optional-dependencies]
+postgres = ["psycopg2-binary>=2.9"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "ruff",
+    "mypy",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/yurivski/driftbrake"
+Repository = "https://github.com/yurivski/driftbrake"
+Issues = "https://github.com/yurivski/driftbrake/issues"
+Changelog = "https://github.com/yurivski/driftbrake/blob/main/CHANGELOG.md"
+
+[project.scripts]
+driftbrake = "driftbrake.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/driftbrake"]
+
+[tool.hatch.build]
+exclude = [
+    # venvs
+    ".venv*",
+    "venv",
+    
+    ".git",
+    ".github",
+    
+    ".gitignore",
+    ".gitattributes",
+    ".claude",
+    ".vscode",
+    ".idea",
+    
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    "__pycache__",
+    "*.pyc",
+    "*.pyo",
+    
+    "dist",
+    "build",
+    "*.egg-info",
+    
+    "tests",
+    "examples",
+    "imagens",
+    "fonte",
+    "DOCUMENTATION.md",
+    "CHANGELOG.md",
+    "Makefile",
+    "schema.lock.json",
+    
+    "uv.lock",
+    "requirements.txt",
+    
+    ".env",
+    ".env.*",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+strict = false
+ignore_missing_imports = true

driftbrake-0.0.1/src/driftbrake/__init__.py

@@ -0,0 +1,64 @@
+"""
+DriftBrake
+=========
+
+A schema contract guard for data pipelines.
+Detects, classifies, and reports schema changes in PostgreSQL databases.
+
+Quick start:
+    from driftbrake import SchemaGuard
+
+    SchemaGuard.from_env(
+        contract_path="schema.lock.json",
+        fail_on=["BREAKING"],
+    ).assert_compatible()
+"""
+
+from driftbrake.classifiers.impact_classifier import ImpactClassifier
+from driftbrake.comparators.schema_comparator import SchemaComparator
+from driftbrake.exceptions import (
+    BreakingSchemaChangeError,
+    ConfigurationError,
+    SchemaConnectionError,
+    SchemaContractNotFoundError,
+    SchemaDetectorError,
+)
+from driftbrake.guard import SchemaGuard
+from driftbrake.models import (
+    ChangeType,
+    ColumnSchema,
+    DatabaseSchema,
+    DiffResult,
+    SchemaChange,
+    Severity,
+    TableSchema,
+)
+from driftbrake.readers.json_reader import JsonSchemaReader
+from driftbrake.readers.postgres import PostgresSchemaReader
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # High-level API
+    "SchemaGuard",
+    # Comparators and classifiers
+    "SchemaComparator",
+    "ImpactClassifier",
+    # Readers
+    "PostgresSchemaReader",
+    "JsonSchemaReader",
+    # Models
+    "DatabaseSchema",
+    "TableSchema",
+    "ColumnSchema",
+    "SchemaChange",
+    "DiffResult",
+    "Severity",
+    "ChangeType",
+    # Exceptions
+    "SchemaDetectorError",
+    "SchemaContractNotFoundError",
+    "SchemaConnectionError",
+    "BreakingSchemaChangeError",
+    "ConfigurationError",
+]

driftbrake-0.0.1/src/driftbrake/classifiers/__init__.py

@@ -0,0 +1,4 @@
+from driftbrake.classifiers.impact_classifier import ImpactClassifier
+from driftbrake.classifiers.type_compatibility import classify_type_change
+
+__all__ = ["ImpactClassifier", "classify_type_change"]

driftbrake-0.0.1/src/driftbrake/classifiers/impact_classifier.py

@@ -0,0 +1,107 @@
+# Classificador de impacto para alterações de schema.
+
+from __future__ import annotations
+
+from driftbrake.classifiers.type_compatibility import classify_type_change
+from driftbrake.models import ChangeType, ColumnSchema, SchemaChange, Severity
+
+
+class ImpactClassifier:
+    """
+    - Objetos removidos são sempre BREAKING.
+    - Colunas nullable adicionadas são SAFE.
+    - Colunas NOT NULL adicionadas sem default são BREAKING.
+    - Alterações de tipo são avaliadas pela matriz de compatibilidade de tipos.
+    """
+
+    def __init__(self, custom_rules: dict | None = None) -> None:
+        self.custom_rules = custom_rules or {}
+
+    def classify_table_added(self, schema: str, table: str) -> Severity:
+        return Severity.SAFE
+
+    def classify_table_removed(self, schema: str, table: str) -> Severity:
+        return Severity.BREAKING
+
+    def classify_column_added(self, column: ColumnSchema) -> Severity:
+        """
+        - Adicionada nullable: SAFE
+        - Adicionada NOT NULL com default: WARNING
+        - Adicionada NOT NULL sem default: BREAKING
+        """
+        if column.nullable:
+            return Severity.SAFE
+        if column.default is not None:
+            return Severity.WARNING
+        return Severity.BREAKING
+
+    def classify_column_removed(self, column_name: str) -> Severity:
+        return Severity.BREAKING
+
+    def classify_type_change(self, old_type: str, new_type: str) -> Severity:
+        return classify_type_change(old_type, new_type)
+
+    def classify_nullable_change(self, old_nullable: bool, new_nullable: bool) -> Severity:
+        if not old_nullable and new_nullable:
+            # NOT NULL removido -> nullable permitido: WARNING (afrouxamento)
+            return Severity.WARNING
+        if old_nullable and not new_nullable:
+            # nullable removido -> NOT NULL adicionado: BREAKING
+            return Severity.BREAKING
+        return Severity.SAFE
+
+    def classify_default_change(self, old_default: object, new_default: object) -> Severity:
+        return Severity.WARNING
+
+    def classify_primary_key_change(self, old_pk: bool, new_pk: bool) -> Severity:
+        return Severity.BREAKING
+
+    def classify_unique_change(self, old_unique: bool, new_unique: bool) -> Severity:
+        return Severity.WARNING
+
+    def classify_foreign_key_change(
+        self, old_fk: list, new_fk: list
+    ) -> Severity:
+        old_has = bool(old_fk)
+        new_has = bool(new_fk)
+        if not old_has and new_has:
+            # FK adicionada
+            return Severity.WARNING
+        # FK alterada ou removida
+        return Severity.BREAKING
+
+    def classify_ordinal_position_change(
+        self, old_pos: int, new_pos: int
+    ) -> Severity:
+        return Severity.WARNING
+
+    def classify_possible_rename(
+        self, removed_col: str, added_col: str
+    ) -> Severity:
+        return Severity.WARNING
+
+    def build_change(
+        self,
+        change_type: ChangeType,
+        severity: Severity,
+        schema_name: str,
+        table_name: str,
+        column_name: str | None,
+        field_name: str | None,
+        old_value: object,
+        new_value: object,
+        description: str,
+        suggestion: str | None = None,
+    ) -> SchemaChange:
+        return SchemaChange(
+            change_type=change_type,
+            severity=severity,
+            schema_name=schema_name,
+            table_name=table_name,
+            column_name=column_name,
+            field_name=field_name,
+            old_value=old_value,
+            new_value=new_value,
+            description=description,
+            suggestion=suggestion,
+        )

driftbrake-0.0.1/src/driftbrake/classifiers/type_compatibility.py

@@ -0,0 +1,117 @@
+"""
+Matriz de compatibilidade de tipos PostgreSQL.
+
+Classifica alterações de tipo como SAFE, WARNING ou BREAKING com base nas
+regras de coerção e cast implícito do PostgreSQL.
+"""
+
+from __future__ import annotations
+
+import re
+
+from driftbrake.models import Severity
+
+# Regras de compatibilidade explícitas como triplas (from_pattern, to_pattern, severity).
+# Os padrões são comparados sem diferenciação de maiúsculas usando substring ou regex.
+_COMPAT_RULES: list[tuple[str, str, Severity]] = [
+    # Expansões de VARCHAR: seguro
+    ("varchar", "text", Severity.SAFE),
+    ("character varying", "text", Severity.SAFE),
+
+    # Alargamento numérico: seguro (tipos menores promovidos)
+    ("smallint", "integer", Severity.SAFE),
+    ("smallint", "bigint", Severity.SAFE),
+    ("real", "double precision", Severity.SAFE),
+
+    # Estreitamento numérico: crítico
+    ("bigint", "integer", Severity.BREAKING),
+    ("bigint", "smallint", Severity.BREAKING),
+    ("integer", "smallint", Severity.BREAKING),
+    ("double precision", "real", Severity.BREAKING),
+
+    # integer -> bigint: aviso (alargamento, mas pode afetar o comportamento da app / tipos ORM)
+    ("integer", "bigint", Severity.WARNING),
+
+    # Data/hora: date -> timestamp é aviso (sem perda de dados, mas semântica muda)
+    ("date", "timestamp", Severity.WARNING),
+    ("timestamp", "date", Severity.BREAKING),
+    ("timestamp", "timestamptz", Severity.WARNING),
+    ("timestamptz", "timestamp", Severity.WARNING),
+
+    # Estreitamento de text/varchar: crítico
+    ("text", "varchar", Severity.BREAKING),
+    ("text", "character varying", Severity.BREAKING),
+    ("text", "numeric", Severity.BREAKING),
+    ("text", "integer", Severity.BREAKING),
+    ("text", "bigint", Severity.BREAKING),
+
+    # numeric para text: crítico
+    ("numeric", "text", Severity.BREAKING),
+    ("integer", "text", Severity.WARNING),
+    ("bigint", "text", Severity.WARNING),
+
+    # Alterações de boolean: crítico
+    ("boolean", "integer", Severity.BREAKING),
+    ("integer", "boolean", Severity.BREAKING),
+]
+
+
+def _normalize_type(type_str: str) -> str:
+    # Normaliza a string de tipo para comparação: minúsculas e sem espaços extras.
+    return type_str.strip().lower()
+
+
+def _extract_varchar_length(type_str: str) -> int | None:
+    # Extrai o comprimento de VARCHAR(n) ou CHARACTER VARYING(n).
+    match = re.search(r"(?:varchar|character varying)\s*\((\d+)\)", type_str, re.IGNORECASE)
+    if match:
+        return int(match.group(1))
+    return None
+
+
+def _extract_numeric_precision(type_str: str) -> tuple[int, int] | None:
+    # Extrai (precisão, escala) de NUMERIC(p, s) ou DECIMAL(p, s).
+    match = re.search(r"(?:numeric|decimal)\s*\((\d+)\s*,\s*(\d+)\)", type_str, re.IGNORECASE)
+    if match:
+        return int(match.group(1)), int(match.group(2))
+    return None
+
+
+def classify_type_change(old_type: str, new_type: str) -> Severity:
+    # Classifica uma alteração de tipo de coluna como SAFE, WARNING ou BREAKING.
+    if _normalize_type(old_type) == _normalize_type(new_type):
+        return Severity.SAFE
+
+    old_norm = _normalize_type(old_type)
+    new_norm = _normalize_type(new_type)
+
+    # Regras de VARCHAR(n) -> VARCHAR(m)
+    old_len = _extract_varchar_length(old_norm)
+    new_len = _extract_varchar_length(new_norm)
+    if old_len is not None and new_len is not None:
+        if new_len >= old_len:
+            return Severity.SAFE
+        return Severity.BREAKING
+
+    # VARCHAR(n) -> TEXT: seguro
+    if old_len is not None and "text" in new_norm:
+        return Severity.SAFE
+
+    # NUMERIC(p1,s) -> NUMERIC(p2,s): seguro se p2 >= p1
+    old_num = _extract_numeric_precision(old_norm)
+    new_num = _extract_numeric_precision(new_norm)
+    if old_num is not None and new_num is not None:
+        old_prec, old_scale = old_num
+        new_prec, new_scale = new_num
+        if new_scale == old_scale and new_prec >= old_prec:
+            return Severity.SAFE
+        if new_prec < old_prec or new_scale != old_scale:
+            return Severity.BREAKING
+
+    # Aplica regras explícitas (verifica se a substring está contida)
+    for from_pat, to_pat, severity in _COMPAT_RULES:
+        if from_pat in old_norm and to_pat in new_norm:
+            return severity
+
+    # Padrão: alteração de tipo desconhecida é BREAKING (conservador)
+    return Severity.BREAKING