Metadata-Version: 2.5
Name: dbt-data-contracts
Version: 0.1.0
Summary: A lightweight data contract control plane for multi-repository dbt ecosystems
Author: dbt_contracts contributors
License: MIT
License-File: LICENSE
Keywords: ci-cd,data-contracts,data-mesh,dbt,semver
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: semver>=3.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Description-Content-Type: text/markdown

# dbt_contracts

> A lightweight **data contract control plane** for multi-repository dbt ecosystems.

dbt model contracts validate what a model publishes internally, but in a multi-repository data-product ecosystem, producers also need to know whether proposed interface changes violate downstream consumer expectations without cloning or rebuilding downstream repositories in CI.

`dbt_contracts` provides:

- **Canonical Data Contracts**: Infrastructure-independent contract models with column schemas, types, nullability, and provenance.
- **dbt Artifact Ingestion**: Automatic extraction of public data models from dbt `manifest.json`.
- **Central Contract Registry**: SQLite-based (and extensible) registry storing immutable contract history and consumer declarations.
- **Explicit Consumer Expectations**: Downstream teams declare version ranges and required columns in simple YAML.
- **SemVer Compatibility Engine**: Deterministic classification of changes as `PATCH`, `MINOR`, `MAJOR`, or `UNKNOWN`.
- **Consumer Impact Analysis**: Identify which specific consumers and models will break when an interface changes.
- **CI PR Gates**: Producer CI runs `dbt-contracts check` with standardized exit codes (`0` = valid, `1` = breaking gate failure, `2` = error).
- **Organization-Scale Discovery**: Scan Azure DevOps organizations to discover dbt projects and consumer contracts without cloning.

---

## Architecture

```text
dbt artifacts / repository metadata
              |
              v
      Discovery & Ingestion
              |
              v
    Canonical Contract Model
              |
      +-------+---------+
      |                 |
      v                 v
Contract Registry   Compatibility Engine
      |                 |
      +--------+--------+
               |
               v
        Consumer Impact
               |
               v
            CI Gate
```

---

## Installation

```bash
pip install dbt-data-contracts
```

For development:

```bash
git clone https://github.com/your-org/dbt_contracts.git
cd dbt_contracts
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\Activate.ps1 on Windows
pip install -e ".[dev]"
```

---

## Quickstart & CLI Usage

### 1. Ingest contracts from a dbt manifest

Inspect public contracts discovered in a dbt manifest:

```bash
dbt-contracts ingest --manifest target/manifest.json
```

### 2. Publish a contract version to the registry

Publish contracts for public dbt models (e.g. `1.0.0`):

```bash
dbt-contracts publish \
  --manifest target/manifest.json \
  --version 1.0.0 \
  --registry .contracts.db
```

### 3. Register a downstream consumer expectation

Downstream consumers define `data-contract-consumers.yml`:

```yaml
consumer: finance

dependencies:
  - product: orders
    model: fct_orders
    version: "^1.0.0"
    expectations:
      columns:
        order_id:
          data_type: bigint
          required: true
        amount:
          data_type: numeric
          required: true
```

Register the expectation in the central registry:

```bash
dbt-contracts consumer register \
  --file data-contract-consumers.yml \
  --registry .contracts.db
```

### 4. Check proposed changes in Producer CI

In producer pull request pipelines, test proposed contracts against published contracts and registered consumers:

```bash
dbt-contracts check \
  --manifest target/manifest.json \
  --proposed-version 1.1.0 \
  --registry .contracts.db
```

If a breaking change is detected (e.g., removing `amount` while `finance` requires it), the command outputs a detailed impact report and exits with code `1`:

```text
BREAKING CHANGE DETECTED: orders.fct_orders

Proposed: 1.1.0 (Current: 1.0.0)
Severity: MAJOR

Breaking changes:
  - Column 'amount' was removed

Affected consumers:
  - finance (expects 'amount: numeric', pinned to ^1.0.0)

SemVer Validation:
  FAIL: Breaking changes require a MAJOR version bump (expected >= 2.0.0).
```

If the proposed version is updated to `2.0.0`:

```bash
dbt-contracts check \
  --manifest target/manifest.json \
  --proposed-version 2.0.0 \
  --registry .contracts.db
```

The check passes with exit code `0`, confirming that `1.0.0` remains intact for existing consumers while `2.0.0` introduces the new breaking contract.

---

## Development & Validation

Run all checks:

```bash
pytest
ruff check .
ruff format --check .
mypy src tests
```

Or run the dev check script:

```bash
./scripts/dev-check.sh
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.
