Updated Readme files
This commit is contained in:
106
pkg/readers/bun/README.md
Normal file
106
pkg/readers/bun/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Bun Reader
|
||||
|
||||
Reads Go source files containing Bun model definitions and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The Bun Reader parses Go source code files that define Bun models (structs with `bun` struct tags) and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses Bun struct tags to extract column definitions
|
||||
- Extracts table names from `bun:"table:tablename"` tags
|
||||
- Identifies primary keys, foreign keys, and indexes
|
||||
- Supports relationship detection
|
||||
- Handles both single files and directories
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/bun"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/models.go",
|
||||
}
|
||||
|
||||
reader := bun.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read Bun models and convert to JSON
|
||||
relspec --input bun --in-file models/ --output json --out-file schema.json
|
||||
|
||||
# Convert Bun models to GORM
|
||||
relspec --input bun --in-file models.go --output gorm --out-file gorm_models.go
|
||||
```
|
||||
|
||||
## Supported Bun Tags
|
||||
|
||||
The reader recognizes the following Bun struct tags:
|
||||
|
||||
- `table` - Table name
|
||||
- `column` - Column name
|
||||
- `type` - SQL data type
|
||||
- `pk` - Primary key
|
||||
- `notnull` - NOT NULL constraint
|
||||
- `autoincrement` - Auto-increment column
|
||||
- `default` - Default value
|
||||
- `unique` - Unique constraint
|
||||
- `rel` - Relationship definition
|
||||
|
||||
## Example Bun Model
|
||||
|
||||
```go
|
||||
package models
|
||||
|
||||
import (
|
||||
"time"
|
||||
"github.com/uptrace/bun"
|
||||
)
|
||||
|
||||
type User struct {
|
||||
bun.BaseModel `bun:"table:users,alias:u"`
|
||||
|
||||
ID int64 `bun:"id,pk,autoincrement"`
|
||||
Username string `bun:"username,notnull,unique"`
|
||||
Email string `bun:"email,notnull"`
|
||||
CreatedAt time.Time `bun:"created_at,notnull,default:now()"`
|
||||
|
||||
Posts []*Post `bun:"rel:has-many,join:id=user_id"`
|
||||
}
|
||||
|
||||
type Post struct {
|
||||
bun.BaseModel `bun:"table:posts,alias:p"`
|
||||
|
||||
ID int64 `bun:"id,pk"`
|
||||
UserID int64 `bun:"user_id,notnull"`
|
||||
Title string `bun:"title,notnull"`
|
||||
Content string `bun:"content"`
|
||||
|
||||
User *User `bun:"rel:belongs-to,join:user_id=id"`
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Test files (ending in `_test.go`) are automatically excluded
|
||||
- The `bun.BaseModel` embedded struct is automatically recognized
|
||||
- Schema defaults to `public` if not specified
|
||||
101
pkg/readers/dbml/README.md
Normal file
101
pkg/readers/dbml/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# DBML Reader
|
||||
|
||||
Reads Database Markup Language (DBML) files and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The DBML Reader parses `.dbml` files that define database schemas using the DBML syntax (used by dbdiagram.io) and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses DBML syntax
|
||||
- Extracts tables, columns, and relationships
|
||||
- Supports DBML-specific features:
|
||||
- Table groups and notes
|
||||
- Enum definitions
|
||||
- Indexes
|
||||
- Foreign key relationships
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/dbml"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/schema.dbml",
|
||||
}
|
||||
|
||||
reader := dbml.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read DBML file and convert to JSON
|
||||
relspec --input dbml --in-file schema.dbml --output json --out-file schema.json
|
||||
|
||||
# Convert DBML to GORM models
|
||||
relspec --input dbml --in-file database.dbml --output gorm --out-file models.go
|
||||
```
|
||||
|
||||
## Example DBML File
|
||||
|
||||
```dbml
|
||||
Table users {
|
||||
id bigserial [pk, increment]
|
||||
username varchar(50) [not null, unique]
|
||||
email varchar(100) [not null]
|
||||
created_at timestamp [not null, default: `now()`]
|
||||
|
||||
Note: 'Users table'
|
||||
}
|
||||
|
||||
Table posts {
|
||||
id bigserial [pk]
|
||||
user_id bigint [not null, ref: > users.id]
|
||||
title varchar(200) [not null]
|
||||
content text
|
||||
|
||||
indexes {
|
||||
user_id
|
||||
(user_id, created_at) [name: 'idx_user_posts']
|
||||
}
|
||||
}
|
||||
|
||||
Ref: posts.user_id > users.id [delete: cascade]
|
||||
```
|
||||
|
||||
## DBML Features Supported
|
||||
|
||||
- Table definitions with columns
|
||||
- Primary keys (`pk`)
|
||||
- Not null constraints (`not null`)
|
||||
- Unique constraints (`unique`)
|
||||
- Default values (`default`)
|
||||
- Inline references (`ref`)
|
||||
- Standalone `Ref` blocks
|
||||
- Indexes and composite indexes
|
||||
- Table notes and column notes
|
||||
- Enums
|
||||
|
||||
## Notes
|
||||
|
||||
- DBML is designed for database documentation and diagramming
|
||||
- Schema name defaults to `public`
|
||||
- Relationship cardinality is preserved
|
||||
96
pkg/readers/dctx/README.md
Normal file
96
pkg/readers/dctx/README.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# DCTX Reader
|
||||
|
||||
Reads Clarion database dictionary (DCTX) files and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The DCTX Reader parses Clarion dictionary files (`.dctx`) that define database structures in the Clarion development system and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses Clarion DCTX XML format
|
||||
- Extracts file (table) and field (column) definitions
|
||||
- Supports Clarion data types
|
||||
- Handles keys (indexes) and relationships
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/dctx"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/database.dctx",
|
||||
}
|
||||
|
||||
reader := dctx.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read DCTX file and convert to JSON
|
||||
relspec --input dctx --in-file legacy.dctx --output json --out-file schema.json
|
||||
|
||||
# Convert DCTX to GORM models for migration
|
||||
relspec --input dctx --in-file app.dctx --output gorm --out-file models.go
|
||||
|
||||
# Export DCTX to PostgreSQL DDL
|
||||
relspec --input dctx --in-file database.dctx --output pgsql --out-file schema.sql
|
||||
```
|
||||
|
||||
## Example DCTX Structure
|
||||
|
||||
DCTX files are XML-based Clarion dictionary files that define:
|
||||
|
||||
- Files (equivalent to tables)
|
||||
- Fields (columns) with Clarion-specific types
|
||||
- Keys (indexes)
|
||||
- Relationships between files
|
||||
|
||||
Common Clarion data types:
|
||||
- `STRING` - Fixed-length string
|
||||
- `CSTRING` - C-style null-terminated string
|
||||
- `LONG` - 32-bit integer
|
||||
- `SHORT` - 16-bit integer
|
||||
- `DECIMAL` - Decimal number
|
||||
- `REAL` - Floating point
|
||||
- `DATE` - Date field
|
||||
- `TIME` - Time field
|
||||
|
||||
## Type Mapping
|
||||
|
||||
The reader automatically maps Clarion data types to standard SQL types:
|
||||
|
||||
| Clarion Type | SQL Type |
|
||||
|--------------|----------|
|
||||
| STRING | VARCHAR |
|
||||
| CSTRING | VARCHAR |
|
||||
| LONG | INTEGER |
|
||||
| SHORT | SMALLINT |
|
||||
| DECIMAL | NUMERIC |
|
||||
| REAL | REAL |
|
||||
| DATE | DATE |
|
||||
| TIME | TIME |
|
||||
|
||||
## Notes
|
||||
|
||||
- DCTX is specific to Clarion development platform
|
||||
- Useful for migrating legacy Clarion applications
|
||||
- Schema name defaults to `public`
|
||||
- Preserves field properties and constraints where possible
|
||||
96
pkg/readers/drawdb/README.md
Normal file
96
pkg/readers/drawdb/README.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# DrawDB Reader
|
||||
|
||||
Reads DrawDB schema files and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The DrawDB Reader parses JSON files exported from DrawDB (a free online database design tool) and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses DrawDB JSON format
|
||||
- Extracts tables, fields, and relationships
|
||||
- Supports DrawDB-specific metadata
|
||||
- Preserves visual layout information
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/drawdb"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/diagram.json",
|
||||
}
|
||||
|
||||
reader := drawdb.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read DrawDB export and convert to JSON schema
|
||||
relspec --input drawdb --in-file diagram.json --output json --out-file schema.json
|
||||
|
||||
# Convert DrawDB design to GORM models
|
||||
relspec --input drawdb --in-file design.json --output gorm --out-file models.go
|
||||
```
|
||||
|
||||
## Example DrawDB Export
|
||||
|
||||
DrawDB exports database designs as JSON files containing:
|
||||
|
||||
```json
|
||||
{
|
||||
"tables": [
|
||||
{
|
||||
"id": "1",
|
||||
"name": "users",
|
||||
"fields": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "BIGINT",
|
||||
"primary": true,
|
||||
"autoIncrement": true
|
||||
},
|
||||
{
|
||||
"name": "username",
|
||||
"type": "VARCHAR",
|
||||
"size": 50,
|
||||
"notNull": true,
|
||||
"unique": true
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"relationships": [
|
||||
{
|
||||
"source": "posts",
|
||||
"target": "users",
|
||||
"type": "many-to-one"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- DrawDB is a free online database designer at drawdb.vercel.app
|
||||
- Export format preserves visual design metadata
|
||||
- Useful for converting visual designs to code
|
||||
- Schema defaults to `public`
|
||||
90
pkg/readers/drizzle/README.md
Normal file
90
pkg/readers/drizzle/README.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Drizzle Reader
|
||||
|
||||
Reads TypeScript/JavaScript files containing Drizzle ORM schema definitions and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The Drizzle Reader parses Drizzle ORM schema files (TypeScript/JavaScript) that define database tables using Drizzle's schema builder and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses Drizzle schema definitions
|
||||
- Extracts table, column, and relationship information
|
||||
- Supports various Drizzle column types
|
||||
- Handles constraints and indexes
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/drizzle"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/schema.ts",
|
||||
}
|
||||
|
||||
reader := drizzle.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read Drizzle schema and convert to JSON
|
||||
relspec --input drizzle --in-file schema.ts --output json --out-file schema.json
|
||||
|
||||
# Convert Drizzle to GORM models
|
||||
relspec --input drizzle --in-file schema/ --output gorm --out-file models.go
|
||||
```
|
||||
|
||||
## Example Drizzle Schema
|
||||
|
||||
```typescript
|
||||
import { pgTable, serial, varchar, text, timestamp, integer } from 'drizzle-orm/pg-core';
|
||||
import { relations } from 'drizzle-orm';
|
||||
|
||||
export const users = pgTable('users', {
|
||||
id: serial('id').primaryKey(),
|
||||
username: varchar('username', { length: 50 }).notNull().unique(),
|
||||
email: varchar('email', { length: 100 }).notNull(),
|
||||
createdAt: timestamp('created_at').notNull().defaultNow(),
|
||||
});
|
||||
|
||||
export const posts = pgTable('posts', {
|
||||
id: serial('id').primaryKey(),
|
||||
userId: integer('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
|
||||
title: varchar('title', { length: 200 }).notNull(),
|
||||
content: text('content'),
|
||||
});
|
||||
|
||||
export const usersRelations = relations(users, ({ many }) => ({
|
||||
posts: many(posts),
|
||||
}));
|
||||
|
||||
export const postsRelations = relations(posts, ({ one }) => ({
|
||||
user: one(users, {
|
||||
fields: [posts.userId],
|
||||
references: [users.id],
|
||||
}),
|
||||
}));
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Supports both PostgreSQL and MySQL Drizzle schemas
|
||||
- Extracts relationship information from `relations` definitions
|
||||
- Schema defaults to `public` for PostgreSQL
|
||||
141
pkg/readers/gorm/README.md
Normal file
141
pkg/readers/gorm/README.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# GORM Reader
|
||||
|
||||
Reads Go source files containing GORM model definitions and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The GORM Reader parses Go source code files that define GORM models (structs with `gorm` struct tags) and converts them into RelSpec's internal database model representation. It supports reading from individual files or entire directories.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses GORM struct tags to extract column definitions
|
||||
- Extracts table names from `TableName()` methods
|
||||
- Identifies primary keys, foreign keys, and indexes
|
||||
- Supports relationship detection (has-many, belongs-to)
|
||||
- Handles both single files and directories
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/gorm"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Read from a single file
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/models.go",
|
||||
}
|
||||
|
||||
reader := gorm.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### Reading from Directory
|
||||
|
||||
```go
|
||||
// Read all .go files from a directory
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/models/",
|
||||
}
|
||||
|
||||
reader := gorm.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read GORM models and convert to JSON
|
||||
relspec --input gorm --in-file models/ --output json --out-file schema.json
|
||||
|
||||
# Convert GORM models to Bun
|
||||
relspec --input gorm --in-file models.go --output bun --out-file bun_models.go
|
||||
```
|
||||
|
||||
## Supported GORM Tags
|
||||
|
||||
The reader recognizes the following GORM struct tags:
|
||||
|
||||
- `column` - Column name
|
||||
- `type` - SQL data type (e.g., `varchar(255)`, `bigint`)
|
||||
- `primaryKey` or `primary_key` - Mark as primary key
|
||||
- `not null` - NOT NULL constraint
|
||||
- `autoIncrement` - Auto-increment column
|
||||
- `default` - Default value
|
||||
- `size` - Column size/length
|
||||
- `index` - Create index
|
||||
- `uniqueIndex` - Create unique index
|
||||
- `unique` - Unique constraint
|
||||
- `foreignKey` - Foreign key column
|
||||
- `references` - Referenced column
|
||||
- `constraint` - Constraint behavior (OnDelete, OnUpdate)
|
||||
|
||||
## Example GORM Model
|
||||
|
||||
```go
|
||||
package models
|
||||
|
||||
import (
|
||||
"time"
|
||||
"gorm.io/gorm"
|
||||
)
|
||||
|
||||
type ModelUser struct {
|
||||
gorm.Model
|
||||
ID int64 `gorm:"column:id;type:bigint;primaryKey;autoIncrement"`
|
||||
Username string `gorm:"column:username;type:varchar(50);not null;uniqueIndex"`
|
||||
Email string `gorm:"column:email;type:varchar(100);not null"`
|
||||
CreatedAt time.Time `gorm:"column:created_at;type:timestamp;not null;default:now()"`
|
||||
|
||||
// Relationships
|
||||
Posts []*ModelPost `gorm:"foreignKey:UserID;references:ID;constraint:OnDelete:CASCADE"`
|
||||
}
|
||||
|
||||
func (ModelUser) TableName() string {
|
||||
return "public.users"
|
||||
}
|
||||
|
||||
type ModelPost struct {
|
||||
ID int64 `gorm:"column:id;type:bigint;primaryKey"`
|
||||
UserID int64 `gorm:"column:user_id;type:bigint;not null"`
|
||||
Title string `gorm:"column:title;type:varchar(200);not null"`
|
||||
Content string `gorm:"column:content;type:text"`
|
||||
|
||||
// Belongs-to relationship
|
||||
User *ModelUser `gorm:"foreignKey:UserID;references:ID"`
|
||||
}
|
||||
|
||||
func (ModelPost) TableName() string {
|
||||
return "public.posts"
|
||||
}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Test files (ending in `_test.go`) are automatically excluded
|
||||
- The `gorm.Model` embedded struct is automatically recognized and skipped
|
||||
- Table names are derived from struct names if `TableName()` method is not present
|
||||
- Schema defaults to `public` if not specified in `TableName()`
|
||||
- Relationships are inferred from GORM relationship tags
|
||||
|
||||
## Limitations
|
||||
|
||||
- Complex relationship types (many-to-many with join tables) may need manual verification
|
||||
- Custom GORM types may not be fully supported
|
||||
- Some advanced GORM features may not be captured
|
||||
152
pkg/readers/json/README.md
Normal file
152
pkg/readers/json/README.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# JSON Reader
|
||||
|
||||
Reads database schema definitions from JSON files.
|
||||
|
||||
## Overview
|
||||
|
||||
The JSON Reader parses JSON files that define database schemas in RelSpec's canonical JSON format and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Reads RelSpec's standard JSON schema format
|
||||
- Supports complete schema representation including:
|
||||
- Databases and schemas
|
||||
- Tables, columns, and data types
|
||||
- Constraints (PK, FK, unique, check)
|
||||
- Indexes
|
||||
- Relationships
|
||||
- Views and sequences
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/json"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/schema.json",
|
||||
}
|
||||
|
||||
reader := json.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read JSON schema and convert to GORM models
|
||||
relspec --input json --in-file schema.json --output gorm --out-file models.go
|
||||
|
||||
# Convert JSON to PostgreSQL DDL
|
||||
relspec --input json --in-file database.json --output pgsql --out-file schema.sql
|
||||
|
||||
# Transform JSON to YAML
|
||||
relspec --input json --in-file schema.json --output yaml --out-file schema.yaml
|
||||
```
|
||||
|
||||
## Example JSON Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "myapp",
|
||||
"database_type": "postgresql",
|
||||
"schemas": [
|
||||
{
|
||||
"name": "public",
|
||||
"tables": [
|
||||
{
|
||||
"name": "users",
|
||||
"schema": "public",
|
||||
"columns": {
|
||||
"id": {
|
||||
"name": "id",
|
||||
"type": "bigint",
|
||||
"not_null": true,
|
||||
"is_primary_key": true,
|
||||
"auto_increment": true,
|
||||
"sequence": 1
|
||||
},
|
||||
"username": {
|
||||
"name": "username",
|
||||
"type": "varchar",
|
||||
"length": 50,
|
||||
"not_null": true,
|
||||
"sequence": 2
|
||||
},
|
||||
"email": {
|
||||
"name": "email",
|
||||
"type": "varchar",
|
||||
"length": 100,
|
||||
"not_null": true,
|
||||
"sequence": 3
|
||||
}
|
||||
},
|
||||
"constraints": {
|
||||
"pk_users": {
|
||||
"name": "pk_users",
|
||||
"type": "PRIMARY KEY",
|
||||
"columns": ["id"]
|
||||
},
|
||||
"uq_users_username": {
|
||||
"name": "uq_users_username",
|
||||
"type": "UNIQUE",
|
||||
"columns": ["username"]
|
||||
}
|
||||
},
|
||||
"indexes": {
|
||||
"idx_users_email": {
|
||||
"name": "idx_users_email",
|
||||
"columns": ["email"],
|
||||
"unique": false,
|
||||
"type": "btree"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Schema Structure
|
||||
|
||||
The JSON format follows RelSpec's internal model structure:
|
||||
|
||||
- `Database` - Top-level container
|
||||
- `name` - Database name
|
||||
- `database_type` - Database system (postgresql, mysql, etc.)
|
||||
- `schemas[]` - Array of schemas
|
||||
|
||||
- `Schema` - Schema/namespace
|
||||
- `name` - Schema name
|
||||
- `tables[]` - Array of tables
|
||||
- `views[]` - Array of views
|
||||
- `sequences[]` - Array of sequences
|
||||
|
||||
- `Table` - Table definition
|
||||
- `name` - Table name
|
||||
- `columns{}` - Map of columns
|
||||
- `constraints{}` - Map of constraints
|
||||
- `indexes{}` - Map of indexes
|
||||
- `relationships{}` - Map of relationships
|
||||
|
||||
## Notes
|
||||
|
||||
- This is RelSpec's native interchange format
|
||||
- Preserves complete schema information
|
||||
- Ideal for version control and schema documentation
|
||||
- Can be used as an intermediate format for transformations
|
||||
138
pkg/readers/pgsql/README.md
Normal file
138
pkg/readers/pgsql/README.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# PostgreSQL Reader
|
||||
|
||||
Reads schema information directly from a live PostgreSQL database.
|
||||
|
||||
## Overview
|
||||
|
||||
The PostgreSQL Reader connects to a PostgreSQL database and introspects its schema, extracting complete information about tables, columns, constraints, indexes, views, and sequences.
|
||||
|
||||
## Features
|
||||
|
||||
- Direct database introspection
|
||||
- Extracts complete schema information including:
|
||||
- Tables and columns
|
||||
- Primary keys, foreign keys, unique constraints, check constraints
|
||||
- Indexes
|
||||
- Views
|
||||
- Sequences
|
||||
- Supports multiple schemas
|
||||
- Captures constraint actions (ON DELETE, ON UPDATE)
|
||||
- Derives relationships from foreign keys
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/pgsql"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
ConnectionString: "postgres://user:password@localhost:5432/mydb?sslmode=disable",
|
||||
}
|
||||
|
||||
reader := pgsql.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Database: %s\n", db.Name)
|
||||
fmt.Printf("Schemas: %d\n", len(db.Schemas))
|
||||
for _, schema := range db.Schemas {
|
||||
fmt.Printf(" Schema: %s, Tables: %d\n", schema.Name, len(schema.Tables))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Inspect PostgreSQL database and export to JSON
|
||||
relspec --input pgsql \
|
||||
--conn "postgres://user:password@localhost:5432/mydb" \
|
||||
--output json \
|
||||
--out-file schema.json
|
||||
|
||||
# Generate GORM models from PostgreSQL database
|
||||
relspec --input pgsql \
|
||||
--conn "postgres://user:password@localhost:5432/mydb" \
|
||||
--output gorm \
|
||||
--out-file models.go
|
||||
|
||||
# Export database structure to YAML
|
||||
relspec --input pgsql \
|
||||
--conn "postgres://localhost/mydb?sslmode=disable" \
|
||||
--output yaml \
|
||||
--out-file schema.yaml
|
||||
```
|
||||
|
||||
## Connection String Format
|
||||
|
||||
The reader uses PostgreSQL connection strings in the format:
|
||||
|
||||
```
|
||||
postgres://username:password@hostname:port/database?parameters
|
||||
```
|
||||
|
||||
Examples:
|
||||
```
|
||||
postgres://localhost/mydb
|
||||
postgres://user:pass@localhost:5432/mydb
|
||||
postgres://user@localhost/mydb?sslmode=disable
|
||||
postgres://user:pass@db.example.com:5432/production?sslmode=require
|
||||
```
|
||||
|
||||
## Extracted Information
|
||||
|
||||
### Tables
|
||||
- Table name and schema
|
||||
- Comments/descriptions
|
||||
- All columns with data types, nullable, defaults
|
||||
- Sequences
|
||||
|
||||
### Columns
|
||||
- Column name, data type, length/precision
|
||||
- NULL/NOT NULL constraints
|
||||
- Default values
|
||||
- Auto-increment information
|
||||
- Primary key designation
|
||||
|
||||
### Constraints
|
||||
- Primary keys
|
||||
- Foreign keys (with ON DELETE/UPDATE actions)
|
||||
- Unique constraints
|
||||
- Check constraints
|
||||
|
||||
### Indexes
|
||||
- Index name and type (btree, hash, gist, gin, etc.)
|
||||
- Columns in index
|
||||
- Unique/non-unique
|
||||
- Partial indexes
|
||||
|
||||
### Views
|
||||
- View definitions
|
||||
- Column information
|
||||
|
||||
### Sequences
|
||||
- Sequence properties
|
||||
- Associated tables
|
||||
|
||||
## Notes
|
||||
|
||||
- Requires PostgreSQL connection permissions
|
||||
- Reads all non-system schemas (excludes pg_catalog, information_schema, pg_toast)
|
||||
- Captures PostgreSQL-specific data types
|
||||
- Automatically maps PostgreSQL types to canonical types
|
||||
- Preserves relationship metadata for downstream conversion
|
||||
|
||||
## Requirements
|
||||
|
||||
- Go library: `github.com/jackc/pgx/v5`
|
||||
- Database user must have SELECT permissions on system catalogs
|
||||
103
pkg/readers/prisma/README.md
Normal file
103
pkg/readers/prisma/README.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Prisma Reader
|
||||
|
||||
Reads Prisma schema files and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The Prisma Reader parses `.prisma` schema files that define database models using Prisma's schema language and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses Prisma schema syntax
|
||||
- Extracts models, fields, and relationships
|
||||
- Supports Prisma attributes and directives
|
||||
- Handles enums and composite types
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/prisma"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/schema.prisma",
|
||||
}
|
||||
|
||||
reader := prisma.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read Prisma schema and convert to JSON
|
||||
relspec --input prisma --in-file schema.prisma --output json --out-file schema.json
|
||||
|
||||
# Convert Prisma to GORM models
|
||||
relspec --input prisma --in-file schema.prisma --output gorm --out-file models.go
|
||||
```
|
||||
|
||||
## Example Prisma Schema
|
||||
|
||||
```prisma
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
url = env("DATABASE_URL")
|
||||
}
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client-js"
|
||||
}
|
||||
|
||||
model User {
|
||||
id Int @id @default(autoincrement())
|
||||
username String @unique @db.VarChar(50)
|
||||
email String @db.VarChar(100)
|
||||
createdAt DateTime @default(now()) @map("created_at")
|
||||
|
||||
posts Post[]
|
||||
|
||||
@@map("users")
|
||||
}
|
||||
|
||||
model Post {
|
||||
id Int @id @default(autoincrement())
|
||||
userId Int @map("user_id")
|
||||
title String @db.VarChar(200)
|
||||
content String @db.Text
|
||||
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@map("posts")
|
||||
}
|
||||
```
|
||||
|
||||
## Supported Prisma Attributes
|
||||
|
||||
- `@id` - Primary key
|
||||
- `@unique` - Unique constraint
|
||||
- `@default` - Default value
|
||||
- `@map` - Column name mapping
|
||||
- `@@map` - Table name mapping
|
||||
- `@relation` - Relationship definition
|
||||
- `@db.*` - Database-specific type annotations
|
||||
|
||||
## Notes
|
||||
|
||||
- Extracts datasource provider information
|
||||
- Supports `@@map` for custom table names
|
||||
- Handles Prisma-specific types and converts them to standard SQL types
|
||||
122
pkg/readers/typeorm/README.md
Normal file
122
pkg/readers/typeorm/README.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# TypeORM Reader
|
||||
|
||||
Reads TypeScript files containing TypeORM entity definitions and extracts database schema information.
|
||||
|
||||
## Overview
|
||||
|
||||
The TypeORM Reader parses TypeScript source files that define TypeORM entities (classes with TypeORM decorators) and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Parses TypeORM decorators and entity definitions
|
||||
- Extracts table, column, and relationship information
|
||||
- Supports various TypeORM column types and options
|
||||
- Handles constraints, indexes, and relationships
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/typeorm"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/entities/",
|
||||
}
|
||||
|
||||
reader := typeorm.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read TypeORM entities and convert to JSON
|
||||
relspec --input typeorm --in-file entities/ --output json --out-file schema.json
|
||||
|
||||
# Convert TypeORM to GORM models
|
||||
relspec --input typeorm --in-file User.ts --output gorm --out-file models.go
|
||||
```
|
||||
|
||||
## Example TypeORM Entity
|
||||
|
||||
```typescript
|
||||
import {
|
||||
Entity,
|
||||
PrimaryGeneratedColumn,
|
||||
Column,
|
||||
CreateDateColumn,
|
||||
OneToMany,
|
||||
} from 'typeorm';
|
||||
import { Post } from './Post';
|
||||
|
||||
@Entity('users')
|
||||
export class User {
|
||||
@PrimaryGeneratedColumn('increment')
|
||||
id: number;
|
||||
|
||||
@Column({ type: 'varchar', length: 50, unique: true })
|
||||
username: string;
|
||||
|
||||
@Column({ type: 'varchar', length: 100 })
|
||||
email: string;
|
||||
|
||||
@CreateDateColumn({ name: 'created_at' })
|
||||
createdAt: Date;
|
||||
|
||||
@OneToMany(() => Post, (post) => post.user)
|
||||
posts: Post[];
|
||||
}
|
||||
|
||||
@Entity('posts')
|
||||
export class Post {
|
||||
@PrimaryGeneratedColumn('increment')
|
||||
id: number;
|
||||
|
||||
@Column({ name: 'user_id' })
|
||||
userId: number;
|
||||
|
||||
@Column({ type: 'varchar', length: 200 })
|
||||
title: string;
|
||||
|
||||
@Column({ type: 'text' })
|
||||
content: string;
|
||||
|
||||
@ManyToOne(() => User, (user) => user.posts, { onDelete: 'CASCADE' })
|
||||
@JoinColumn({ name: 'user_id' })
|
||||
user: User;
|
||||
}
|
||||
```
|
||||
|
||||
## Supported TypeORM Decorators
|
||||
|
||||
- `@Entity()` - Entity/table definition
|
||||
- `@PrimaryGeneratedColumn()` - Auto-increment primary key
|
||||
- `@PrimaryColumn()` - Primary key
|
||||
- `@Column()` - Column definition
|
||||
- `@CreateDateColumn()` - Auto-set creation timestamp
|
||||
- `@UpdateDateColumn()` - Auto-update timestamp
|
||||
- `@OneToMany()` - One-to-many relationship
|
||||
- `@ManyToOne()` - Many-to-one relationship
|
||||
- `@JoinColumn()` - Foreign key column
|
||||
- `@Index()` - Index definition
|
||||
- `@Unique()` - Unique constraint
|
||||
|
||||
## Notes
|
||||
|
||||
- Schema name can be specified in `@Entity()` decorator
|
||||
- Supports both JavaScript and TypeScript entity files
|
||||
- Relationship metadata is extracted from decorators
|
||||
159
pkg/readers/yaml/README.md
Normal file
159
pkg/readers/yaml/README.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# YAML Reader
|
||||
|
||||
Reads database schema definitions from YAML files.
|
||||
|
||||
## Overview
|
||||
|
||||
The YAML Reader parses YAML files that define database schemas in RelSpec's canonical YAML format and converts them into RelSpec's internal database model representation.
|
||||
|
||||
## Features
|
||||
|
||||
- Reads RelSpec's standard YAML schema format
|
||||
- Human-readable alternative to JSON format
|
||||
- Supports complete schema representation including:
|
||||
- Databases and schemas
|
||||
- Tables, columns, and data types
|
||||
- Constraints (PK, FK, unique, check)
|
||||
- Indexes
|
||||
- Relationships
|
||||
- Views and sequences
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Example
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/yaml"
|
||||
)
|
||||
|
||||
func main() {
|
||||
options := &readers.ReaderOptions{
|
||||
FilePath: "/path/to/schema.yaml",
|
||||
}
|
||||
|
||||
reader := yaml.NewReader(options)
|
||||
db, err := reader.ReadDatabase()
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d schemas\n", len(db.Schemas))
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Example
|
||||
|
||||
```bash
|
||||
# Read YAML schema and convert to GORM models
|
||||
relspec --input yaml --in-file schema.yaml --output gorm --out-file models.go
|
||||
|
||||
# Convert YAML to PostgreSQL DDL
|
||||
relspec --input yaml --in-file database.yaml --output pgsql --out-file schema.sql
|
||||
|
||||
# Transform YAML to JSON
|
||||
relspec --input yaml --in-file schema.yaml --output json --out-file schema.json
|
||||
```
|
||||
|
||||
## Example YAML Schema
|
||||
|
||||
```yaml
|
||||
name: myapp
|
||||
database_type: postgresql
|
||||
schemas:
|
||||
- name: public
|
||||
tables:
|
||||
- name: users
|
||||
schema: public
|
||||
columns:
|
||||
id:
|
||||
name: id
|
||||
type: bigint
|
||||
not_null: true
|
||||
is_primary_key: true
|
||||
auto_increment: true
|
||||
sequence: 1
|
||||
username:
|
||||
name: username
|
||||
type: varchar
|
||||
length: 50
|
||||
not_null: true
|
||||
sequence: 2
|
||||
email:
|
||||
name: email
|
||||
type: varchar
|
||||
length: 100
|
||||
not_null: true
|
||||
sequence: 3
|
||||
constraints:
|
||||
pk_users:
|
||||
name: pk_users
|
||||
type: PRIMARY KEY
|
||||
columns:
|
||||
- id
|
||||
uq_users_username:
|
||||
name: uq_users_username
|
||||
type: UNIQUE
|
||||
columns:
|
||||
- username
|
||||
indexes:
|
||||
idx_users_email:
|
||||
name: idx_users_email
|
||||
columns:
|
||||
- email
|
||||
unique: false
|
||||
type: btree
|
||||
- name: posts
|
||||
schema: public
|
||||
columns:
|
||||
id:
|
||||
name: id
|
||||
type: bigint
|
||||
not_null: true
|
||||
is_primary_key: true
|
||||
sequence: 1
|
||||
user_id:
|
||||
name: user_id
|
||||
type: bigint
|
||||
not_null: true
|
||||
sequence: 2
|
||||
title:
|
||||
name: title
|
||||
type: varchar
|
||||
length: 200
|
||||
not_null: true
|
||||
sequence: 3
|
||||
constraints:
|
||||
fk_posts_user_id:
|
||||
name: fk_posts_user_id
|
||||
type: FOREIGN KEY
|
||||
columns:
|
||||
- user_id
|
||||
referenced_table: users
|
||||
referenced_schema: public
|
||||
referenced_columns:
|
||||
- id
|
||||
on_delete: CASCADE
|
||||
on_update: NO ACTION
|
||||
```
|
||||
|
||||
## Schema Structure
|
||||
|
||||
The YAML format mirrors RelSpec's internal model structure with human-readable syntax:
|
||||
|
||||
- Database level: `name`, `database_type`, `schemas`
|
||||
- Schema level: `name`, `tables`, `views`, `sequences`
|
||||
- Table level: `name`, `schema`, `columns`, `constraints`, `indexes`, `relationships`
|
||||
- Column level: `name`, `type`, `length`, `not_null`, `default`, etc.
|
||||
|
||||
## Notes
|
||||
|
||||
- YAML format is more human-readable than JSON
|
||||
- Ideal for manual editing and version control
|
||||
- Comments are supported in YAML
|
||||
- Preserves complete schema information
|
||||
- Can be used for configuration and documentation
|
||||
Reference in New Issue
Block a user