relspecgo/docs/FORMAT_EXAMPLES.md

Format Usage Examples

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 output.

Writers: DBML to every format

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 <name> to select one.

Readers: file-based formats into DBML (or JSON where noted)

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

# 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:

# 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 "<mssql connection string>" \
                --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 and JOB_FILES.md.
• The template writer is exposed through relspec templ. See TEMPLATE_MODE.md.