{"id":13522413,"url":"https://github.com/beenotung/quick-erd","last_synced_at":"2025-04-07T07:04:42.303Z","repository":{"id":57332377,"uuid":"393846350","full_name":"beenotung/quick-erd","owner":"beenotung","description":"quick and easy text-based ERD editor with drag and drop visualization + code generator for migration, query, typescript types and orm entity","archived":false,"fork":false,"pushed_at":"2025-03-05T03:36:51.000Z","size":625,"stargazers_count":50,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T19:38:13.502Z","etag":null,"topics":["drag-and-drop","erd","text-based"],"latest_commit_sha":null,"homepage":"https://erd.surge.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beenotung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-08T03:27:38.000Z","updated_at":"2025-03-14T20:11:11.000Z","dependencies_parsed_at":"2023-12-13T16:44:10.027Z","dependency_job_id":"35b27787-29d9-429a-bc40-1df95a92cd96","html_url":"https://github.com/beenotung/quick-erd","commit_stats":{"total_commits":750,"total_committers":2,"mean_commits":375.0,"dds":0.00666666666666671,"last_synced_commit":"c732888d607a2988682215a519266db8d681e99c"},"previous_names":[],"tags_count":162,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Fquick-erd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Fquick-erd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Fquick-erd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Fquick-erd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beenotung","download_url":"https://codeload.github.com/beenotung/quick-erd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608150,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drag-and-drop","erd","text-based"],"created_at":"2024-08-01T06:00:46.925Z","updated_at":"2025-04-07T07:04:42.282Z","avatar_url":"https://github.com/beenotung.png","language":"TypeScript","readme":"# quick-erd\n\nquick and easy text-based ERD editor with drag and drop visualization + code generator for migration, query, typescript types and orm entity\n\n[![npm Package Version](https://img.shields.io/npm/v/quick-erd)](https://www.npmjs.com/package/quick-erd)\n[![npm Package Downloads](https://img.shields.io/npm/dy/quick-erd)](https://www.npmtrends.com/quick-erd)\n\n![banner](./assets/banner.webp)\n\n## Quick Reference\n\n### Web UI Diagram and Editor\n\n**Hosted Web UI**: https://quick-erd.surge.sh\n\n**Run locally** (with access to local `erd.txt` file):\n\n```bash\nnpm i -D quick-erd\nnpx erd-ui\n```\n\n### npx cli\n\ngenerate incremental migration:\n`auto-migrate`\n\ngenerate typescript types of each table:\n`erd-to-types`\n\ngenerate each table types and better-sqlite3-proxy schema:\n`erd-to-proxy`\n\ngenerate java jpa entities and repositories:\n`erd-to-spring`\n\ngenerate initial schema:\n`erd-to-sqlite`, `erd-to-knex`\n\nreverse-engineer erd text:\n`pg-to-erd`, `mysql-to-erd`, `mssql-to-erd`, `sqlite-to-erd`\n\nformat erd text:\n`format-erd`\n\nopen web ui:\n`erd-ui`\n\n## Features\n\n- [x] text-based erd editor\n- [x] import from existing postgresql schema\n- [x] generate database schema migration\n  - [x] knex migrate script\n  - [x] sqlite migrate statements\n  - [x] support postgres, mysql, mssql, sqlite\n- [x] published as npx script\n- [x] web-based schema visualization\n  - [x] zoom in/out\n  - [x] drag-and-drop moving\n  - [x] show/hide non-relational columns\n  - [x] custom heading color per table\n  - [x] customize UI color theme\n  - [x] keyboard shortcuts\n  - [x] auto save-and-restore with localStorage\n  - [x] auto format the schema text\n  - [x] auto normalize specified column\n  - [x] auto avoid table overlapping visually\n  - [x] import/export diagram with drag position and zoom level\n  - [x] right-click on diagram to select table/column in editor\n  - [x] auto-complete when creating new table\n- [x] web-based query builder\n  - [x] select columns with checkbox\n  - [x] generate SQL/knex query with nested join-table\n  - [x] generate typescript type of query result\n  - [x] copy selected part into clipboard\n  - [x] support additional query (where / group-by / order-by / limit, e.t.c.)\n  - [x] support sharing diagram embedded in url\n- [x] local web-ui\n  - [x] offline usage\n  - [x] load from disk file\n  - [x] save to disk file\n\n## Usage\n\n### ERD Editing\n\nOption 1: Run it online\n\nHosted on https://erd.surge.sh and https://quick-erd.surge.sh\n\nOption 2: Run it locally\n\n1. Clone this git repository\n2. cd into the folder\n3. Run `npm install`\n4. Run `npm start`\n\n### Database Utility\n\n#### Setup\n\n1. Install this package as devDependency, run `npm i -D quick-erd`\n\n2. Setup database connection credential in `.env`.\n\n`.env` is not needed for sqlite\n\nYou can refer to `.env.example`\n\n#### Overview of Commands\n\nBelow are available commands in example.\n\n\u003cdetails\u003e\n\u003csummary\u003eRemarks to Windows user (click to expand)\u003c/summary\u003e\nWindows users area recommended to use git bash to perform pipe operations.\n\nIf you prefer to use PowerShell, you may need to replace `\u003c` with `\\\u003c` to pipe file content as stdin.\n\n\u003c/details\u003e\n\n**To reverse-engineer erd file from live database**:\n\n- `npx pg-to-erd \u003e erd.txt`\n- `npx mysql-to-erd \u003e erd.txt`\n- `npx mssql-to-erd \u003e erd.txt`\n- `npx sqlite-to-erd dev.sqlite3 \u003e erd.txt`\n\n**To generate initial database migration script from erd file**:\n\n- `npx erd-to-knex pg \u003c erd.txt \u003e migrations/001-create-tables.ts`\n- `npx erd-to-sqlite \u003c erd.txt \u003e migrations/001-create-tables.sql`\n\n**To generate incremental database migration script from erd file and live database**:\n\n- `npx auto-migrate pg \u003c erd.txt`\n- `npx auto-migrate mysql \u003c erd.txt`\n- `npx auto-migrate mssql \u003c erd.txt`\n- `npx auto-migrate dev.sqlite3 \u003c erd.txt`\n- `npx auto-migrate --rename pg \u003c erd.txt`\n\n**To generate typescript types of each table**:\n\n- `npx erd-to-types \u003c erd.txt \u003e types.ts`\n\n**To generate types and proxy schema for better-sqlite3-proxy**:\n\n- `npx erd-to-proxy \u003c erd.txt \u003e proxy.ts`\n- `npx erd-to-proxy --factory \u003c erd.txt \u003e proxy.ts`\n\n**To generate java jpa entities and repositories**:\n\n- `npx erd-to-spring pg \u003c erd.txt`\n- `npx erd-to-spring h2 \u003c erd.txt`\n\n**To format erd file**:\n\n- `npx format-erd erd.txt`\n- `npx format-erd --ref ordered_erd.txt new_erd.txt`\n\n**To update erd file from live database**:\n\n```bash\nnpx pg-to-erd \u003e erd.tmp\nnpx format-erd -r erd.txt erd.tmp\nmeld erd.txt erd.tmp\nrm erd.tmp\n```\n\n**To open web ui with disk file access**:\n\n- `npx erd-ui`\n- `npx erd-ui -p 8520 erd.txt`\n\n#### Import from Existing Schema\n\n1. Extract from live database\n\nFor Postgresql schema: Run `pg-to-erd`\n\nFor Mysql/MariaDB schema: Run `mysql-to-erd`\n\nFor MSSQL (Microsoft SQL Server) schema: Run `mssql-to-erd`\n\nFor Sqlite schema: Run `sqlite-to-erd SQLITE_FILENAME`\n\nYou can save the output into a file using pipe. e.g. by running: `pg-to-erd \u003e erd.txt`\n\n2. Copy the output text into the web erd editor\n\n#### Export as Migration Script\n\nYou can export the erd.txt to a database migration script. This process is also called forward-engineering for database schema.\n\nSupported schema format includes: [knex](https://github.com/knex/knex) and [better-sqlite3-helper](https://github.com/Kauto/better-sqlite3-helper)\n\n##### Export as Knex Migration Script\n\n1. Run `erd-to-knex pg \u003c erd.txt \u003e migrate.ts`\n\nYou need to specify the db_client. e.g. `pg`, `mysql`, `mssql`, or `sqlite`\n\nYou can save the erd text into a file, then load it as stdin. e.g. `erd-to-knex pg \u003c erd.txt`\n\nAlso, you can save the result into a knex migration script. e.g.\n\n```bash\n# create migrations directory if not exist\nmkdir -p migrations\n\n# read from erd.txt, save to migrations/YYYYmmddHHMMSS-create-tables.ts\nerd-to-knex pg \u003c erd.txt \u003e migrations/$(date +\"%Y%m%d%H%M%S\")-create-tables.ts\n```\n\n##### Export as Sqlite Migration Script\n\n1. Run `erd-to-sqlite \u003c erd.txt \u003e migrate.sql`\n\nDepending on your migration directory (default is ./migrations/), you may save the migration script in corresponding directory. e.g.\n\n```bash\n# create migrations directory if not exist\nmkdir -p migrations\n\n# read from erd.txt, save to migrations/000-create-tables.sql\nerd-to-sqlite \u003c erd.txt \u003e migrations/000-create-tables.sql\n```\n\n##### Generate Incremental Knex Migration Script\n\n1. Run `npx auto-migrate dev.sqlite3 \u003c erd.txt`\n\n   or `npx auto-migrate mysql \u003c erd.txt`\n\n   or `npx auto-migrate mssql \u003c erd.txt`\n\n   or `npx auto-migrate pg \u003c erd.txt`\n\n   or `npx auto-migrate --rename pg \u003c erd.txt`\n\nThis command auto setup knex and npm scripts, then it generates incremental migration script for knex.\n\nFor sqlite database, it also auto setup `db.ts` with `better-sqlite3` connection using given database filename.\n\nThe `--rename` or `-r` flag enable table/column rename detection.\n\nIf there are pending knex migrations not applied, it will show error message and stop running.\n\n#### Generate typescript types of each table\n\n1. Run `npx erd-to-types \u003c erd.txt \u003e types.ts`\n\nThis command generates the the typescript types of each table.\n\nThe relation fields are also included based on the foreign key references.\n\n#### Generate types and proxy schema for better-sqlite3-proxy\n\n1. Run `npx erd-to-proxy \u003c erd.txt \u003e proxy.ts`\n\nThis command generates the typescript types of each table and the schema for `proxySchema()` in [better-sqlite3-proxy](https://github.com/beenotung/better-sqlite3-proxy)\n\nThe relation fields are also included based on the foreign key references.\n\n**Additional arguments**:\n\n- export format:\n\n  - `--factory`\n  - `--singleton` (default)\n\n- import format:\n  - `--commonjs` or `--cjs` (default)\n  - `--module` or `--esm`\n\n_Export Format_:\n\nThe default behavior is to generate a proxy as singleton with commonjs format.\n\nIf a factory function is preferred, you can pass `--factory` in the argument, e.g. `npx erd-to-proxy --factory \u003c erd.txt \u003e proxy.ts`\n\n_Import Format_:\n\nIn commonjs mode, the import path of local typescript files should not include `.js` extension;\nIn esm module, the import path of local files should include `.js` extension.\n\nIn the generated proxy file, it needs to import the local file `db.ts`. This tool will try to read the `type` field in `package.json` to determine the import format, and fallback to use \"commonjs\" format if undetermined.\n\nIf esm format is preferred but undetected, you can pass `--esm` in the argument, e.g. `npx erd-to-proxy --esm \u003c erd.txt \u003e proxy.ts`\n\n#### Format Diagram Text\n\nTo \"prettify\" the erd, run: `format-erd erd.txt`\n\nTo sort the tables and fields of exported erd according to previous version of erd, run:\n`format-erd --ref old_erd.txt new_erd.txt`\n\nThe original text file will be backup with suffix, e.g. 'erd.txt.bk_20220212144828'\n\nThe formatted erd text will be saved in-place.\n\nWarning: Comments are not preserved in the current version. If you want to restore the comments, you may use diff tools like [meld](https://meldmerge.org/) to compare the formatted version and original version.\n\n## Todo\n\n- to support named enum\n\n  - currently it only supports inline enum in a table field\n  - but postgres default enum as a global type\n\n- to support prisma schema\n\n  - generate it with relations\n  - read from it\n\n- to support composite primary keys\n- to support composite unique keys\n\n- update \"auto place\" algorithm to avoid relationship lines overlap the tables visually\n\n## License\n\nThis project is licensed with [BSD-2-Clause](./LICENSE)\n\nThis is free, libre, and open-source software. It comes down to four essential freedoms [[ref]](https://seirdy.one/2021/01/27/whatsapp-and-the-domestication-of-users.html#fnref:2):\n\n- The freedom to run the program as you wish, for any purpose\n- The freedom to study how the program works, and change it so it does your computing as you wish\n- The freedom to redistribute copies so you can help others\n- The freedom to distribute copies of your modified versions to others\n","funding_links":[],"categories":["Javascript Libraries"],"sub_categories":["Misc"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeenotung%2Fquick-erd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeenotung%2Fquick-erd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeenotung%2Fquick-erd/lists"}