diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..6a45073 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,25 @@ +name: Parsing or layout problem +description: Report a reproducible SQL, rendering or installation problem. +body: + - type: textarea + id: environment + attributes: + label: Versions and environment + description: Include migration-erd --version, d2 --version, Python version and operating system. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Command and minimal input + description: Include the command, database dialect, and a small fictional SQL example. Remove company data, credentials and private paths. For layout issues, attach the resulting SVG if possible. + render: text + validations: + required: true + - type: textarea + id: result + attributes: + label: Expected and actual result + description: Describe the difference and include relevant terminal errors. + validations: + required: true diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index fdc0d4d..9477924 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -1,6 +1,30 @@ name: Check ERD generation -on: [push, pull_request] +on: + workflow_dispatch: + push: + branches: [main] + paths: + - "erd_generator/**" + - "tests/**" + - "requirements*.txt" + - "pyproject.toml" + - "MANIFEST.in" + - "Makefile" + - ".github/workflows/check.yml" + pull_request: + paths: + - "erd_generator/**" + - "tests/**" + - "requirements*.txt" + - "pyproject.toml" + - "MANIFEST.in" + - "Makefile" + - ".github/workflows/check.yml" + +concurrency: + group: check-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true permissions: contents: read diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 718f3a5..20259da 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -2,17 +2,31 @@ name: Publish project website on: workflow_dispatch: + pull_request: + paths: + - "site/**" + - "README.md" + - "dev_guide.md" + - "pyproject.toml" + - "erd_generator/__init__.py" + - "tests/unit/test_publication.py" + - ".github/workflows/pages.yml" push: branches: [main] paths: - "site/**" + - "README.md" + - "dev_guide.md" + - "pyproject.toml" + - "erd_generator/__init__.py" + - "tests/unit/test_publication.py" - ".github/workflows/pages.yml" permissions: contents: read concurrency: - group: pages + group: pages-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: false jobs: @@ -22,8 +36,16 @@ jobs: steps: - uses: actions/checkout@v7.0.1 with: - ref: main persist-credentials: false + - uses: actions/setup-python@v7.0.0 + with: + python-version: "3.11" + cache: pip + cache-dependency-path: requirements*.txt + - name: Check public URLs and metadata + run: | + python -m pip install -r requirements-dev.txt + python -m pytest -q tests/unit/test_publication.py - name: Fetch versioned illustration assets env: GH_TOKEN: ${{ github.token }} @@ -34,10 +56,13 @@ jobs: test -s site/assets/layout-after.svg test -s site/assets/layout-before.svg - uses: actions/configure-pages@v6.0.0 + if: github.event_name != 'pull_request' - uses: actions/upload-pages-artifact@v5.0.0 + if: github.event_name != 'pull_request' with: path: site/ deploy: + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' needs: build runs-on: ubuntu-24.04 timeout-minutes: 5 diff --git a/README.md b/README.md index 865ec64..0207b6b 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Migration ERD +# Database Migration ERD -**Readable PostgreSQL ER diagrams from migration SQL. No database connection required.** +**Readable ER diagrams from database migration SQL. No database connection required.** -[![64 fictional tables automatically arranged into six groups](https://github.com/fightingBald/database_migrate_UML_generator/releases/download/v0.2.0/layout-after.png)](https://github.com/fightingBald/database_migrate_UML_generator/releases/download/v0.2.0/layout-after.svg) +[![64 fictional tables automatically arranged into six groups](https://github.com/fightingBald/database-migration-erd/releases/download/v0.2.0/layout-after.png)](https://github.com/fightingBald/database-migration-erd/releases/download/v0.2.0/layout-after.svg) -64 dummy tables, six automatically inferred groups, default settings. [Before/after and tool comparison](https://fightingbald.github.io/database_migrate_UML_generator/) · [Download SVG](https://github.com/fightingBald/database_migrate_UML_generator/releases/download/v0.2.0/layout-after.svg) +64 dummy tables, six automatically inferred groups, default settings. [Before/after and tool comparison](https://fightingbald.github.io/database-migration-erd/) · [Download SVG](https://github.com/fightingBald/database-migration-erd/releases/download/v0.2.0/layout-after.svg) ## Why use it? @@ -13,14 +13,14 @@ - **Migration-aware input:** forward SQL changes, sql-migrate/goose Up sections and supported dollar-quoted `DO` blocks, processed locally without executing SQL. - **Fits codegen and CI:** one command, SVG-only output by default, meaningful exit codes and previous SVG preserved on failure. -Use it when migration files are your input and an automatically arranged ER diagram is your output. It does not apply migrations or model every PostgreSQL feature; see [SQL support](https://github.com/fightingBald/database_migrate_UML_generator/blob/main/dev_guide.md#sql-support-and-diagnostics). +**SQL support:** the parser currently uses the PostgreSQL dialect. Compatible SQL from other databases may work, but full MySQL, SQLite and SQL Server migration support is not verified. It reads SQL files, not ORM migration code, and never applies migrations. See [supported SQL and limitations](https://github.com/fightingBald/database-migration-erd/blob/main/dev_guide.md#sql-support-and-diagnostics). ## Install Requires **Python 3.11+**, [pipx](https://pipx.pypa.io/stable/installation/) and [D2 0.7.1](https://github.com/d2lang/d2/releases/tag/v0.7.1) on PATH. Install the versioned package from GitHub Releases: ```bash -pipx install https://github.com/fightingBald/database_migrate_UML_generator/releases/download/v0.2.0/migration_erd-0.2.0-py3-none-any.whl +pipx install https://github.com/fightingBald/database-migration-erd/releases/download/v0.2.1/migration_erd-0.2.1-py3-none-any.whl ``` ## Usage @@ -37,9 +37,11 @@ Errors appear in the terminal, with a nonzero exit code and the previous SVG pre | Option | Purpose | | --- | --- | -| `--fk-config file.yaml` | [Add relationships](https://github.com/fightingBald/database_migrate_UML_generator/blob/main/dev_guide.md#relationships-without-database-fk-constraints). | -| `--layout-config file.yaml` | [Set groups, titles and colours](https://github.com/fightingBald/database_migrate_UML_generator/blob/main/dev_guide.md#business-layout). | -| `--layout tala` | [Use TALA](https://github.com/fightingBald/database_migrate_UML_generator/blob/main/dev_guide.md#optional-tala-layout). | +| `--fk-config file.yaml` | [Add relationships](https://github.com/fightingBald/database-migration-erd/blob/main/dev_guide.md#relationships-without-database-fk-constraints). | +| `--layout-config file.yaml` | [Set groups, titles and colours](https://github.com/fightingBald/database-migration-erd/blob/main/dev_guide.md#business-layout). | +| `--layout tala` | [Use TALA](https://github.com/fightingBald/database-migration-erd/blob/main/dev_guide.md#optional-tala-layout). | | `--show-references` | Label cross-group FK targets beside fields. | -Run `migration-erd --help` for all options. The [developer guide](https://github.com/fightingBald/database_migrate_UML_generator/blob/main/dev_guide.md) covers source installation, copying into `tools/erd-generator/`, CI and development. `python -m erd_generator` remains available. +Run `migration-erd --help` for all options. The [developer guide](https://github.com/fightingBald/database-migration-erd/blob/main/dev_guide.md) covers source installation, copying into `tools/erd-generator/`, CI and development. `python -m erd_generator` remains available. + +Found a parsing or layout problem? [Report it with a small fictional SQL example](https://github.com/fightingBald/database-migration-erd/issues/new?template=bug_report.yml). diff --git a/dev_guide.md b/dev_guide.md index aa16729..6c5ce41 100644 --- a/dev_guide.md +++ b/dev_guide.md @@ -93,6 +93,8 @@ Intermediate layouts stay in memory; only final publication uses an atomic stagi ## SQL support and diagnostics +The project accepts SQL migration files rather than a specific migration framework. Its tokenizer, parser and SQL normalization currently use the PostgreSQL dialect; there is no dialect selector. Common SQL from other databases can be compatible, but that is not a guarantee for their complete migration syntax. MySQL backtick-quoted DDL and SQL Server bracket-quoted DDL with `GO` fail in current checks. SQLite-style `CREATE TABLE` can parse, but SQLite-specific migration behavior is not fully validated. ORM migration source code must first be exported to SQL. + Inputs are UTF-8. `V__description.sql` files use numeric version order; other SQL files use path order. sql-migrate/goose files read only Up sections; `.down.sql` files are skipped. | SQL | Handling | @@ -128,7 +130,7 @@ python -m build python -m twine check --strict dist/* ``` -CI checks Python 3.11/3.14. Rendering tests require D2 0.7.1; optional TALA tests skip without the plugin (`python -m pytest -q -m tala`). +Code CI checks Python 3.11/3.14 on Linux for runtime, test and build changes. Documentation and website edits use the lighter publication checks in `pages.yml`; the full check can also be run manually. Rendering tests require D2 0.7.1; optional TALA tests skip without the plugin (`python -m pytest -q -m tala`). Flow: SQL/FK YAML → Schema → D2 → render → optional cluster composition → verified SVG. Lower-level modules must not import the CLI. @@ -150,14 +152,14 @@ Configure [pending Trusted Publishers](https://docs.pypi.org/trusted-publishers/ | Field | Value | | --- | --- | | Project | `migration-erd` | -| GitHub owner / repository | `fightingBald` / `database_migrate_UML_generator` | +| GitHub owner / repository | `fightingBald` / `database-migration-erd` | | Workflow | `publish.yml` | | Environment | `pypi` or `testpypi`, matching the index | After CI passes for the release commit, create a matching `v` tag and GitHub Release. Run `gh workflow run publish.yml --ref v -f target=testpypi`, verify installation, then repeat with `target=pypi`. No upload token is stored in the repository. The workflow rejects a tag/version mismatch. Until PyPI is configured, use the wheel attached to the GitHub Release. -`site/` is a static project website. Its illustration files are downloaded from the pinned public GitHub Release during `pages.yml`; `site/assets/` and `dist/` stay ignored. Pages deploys website changes pushed to `main`; after publishing a Release, run `gh workflow run pages.yml --ref main`. Keep the Pages environment restricted to `main` and use GitHub Actions as its source. Verify image and package URLs without authentication before linking them in the README; draft Release assets are not public. Keep asset URLs and measurements together when updating a showcase. +`site/` is a static project website. `pages.yml` checks canonical URLs, internal links and download metadata on PRs, and deploys changes pushed to `main`. Illustrations are downloaded from the pinned public Release; `site/assets/` and `dist/` stay ignored. After publishing a Release, run `gh workflow run pages.yml --ref main`. Keep the Pages environment restricted to `main` and use GitHub Actions as its source. Publish and verify image/package URLs without authentication before merging README links; draft assets are not public. Keep showcase measurements pinned to the version that generated them. -Submit `https://fightingbald.github.io/database_migrate_UML_generator/sitemap.xml` in Search Console for the project URL. The site has canonical URLs, descriptive text and crawlable pages; these do not guarantee indexing or AI citations. A project-path `robots.txt` would not control the host's root crawler policy. +Submit `https://fightingbald.github.io/database-migration-erd/sitemap.xml` in Search Console for the project URL. The site has canonical URLs, descriptive text and crawlable pages; these do not guarantee indexing or AI citations. A project-path `robots.txt` would not control the host's root crawler policy. To roll back the website, revert the site change and rerun `pages.yml`. Published package versions are immutable: fix forward with a new version, or pin consumers to the last working version. Leave existing release assets intact so documentation links remain stable. diff --git a/erd_generator/__init__.py b/erd_generator/__init__.py index 438a819..d64f653 100644 --- a/erd_generator/__init__.py +++ b/erd_generator/__init__.py @@ -5,7 +5,7 @@ from importlib import import_module from typing import Any -__version__ = "0.2.0" +__version__ = "0.2.1" __all__ = [ "ParseFailure", diff --git a/erd_generator/cli.py b/erd_generator/cli.py index 019cb83..69c4874 100644 --- a/erd_generator/cli.py +++ b/erd_generator/cli.py @@ -23,7 +23,10 @@ def build_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser( - description="Generate readable PostgreSQL ER diagrams from migrations, without a database connection", + description=( + "Generate readable ER diagrams from migration SQL, without a database " + "connection (PostgreSQL dialect parser)" + ), allow_abbrev=False, usage="%(prog)s SQL_DIR OUTPUT [options]", formatter_class=argparse.RawDescriptionHelpFormatter, diff --git a/pyproject.toml b/pyproject.toml index f0edec9..24a334b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "migration-erd" dynamic = ["version", "dependencies"] -description = "Readable PostgreSQL ER diagrams from migration SQL, with automatic clustering and no database connection" +description = "Readable ER diagrams from database migration SQL, with automatic clustering and no database connection" readme = "README.md" requires-python = ">=3.11" authors = [{name = "fightingBald"}] @@ -25,11 +25,11 @@ classifiers = [ ] [project.urls] -Homepage = "https://fightingbald.github.io/database_migrate_UML_generator/" -Documentation = "https://github.com/fightingBald/database_migrate_UML_generator/blob/main/dev_guide.md" -Source = "https://github.com/fightingBald/database_migrate_UML_generator" -Issues = "https://github.com/fightingBald/database_migrate_UML_generator/issues" -Changelog = "https://github.com/fightingBald/database_migrate_UML_generator/releases" +Homepage = "https://fightingbald.github.io/database-migration-erd/" +Documentation = "https://github.com/fightingBald/database-migration-erd/blob/main/dev_guide.md" +Source = "https://github.com/fightingBald/database-migration-erd" +Issues = "https://github.com/fightingBald/database-migration-erd/issues" +Changelog = "https://github.com/fightingBald/database-migration-erd/releases" [project.scripts] migration-erd = "erd_generator.cli:main" diff --git a/site/guides/ci-docusaurus.html b/site/guides/ci-docusaurus.html index 68b5efa..eb0e7f3 100644 --- a/site/guides/ci-docusaurus.html +++ b/site/guides/ci-docusaurus.html @@ -4,17 +4,17 @@ - Automatically update database diagrams in CI and Docusaurus — Migration - ERD + Automatically update database diagrams in CI and Docusaurus — Database + Migration ERD @@ -40,11 +40,10 @@