GitHub Action: a schema diagram pull request on every migration change

Usage

A workflow that redraws the diagram whenever a migration changes on main, and on demand:

name: Update schema diagram

on:
  push:
    branches: [main]
    paths: ['db/migration/**']
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  draw:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: schemadrawercom/action@v1
        with:
          sql-directory: db/migration
          output-path: docs/schema-diagram.svg
          migration-type: FLYWAY
          database-type: POSTGRESQL
          database-version: '18'
          github-token: ${{ secrets.GITHUB_TOKEN }}

The permissions block matters: the action pushes a branch and opens a pull request with the token you pass, so it needs contents: write and pull-requests: write. If the generated SVG is identical to the one already in the repository, no pull request is opened.

How it works

Draw. Every file under sql-directory, subdirectories included and named relative to it, is sent to POST /api/v1/drawing together with userId, migrationType, databaseType and version. The Request-Id is derived from the workflow run and attempt, so a re-run of the same attempt is not drawn twice, and userId is derived from the repository name unless you set one.
Wait. GET /api/v1/drawing/{jobId} is polled every 3 seconds, for up to timeout-seconds. On ERROR the step fails and prints the migration tool's message. On SUCCESS the SVG is downloaded to output-path.
Open a pull request. A branch is created, the file committed and pushed, and a pull request opened against base-branch.

Inputs

Name	Required	Default	Description
`sql-directory`	yes		Directory with the migration files, relative to the repository root. Everything in it, subdirectories included, is uploaded.
`output-path`	yes		Path of the SVG to create or update in the repository.
`api-base-url`	no	`https://schemadrawer.com/api/v1`	Base URL of the API.
`migration-type`	no	`FLYWAY`	The migration tool the files are written for: FLYWAY, LIQUIBASE, PRISMA, DJANGO and the other MigrationType values.
`database-type`	no	`POSTGRESQL`	POSTGRESQL, MYSQL, MARIADB, MSSQL, ORACLE or SQLITE.
`database-version`	no	`18`	Version of the engine, one of those it is offered in.
`user-id`	no	derived from the repository name	UUID identifying this repository at schemadrawer.com.
`timeout-seconds`	no	`300`	How long to wait for the diagram before failing the job.
`base-branch`	no	`current branch`	Branch the pull request targets.
`pr-branch`	no	`schemadrawer/update-<run id>-<run attempt>`	Branch created for the pull request.
`pr-title`	no	`Update schema diagram`	Title of the pull request.
`pr-body`	no	a generic message	Body of the pull request.
`commit-message`	no	`chore: update schema diagram`	Commit message for the diagram file.
`github-token`	yes		Token used to push the branch and open the pull request; needs contents: write and pull-requests: write.

Outputs

Name	Description
`pull-request-url`	URL of the pull request that was opened; empty when there was nothing to commit.

Requirements

A runner with curl, jq, python3 and the gh CLI, all preinstalled on ubuntu-latest.
actions/checkout before the action, so that the repository is there to commit into.
permissions: contents: write and pull-requests: write.

Running the draw step by hand

The action is two bash scripts. The first one takes its inputs from the environment and runs anywhere, which makes it a handy way to draw a diagram from a laptop or from another CI system:

SQL_DIRECTORY=db/migration \
OUTPUT_PATH=docs/schema-diagram.svg \
MIGRATION_TYPE=FLYWAY DATABASE_TYPE=POSTGRESQL DATABASE_VERSION=18 \
scripts/draw.sh

It prints the files it uploads, the job id and where the diagram went. A failed migration ends with the migration tool's message and exit code 1.

Tips

Trigger on paths that cover your migrations, so the diagram is redrawn exactly when it can change.
Draw on the engine version you deploy to. If you support several, run the action in a matrix and write one SVG per engine.
Use the failing step as a check: a pull request that breaks a migration fails the workflow with the tool's own error, before anyone deploys it.

GitHub Action