https://github.com/samdouble/migration-visualizer
https://github.com/samdouble/migration-visualizer
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/samdouble/migration-visualizer
- Owner: samdouble
- Created: 2025-12-27T17:12:37.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-01-09T23:08:18.000Z (6 months ago)
- Last Synced: 2026-01-10T20:10:19.247Z (6 months ago)
- Language: TypeScript
- Size: 387 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
[](https://github.com/samdouble/migration-visualizer/actions/workflows/checks.yml)
[](https://www.npmjs.org/package/migration-visualizer)
[](https://www.npmjs.org/package/migration-visualizer)
[](https://coveralls.io/github/samdouble/migration-visualizer?branch=master)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://www.mysql.com/)
[](https://www.postgresql.org/)
[](https://www.sqlite.org/)
[](https://jestjs.io/)
[](https://www.npmjs.com/)
# Migration Visualizer
This tool outputs Entity Relationship diagrams for Knex.js and Kysely migrations in Mermaid format.
## Usage
Install the package:
```bash
npm install -g migration-visualizer
```
And then use it through the CLI.
### CLI
```bash
npx migration-visualizer visualize [options]
```
#### Options
| Option | Description | Required |
|--------|-------------|----------|
| `--query-builder ` | Query builder to use (`knex`, `kysely`) | Yes |
| `--changed ` | List of new and updated migration files | No |
| `--output ` | Output format (default: `mermaid`) | No |
#### Kysely-specific Options
| Option | Description | Required |
|--------|-------------|----------|
| `--dialect ` | Database dialect (`sqlite3`, `mysql2`, `pg`) | Yes |
| `--migrations ` | Path to migrations directory | Yes |
| `--host ` | Database host | No |
| `--port ` | Database port | No |
| `--database ` | Database name | No |
| `--user ` | Database user | No |
| `--password ` | Database password | No |
| `--filename ` | Database filename (SQLite) | No |
| `--useNullAsDefault` | Use null as default (SQLite) | No |
#### Examples
##### Knex.js
`migration-visualizer` detects the Knexfile at the root of your project and uses it for configuration.
```bash
npx migration-visualizer visualize --query-builder knex --changed 20251227000006_create_likes.ts
```
##### Kysely
Since Kysely does not provide a configuration file, you need to provide the dialect, migrations directory, and other connection details.
**With MySQL**:
```bash
npx migration-visualizer visualize \
--query-builder kysely \
--dialect mysql2 \
--host localhost \
--port 3306 \
--database mydb \
--user root \
--password secret \
--migrations ./migrations \
--changed 20251227000006_create_likes.ts
```
**With PostgreSQL**:
```bash
npx migration-visualizer visualize \
--query-builder kysely \
--dialect pg \
--host localhost \
--port 5432 \
--database mydb \
--user postgres \
--password secret \
--migrations ./migrations \
--changed 20251227000006_create_likes.ts
```
**With SQLite**:
```bash
npx migration-visualizer visualize \
--query-builder kysely \
--dialect sqlite3 \
--filename dev.sqlite3 \
--migrations ./migrations \
--changed 20251227000006_create_likes.ts
```
### GitHub Action
TODO
## Features
### Supported Query Builders
- Knex.js
- Kysely
### Supported Databases
- MySQL
- PostgreSQL
- SQLite
### Supported Output Formats
- Mermaid
## Development
### Testing
Simply run the following command to run the tests:
```bash
npm run test
```
For now, the PostgreSQL tests are only run in the CI. It would be nice to be able to run them locally as well, but I couldn't find a way to set up simply a PostgreSQL server (`pg-mem` currently does not support migrations and a few other important features needed in this project).