# 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

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

## 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
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 "<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](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).