ChartDB Database Sync

ChartDB Database Sync Action

Automatically sync your database schema with ChartDB to keep your ER diagrams up-to-date.

Features

🔄 Automatic database schema synchronization
📊 Updates ChartDB diagrams in real-time
🔒 Secure handling of credentials via GitHub Secrets
🐳 Docker-based for consistent execution
🗄️ Supports PostgreSQL, MySQL, SQL Server, MariaDB, SQLite, ClickHouse, CockroachDB, and Oracle

Usage

Basic Example

name: Sync Database with ChartDB
on:
  push:
    branches: [ main ]
  schedule:
    - cron: '0 0 * * *'  # Daily sync at midnight

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync Database Schema
        uses: chartdb/chartdb-action@v1
        with:
          db-host: ${{ secrets.DB_HOST }}
          db-port: '5432'
          db-database: ${{ secrets.DB_DATABASE }}
          db-username: ${{ secrets.DB_USERNAME }}
          db-password: ${{ secrets.DB_PASSWORD }}
          db-type: 'postgresql'
          chartdb-api-token: ${{ secrets.CHARTDB_API_TOKEN }}
          chartdb-diagram-id: ${{ secrets.CHARTDB_DIAGRAM_ID }}

With GitHub-hosted Database

name: Sync GitHub Actions Database
on:
  workflow_dispatch:
  push:
    paths:
      - 'migrations/**'
      - 'schema/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4
      
      - name: Run migrations
        run: |
          # Your migration commands here
          
      - name: Sync with ChartDB
        uses: chartdb/chartdb-action@v1
        with:
          db-host: 'localhost'
          db-port: '5432'
          db-database: 'testdb'
          db-username: 'testuser'
          db-password: 'testpass'
          db-type: 'postgresql'
          chartdb-api-token: ${{ secrets.CHARTDB_API_TOKEN }}
          chartdb-diagram-id: ${{ secrets.CHARTDB_DIAGRAM_ID }}

Inputs

Input	Description	Required	Default
`db-host`	Database host address	Yes	-
`db-port`	Database port	No	`5432`
`db-database`	Database name	Yes	-
`db-username`	Database username	Yes	-
`db-password`	Database password (use secrets!)	No	-
`db-type`	Database type (`postgresql`, `mysql`, `sql_server`, `sqlite`, `mariadb`, `clickhouse`, `cockroachdb`, `oracle`)	Yes	-
`chartdb-api-token`	ChartDB API token (use secrets!)	Yes	-
`chartdb-diagram-id`	ChartDB diagram ID to sync with	Yes	-
`network`	Docker network mode	No	`host`

Outputs

Output	Description
`status`	Sync status (`success` or `failed`)

Setup

1. Get ChartDB Credentials

Sign up at ChartDB
Create or open your diagram
Navigate to diagram settings
Generate an API token
Copy your diagram ID from the URL or settings

2. Configure GitHub Secrets

Add the following secrets to your repository:

Go to Settings → Secrets and variables → Actions
Add these secrets:
- DB_HOST: Your database host
- DB_DATABASE: Your database name
- DB_USERNAME: Database username
- DB_PASSWORD: Database password
- CHARTDB_API_TOKEN: Your ChartDB API token
- CHARTDB_DIAGRAM_ID: Your ChartDB diagram ID

3. Add Workflow

Create .github/workflows/chartdb-sync.yml in your repository with one of the examples above.

Security Considerations

Always use GitHub Secrets for sensitive information
Never commit credentials directly in workflow files
Consider using environment-specific secrets for different stages
Use least-privilege database users for syncing
Rotate API tokens regularly

Database Support

PostgreSQL

db-type: 'postgresql'
db-port: '5432'  # default

MySQL

db-type: 'mysql'
db-port: '3306'  # default

MariaDB

db-type: 'mariadb'
db-port: '3306'  # default

Microsoft SQL Server

db-type: 'sql_server'
db-port: '1433'  # default

Advanced Usage

Conditional Sync

- name: Sync with ChartDB
  if: github.ref == 'refs/heads/main'
  uses: chartdb/chartdb-action@v1
  with:
    # ... your configuration

Multiple Environments

jobs:
  sync-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: chartdb/chartdb-action@v1
        with:
          db-host: ${{ secrets.STAGING_DB_HOST }}
          chartdb-diagram-id: ${{ secrets.STAGING_DIAGRAM_ID }}
          # ... other staging config

  sync-production:
    runs-on: ubuntu-latest
    environment: production
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: chartdb/chartdb-action@v1
        with:
          db-host: ${{ secrets.PROD_DB_HOST }}
          chartdb-diagram-id: ${{ secrets.PROD_DIAGRAM_ID }}
          # ... other production config

With Status Check

- name: Sync with ChartDB
  id: chartdb-sync
  uses: chartdb/chartdb-action@v1
  with:
    # ... your configuration

- name: Check sync status
  if: steps.chartdb-sync.outputs.status == 'failed'
  run: |
    echo "ChartDB sync failed! Check the logs above."
    exit 1

Troubleshooting

Connection Issues

If the action fails to connect to your database:

Check network accessibility: Ensure your database is accessible from GitHub Actions runners
Verify credentials: Double-check all secrets are correctly set
Firewall rules: Add GitHub Actions IP ranges to your database firewall if needed
Use self-hosted runners: For private databases, consider using self-hosted runners

Docker Network Modes

The action uses host network mode by default. For other configurations:

with:
  network: 'bridge'  # or 'none', 'container:name', etc.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Documentation: ChartDB Docs