Metadata-Version: 2.5
Name: ddl-stitch
Version: 1.0.0
Summary: Assemble un dossier de fichiers .sql (un objet SQL par fichier) en un unique fichier DDL PostgreSQL, ordonné selon le graphe des dépendances.
Project-URL: Homepage, https://gitlab.com/golomend/ddl-stitch
Project-URL: Documentation, https://golomend.gitlab.io/ddl-stitch/
Project-URL: Repository, https://gitlab.com/golomend/ddl-stitch
Project-URL: Issues, https://gitlab.com/golomend/ddl-stitch/-/issues
Project-URL: Changelog, https://gitlab.com/golomend/ddl-stitch/-/blob/main/CHANGELOG.md
Author: Guillaume Mangione
License-Expression: MIT
License-File: LICENSE
Keywords: ddl,dependency-graph,graphviz,mermaid,postgresql,schema,sql,sqlglot,topological-sort
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: French
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 :: Build Tools
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlglot>=30.22
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# ddl-stitch

[![pipeline](https://gitlab.com/golomend/ddl-stitch/badges/main/pipeline.svg)](https://gitlab.com/golomend/ddl-stitch/-/pipelines)
[![PyPI](https://img.shields.io/pypi/v/ddl-stitch)](https://pypi.org/project/ddl-stitch/)
[![Python](https://img.shields.io/pypi/pyversions/ddl-stitch)](https://pypi.org/project/ddl-stitch/)
[![licence](https://img.shields.io/badge/licence-MIT-blue)](https://gitlab.com/golomend/ddl-stitch/-/blob/main/LICENSE)
[![documentation](https://img.shields.io/badge/doc-golomend.gitlab.io-indigo)](https://golomend.gitlab.io/ddl-stitch/)

Assemble un dossier de fichiers `.sql` — **un objet SQL par fichier** — en un **unique
fichier DDL**, ordonné selon le **graphe des dépendances** des objets.

```
ddl/                                          schema.sql  (ordre calculé)
├── triggers/orders_audit.sql                 -- SCHEMA shop
├── views/order_summary.sql                   -- EXTENSION citext
├── tables/orders.sql          ddl-stitch     -- TYPE shop.order_status
├── tables/customers.sql      ───────────▶    -- TABLE shop.customers
├── types/order_status.sql        build       -- TABLE shop.orders   (FK -> customers)
├── extensions/citext.sql                     -- VIEW shop.order_summary
└── shop.sql                                  -- TRIGGER orders_audit ON shop.orders
```

Les dépendances sont **déduites du SQL** — clés étrangères, types utilisés, séquences et
fonctions appelées, tables lues par une vue, table et fonction d'un trigger — : aucun
ordre à déclarer, aucune numérotation de fichiers. Le texte de chaque fichier est
recopié **tel quel**, jamais réécrit.

📖 **Documentation complète : <https://golomend.gitlab.io/ddl-stitch/>**

## Installation

```bash
pip install ddl-stitch
```

Python 3.10 ou plus récent. Pour l'utiliser comme outil en ligne de commande isolé :
`pipx install ddl-stitch` ou `uv tool install ddl-stitch`.

## En bref

```bash
ddl-stitch build ddl -o schema.sql              # le DDL, dans l'ordre de création
ddl-stitch build ddl --dry-run                  # l'ordre et des statistiques, sans rien écrire
ddl-stitch build ddl --drop -o schema.sql       # un fichier rejouable (DROP … CASCADE en tête)
ddl-stitch build ddl --schema crm --with-deps   # une partie du schéma, autonome
ddl-stitch graph ddl                            # le graphe en Mermaid
ddl-stitch manifest ddl -o manifest.yaml        # le graphe en YAML (ou JSON)
```

```
$ ddl-stitch build examples/ddl -o schema.sql
4 objets assemblés -> schema.sql
```

Le graphe exporté pour les types, tables et vues du schéma `shop` de l'exemple
complet (`ddl-stitch graph tests/golden/boutique/input --schema shop --kind type
--kind table --kind view`) : une couleur par famille, la nature de chaque
dépendance sur sa flèche.

```mermaid
graph TD
    n1["TYPE shop.address"]:::type
    n2["DOMAIN shop.email"]:::type
    n3["TYPE shop.order_status"]:::type
    n4["TYPE shop.price_range"]:::type
    n5["TABLE shop.customers"]:::table
    n6["TABLE shop.products"]:::table
    n7["TABLE shop.orders"]:::table
    n8["ALTER TABLE shop.customers"]:::table
    n9["TABLE shop.order_lines"]:::table
    n10["MATERIALIZED VIEW shop.daily_sales"]:::view
    n11["VIEW shop.order_summary"]:::view
    n12["VIEW shop.best_customers"]:::view
    n1 -->|type| n5
    n2 -->|type| n5
    n4 -->|type| n6
    n3 -->|type| n7
    n5 -->|fk| n7
    n5 -->|alter| n8
    n7 -->|fk| n8
    n6 -->|fk| n9
    n7 -->|fk| n9
    n7 -->|view_ref| n10
    n5 -->|view_ref| n11
    n7 -->|view_ref| n11
    n11 -->|view_ref| n12
    classDef type fill:#fce4ec,stroke:#ec407a,stroke-width:1.5px,color:#1a1a1a
    classDef table fill:#e3f2fd,stroke:#1e88e5,stroke-width:1.5px,color:#1a1a1a
    classDef view fill:#e8f5e9,stroke:#43a047,stroke-width:1.5px,color:#1a1a1a
```

## Fonctionnalités

- **PostgreSQL** : schémas, extensions, types et domaines, séquences, fonctions et
  procédures, tables et `ALTER TABLE … ADD`, index, vues (y compris matérialisées),
  triggers, et les `COMMENT ON` qui les accompagnent.
- **Des erreurs claires**, toutes rapportées d'un coup : SQL invalide (avec ligne et
  colonne), cycle de dépendances (avec le remède), objet défini deux fois, objet absent
  du dossier. Un code de sortie par famille d'erreurs.
- **Objets absents du dossier** : avertir, échouer (`--missing strict`, pour la CI) ou
  déclarer ce qui existe déjà en base (`--external`).
- **Filtres** : par fichiers (`--include`, `--exclude`) ou par objets (`--schema`,
  `--kind`, `--with-deps`).
- **Exports du graphe** : manifest YAML / JSON (avec son JSON Schema), Mermaid, Graphviz
  DOT, DAG générique pour un orchestrateur.
- **Reproductible** : même dossier, même fichier, au caractère près.

Le détail de chaque fonctionnalité est dans la
[documentation](https://golomend.gitlab.io/ddl-stitch/), les évolutions dans le
[CHANGELOG](https://gitlab.com/golomend/ddl-stitch/-/blob/main/CHANGELOG.md).

## Développement

```bash
git clone https://gitlab.com/golomend/ddl-stitch.git
cd ddl-stitch
pip install -e . --group dev
pre-commit install          # ruff + mypy avant chaque commit
pytest
```

Les tests **golden** exécutent aussi le DDL produit sur une vraie base PostgreSQL, si
`DDL_STITCH_TEST_DSN` est définie (sinon, ils sont ignorés) :

```bash
docker run -d --rm --name ddl-stitch-pg -p 127.0.0.1:55432:5432 \
-e POSTGRES_USER=ddl \
-e POSTGRES_PASSWORD=ddl \
-e POSTGRES_DB=ddl_stitch postgres:16
export DDL_STITCH_TEST_DSN=postgresql://ddl:ddl@127.0.0.1:55432/ddl_stitch
pytest
```

Documentation du site : `pip install -e . --group docs`, puis `mkdocs serve`. Le
[wiki](https://gitlab.com/golomend/ddl-stitch/-/wikis/home) explique comment l'outil est
construit, et pourquoi.

La version est dérivée des tags git (`vX.Y.Z`) par `hatch-vcs` : aucun numéro n'est
écrit dans le code. Un tag de version déclenche la publication par la CI.

## Licence

[MIT](https://gitlab.com/golomend/ddl-stitch/-/blob/main/LICENSE).
