From 54041228c9ed91aaed205b2f486aac0ad70cac29 Mon Sep 17 00:00:00 2001 From: SG Command Date: Sat, 3 Oct 2026 03:09:26 +0200 Subject: [PATCH 1/2] docs: add usage examples for each format combination (#37) Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 + docs/FORMAT_EXAMPLES.md | 102 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 docs/FORMAT_EXAMPLES.md diff --git a/README.md b/README.md index 69f4b44..6d43f99 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ go install -v git.warky.dev/wdevs/relspecgo/cmd/relspec@latest | **Readers** | `bun` `dbml` `dctx` `drawdb` `drizzle` `gorm` `graphql` `json` `mssql` `pgsql` `prisma` `sqldir` `sqlite` `typeorm` `yaml` | | **Writers** | `bun` `dbml` `dctx` `drawdb` `drizzle` `gorm` `graphql` `json` `mssql` `pgsql` `prisma` `sqlexec` `sqlite` `template` `typeorm` `yaml` | +See [docs/FORMAT_EXAMPLES.md](docs/FORMAT_EXAMPLES.md) for usage examples covering every format. + ## Commands ### `convert` — Schema conversion diff --git a/docs/FORMAT_EXAMPLES.md b/docs/FORMAT_EXAMPLES.md new file mode 100644 index 0000000..e27e032 --- /dev/null +++ b/docs/FORMAT_EXAMPLES.md @@ -0,0 +1,102 @@ +# Format Usage Examples + +Examples for `relspec convert` covering every reader and writer format. The +"Writers" and "Readers" sections below were run against `examples/test_schema.dbml`. +The cross-format and live-database examples were not run; they follow the flags +shown in `relspec convert --help`. + +Any reader can be combined with any writer: pick `--from`/`--from-path` for the +source and `--to`/`--to-path` for the target. Add `--silent` to suppress progress +output. + +## Writers: DBML to every format + +```bash +S="--from dbml --from-path examples/test_schema.dbml" + +relspec convert $S --to json --to-path schema.json +relspec convert $S --to yaml --to-path schema.yaml +relspec convert $S --to dctx --to-path schema.dctx +relspec convert $S --to drawdb --to-path schema.drawdb.json +relspec convert $S --to graphql --to-path schema.graphql +relspec convert $S --to prisma --to-path schema.prisma +relspec convert $S --to pgsql --to-path schema.pg.sql +relspec convert $S --to mssql --to-path schema.mssql.sql +relspec convert $S --to sqlite --to-path schema.sqlite.sql +relspec convert $S --to drizzle --to-path schema.ts +relspec convert $S --to typeorm --to-path entities.ts +relspec convert $S --to gorm --to-path models.go --package models +relspec convert $S --to bun --to-path models.go --package models +``` + +Notes: + +- Code-generation writers (`gorm`, `bun`) take `--package`. They also accept + `--types baselib|stdlib|sqltypes` to choose the nullable type package. +- When `--to-path` is a directory it must already exist. +- `sqlite` output automatically flattens `schema.table` names. Use + `--flatten-schema` for other formats if the target has no schema support. +- `dctx` supports a single schema only; use `--schema ` to select one. + +## Readers: every format back to DBML + +```bash +relspec convert --from json --from-path schema.json --to dbml --to-path out.dbml +relspec convert --from yaml --from-path schema.yaml --to dbml --to-path out.dbml +relspec convert --from dctx --from-path schema.dctx --to dbml --to-path out.dbml +relspec convert --from drawdb --from-path schema.drawdb.json --to dbml --to-path out.dbml +relspec convert --from graphql --from-path schema.graphql --to dbml --to-path out.dbml +relspec convert --from prisma --from-path schema.prisma --to dbml --to-path out.dbml +relspec convert --from drizzle --from-path schema.ts --to dbml --to-path out.dbml +relspec convert --from typeorm --from-path entities.ts --to dbml --to-path out.dbml +relspec convert --from bun --from-path models.go --to dbml --to-path out.dbml +relspec convert --from gorm --from-path models.go --to json --to-path out.json +``` + +Code-first readers (`gorm`, `bun`, `drizzle`, `typeorm`) accept a single file or a +directory of model files. + +> Known issue: reading GORM models and writing DBML currently panics in the DBML +> writer (`pkg/writers/dbml/writer.go`, `constraintToDBML`). Use another target +> such as JSON until this is fixed. + +## Cross-format combinations + +```bash +# ORM models to SQL DDL +relspec convert --from gorm --from-path models.go --to pgsql --to-path schema.sql + +# Prisma to Drizzle +relspec convert --from prisma --from-path schema.prisma --to drizzle --to-path schema.ts + +# DrawDB diagram to GraphQL +relspec convert --from drawdb --from-path diagram.json --to graphql --to-path schema.graphql + +# Merge several files while converting +relspec convert --from json --from-list "a.json,b.json" --to yaml --to-path merged.yaml +``` + +## Live databases + +These need a reachable database: + +```bash +# PostgreSQL +relspec convert --from pgsql --from-conn "postgres://user:pass@localhost:5432/mydb" \ + --to dbml --to-path schema.dbml + +# SQL Server +relspec convert --from mssql --from-conn "" \ + --to json --to-path schema.json + +# SQLite database file (--from-conn takes the file path) +relspec convert --from sqlite --from-conn ./app.db --to dbml --to-path schema.dbml +``` + +## Formats outside `convert` + +- `sqldir` (SQL script directory reader) and `sqlexec` (SQL execution writer) are + used by `relspec scripts` and `relspec job`, and `sqldir` by `relspec diff`. + See [SCRIPTS_COMMAND.md](SCRIPTS_COMMAND.md) and [JOB_FILES.md](JOB_FILES.md). +- The `template` writer is exposed through `relspec templ`. See + [TEMPLATE_MODE.md](TEMPLATE_MODE.md). -- 2.54.0 From 519ee4f6eb48ef320a627d4aec3cf66eea0d9b6d Mon Sep 17 00:00:00 2001 From: SG Command Date: Sat, 3 Oct 2026 05:09:00 +0200 Subject: [PATCH 2/2] docs: clarify format example coverage --- docs/FORMAT_EXAMPLES.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/FORMAT_EXAMPLES.md b/docs/FORMAT_EXAMPLES.md index e27e032..a023de3 100644 --- a/docs/FORMAT_EXAMPLES.md +++ b/docs/FORMAT_EXAMPLES.md @@ -1,9 +1,10 @@ # Format Usage Examples -Examples for `relspec convert` covering every reader and writer format. The -"Writers" and "Readers" sections below were run against `examples/test_schema.dbml`. -The cross-format and live-database examples were not run; they follow the flags -shown in `relspec convert --help`. +Examples for `relspec convert` covering the file-based reader and writer +formats. The "Writers" and "Readers" sections below were run against +`examples/test_schema.dbml`. The cross-format and live-database examples were +not run; they follow the flags shown in `relspec convert --help` and require +matching input files or reachable databases. Any reader can be combined with any writer: pick `--from`/`--from-path` for the source and `--to`/`--to-path` for the target. Add `--silent` to suppress progress @@ -38,7 +39,7 @@ Notes: `--flatten-schema` for other formats if the target has no schema support. - `dctx` supports a single schema only; use `--schema ` to select one. -## Readers: every format back to DBML +## Readers: file-based formats into DBML (or JSON where noted) ```bash relspec convert --from json --from-path schema.json --to dbml --to-path out.dbml -- 2.54.0