166 lines
5.7 KiB
Markdown
166 lines
5.7 KiB
Markdown
# RelSpec
|
|
|
|
[](https://git.warky.dev/wdevs/relspecgo/releases/latest)
|
|
[](https://git.warky.dev/wdevs/relspecgo/actions/workflows/ci.yml)
|
|
[](https://git.warky.dev/wdevs/relspecgo/actions/workflows/integration-tests.yml)
|
|
[](https://go.dev/dl/)
|
|
[](LICENSE)
|
|
|
|
> Bidirectional database schema conversion, validation, and templating tool.
|
|
|
|
|
|
|
|
## Install
|
|
|
|
```bash
|
|
go install -v git.warky.dev/wdevs/relspecgo/cmd/relspec@latest
|
|
```
|
|
|
|
## Supported Formats
|
|
|
|
| Direction | Formats |
|
|
|-----------|---------|
|
|
| **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` |
|
|
|
|
## Commands
|
|
|
|
### `convert` — Schema conversion
|
|
|
|
```bash
|
|
# PostgreSQL → GORM models
|
|
relspec convert --from pgsql --from-conn "postgres://user:pass@localhost/mydb" \
|
|
--to gorm --to-path models/ --package models
|
|
|
|
# DBML → PostgreSQL DDL
|
|
relspec convert --from dbml --from-path schema.dbml --to pgsql --to-path schema.sql
|
|
|
|
# PostgreSQL → SQLite (auto flattens schemas)
|
|
relspec convert --from pgsql --from-conn "postgres://..." --to sqlite --to-path schema.sql
|
|
|
|
# Multiple input files merged
|
|
relspec convert --from json --from-list "a.json,b.json" --to yaml --to-path merged.yaml
|
|
```
|
|
|
|
### `merge` — Additive schema merge (never modifies existing items)
|
|
|
|
```bash
|
|
# Merge two JSON schemas
|
|
relspec merge --target json --target-path base.json \
|
|
--source json --source-path additions.json \
|
|
--output json --output-path merged.json
|
|
|
|
# Merge PostgreSQL into JSON, skipping tables
|
|
relspec merge --target json --target-path current.json \
|
|
--source pgsql --source-conn "postgres://user:pass@localhost/db" \
|
|
--output json --output-path updated.json \
|
|
--skip-tables "audit_log,temp_tables"
|
|
```
|
|
|
|
Skip flags: `--skip-relations` `--skip-views` `--skip-domains` `--skip-enums` `--skip-sequences`
|
|
|
|
### `inspect` — Schema validation / linting
|
|
|
|
```bash
|
|
# Validate PostgreSQL database
|
|
relspec inspect --from pgsql --from-conn "postgres://user:pass@localhost/mydb"
|
|
|
|
# Validate DBML with custom rules
|
|
relspec inspect --from dbml --from-path schema.dbml --rules .relspec-rules.yaml
|
|
|
|
# JSON report output
|
|
relspec inspect --from json --from-path db.json --output-format json --output report.json
|
|
|
|
# Filter to specific schema
|
|
relspec inspect --from pgsql --from-conn "..." --schema public
|
|
```
|
|
|
|
Rules: naming conventions, PK/FK standards, missing indexes, reserved keywords, circular dependencies.
|
|
|
|
### `diff` — Schema comparison
|
|
|
|
```bash
|
|
relspec diff --from pgsql --from-conn "postgres://localhost/db1" \
|
|
--to pgsql --to-conn "postgres://localhost/db2"
|
|
```
|
|
|
|
### `templ` — Custom template rendering
|
|
|
|
```bash
|
|
# Render database schema to Markdown docs
|
|
relspec templ --from pgsql --from-conn "postgres://user:pass@localhost/db" \
|
|
--template docs.tmpl --output schema-docs.md
|
|
|
|
# One TypeScript file per table
|
|
relspec templ --from dbml --from-path schema.dbml \
|
|
--template ts-model.tmpl --mode table \
|
|
--output ./models/ --filename-pattern "{{.Name | toCamelCase}}.ts"
|
|
```
|
|
|
|
Modes: `database` (default) · `schema` · `table` · `script`
|
|
|
|
Template functions: string utils (`toCamelCase`, `toSnakeCase`, `pluralize`, …), type converters (`sqlToGo`, `sqlToTypeScript`, …), filters, loop helpers, safe access.
|
|
|
|
### `edit` — Interactive TUI editor
|
|
|
|
```bash
|
|
# Edit DBML schema interactively
|
|
relspec edit --from dbml --from-path schema.dbml --to dbml --to-path schema.dbml
|
|
|
|
# Edit live PostgreSQL database
|
|
relspec edit --from pgsql --from-conn "postgres://user:pass@localhost/mydb" \
|
|
--to pgsql --to-conn "postgres://user:pass@localhost/mydb"
|
|
```
|
|
|
|
<p align="center">
|
|
<img src="./assets/image/screenshots/main_screen.jpg">
|
|
</p>
|
|
<p align="center">
|
|
<img src="./assets/image/screenshots/table_view.jpg">
|
|
</p>
|
|
<p align="center">
|
|
<img src="./assets/image/screenshots/edit_column.jpg">
|
|
</p>
|
|
|
|
## Development
|
|
|
|
**Prerequisites:** Go 1.24.0+
|
|
|
|
```bash
|
|
make build # → build/relspec
|
|
make test # race detection + coverage
|
|
make lint # requires golangci-lint
|
|
make coverage # → coverage.html
|
|
make install # → $GOPATH/bin
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
cmd/relspec/ CLI commands
|
|
pkg/readers/ Input format readers
|
|
pkg/writers/ Output format writers
|
|
pkg/inspector/ Schema validation
|
|
pkg/diff/ Schema comparison
|
|
pkg/merge/ Schema merging
|
|
pkg/models/ Internal data models
|
|
pkg/transform/ Transformation logic
|
|
pkg/pgsql/ PostgreSQL utilities
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Register or sign in with GitHub at [git.warky.dev](https://git.warky.dev)
|
|
2. Clone the repository: `git clone https://git.warky.dev/wdevs/relspecgo.git`
|
|
3. Create a feature branch: `git checkout -b feature/your-feature-name`
|
|
4. Commit your changes and push the branch
|
|
5. Open a pull request with a description of the new feature or fix
|
|
|
|
For questions or discussion, join the Discord: [discord.gg/74rcTujp25](https://discord.gg/74rcTujp25) — `warkyhein`
|
|
|
|
## Links
|
|
|
|
- [Todo](./TODO.md)
|
|
- [AI Use Policy](./AI_USE.md)
|
|
- [License](LICENSE) — Apache 2.0 · Copyright 2025 Warky Devs
|