Skip to content

Commit 2a4ba85

Browse files
sunarysunary
authored
bump version (#65)
* bump version
1 parent 892c78e commit 2a4ba85

File tree

5 files changed

+249
-225
lines changed

5 files changed

+249
-225
lines changed

‎README.md‎

Lines changed: 91 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,100 @@
44

55
English | [中文](README_zh.md)
66

7-
SQLize is a powerful migration generation tool that detects differences between two SQL state sources. It simplifies migration creation by comparing an existing SQL schema with Go models, ensuring seamless database updates.
7+
## Purpose
88

9-
Designed for flexibility, SQLize supports `MySQL`, `PostgreSQL`, and `SQLite` and integrates well with popular Go ORM and migration tools like `gorm` (gorm tag), `golang-migrate/migrate` (migration version), and more.
9+
**SQLize** generates database migrations by comparing two schema sources: your **Go structs** (desired state) and your **existing migrations** (current state). Instead of writing migration SQL by hand, you define models in Go and SQLize produces the `ALTER TABLE`, `CREATE TABLE`, and related statements needed to bring your database up to date.
1010

11-
Additionally, SQLize offers advanced features, including `Avro Schema` export (MySQL only) and `ERD` diagram generation (`MermaidJS`).
11+
### What problem does it solve?
12+
13+
- **Manual migrations are error-prone** — Easy to forget columns, indexes, or foreign keys when writing `ALTER TABLE` by hand
14+
- **Schema drift** — Go models and the database can get out of sync over time
15+
- **Boilerplate** — Repetitive work creating up/down migrations for every schema change
16+
17+
### How it works
18+
19+
1. **Desired state** — Load schema from your Go structs (via `FromObjects`)
20+
2. **Current state** — Load schema from your migration folder (via `FromMigrationFolder`)
21+
3. **Diff** — SQLize compares them and computes the changes
22+
4. **Output** — Get migration SQL (`StringUp` / `StringDown`) or write files directly (`WriteFilesWithVersion`)
23+
24+
```
25+
Go structs (desired) ──┐
26+
├──► Diff ──► Migration SQL (up/down)
27+
Migration files (current) ─┘
28+
```
29+
30+
## Features
31+
32+
- **Multi-database**: MySQL, PostgreSQL, SQLite, SQL Server
33+
- **ORM-friendly**: Works with struct tags (`sql`, `gorm`), compatible with `golang-migrate/migrate`
34+
- **Schema export**: Avro Schema (MySQL), ERD diagrams (MermaidJS)
35+
36+
## Installation
37+
38+
```bash
39+
go get github.com/sunary/sqlize
40+
```
41+
42+
## Quick Start
43+
44+
```golang
45+
package main
46+
47+
import (
48+
"fmt"
49+
"log"
50+
"os"
51+
52+
"github.com/sunary/sqlize"
53+
)
54+
55+
func main() {
56+
migrationFolder := "migrations/"
57+
sqlLatest := sqlize.NewSqlize(
58+
sqlize.WithSqlTag("sql"),
59+
sqlize.WithMigrationFolder(migrationFolder),
60+
sqlize.WithCommentGenerate(),
61+
)
62+
63+
ms := YourModels() // Return your Go models
64+
err := sqlLatest.FromObjects(ms...)
65+
if err != nil {
66+
log.Fatal("sqlize FromObjects", err)
67+
}
68+
sqlVersion := sqlLatest.HashValue()
69+
70+
sqlMigrated := sqlize.NewSqlize(sqlize.WithMigrationFolder(migrationFolder))
71+
err = sqlMigrated.FromMigrationFolder()
72+
if err != nil {
73+
log.Fatal("sqlize FromMigrationFolder", err)
74+
}
75+
76+
sqlLatest.Diff(*sqlMigrated)
77+
78+
fmt.Println("sql version", sqlVersion)
79+
fmt.Println("\n### migration up")
80+
fmt.Println(sqlLatest.StringUp())
81+
fmt.Println("\n### migration down")
82+
fmt.Println(sqlLatest.StringDown())
83+
84+
if len(os.Args) > 1 {
85+
err = sqlLatest.WriteFilesWithVersion(os.Args[1], sqlVersion, false)
86+
if err != nil {
87+
log.Fatal("sqlize WriteFilesWithVersion", err)
88+
}
89+
}
90+
}
91+
```
1292

1393
## Conventions
1494

1595
### Default Behaviors
1696

17-
- Database: `mysql` (use `sql_builder.WithPostgresql()` for PostgreSQL, etc.)
18-
- SQL syntax: Uppercase (e.g., `"SELECT * FROM user WHERE id = ?"`)
19-
- For lowercase, use `sql_builder.WithSqlLowercase()`
20-
- Table naming: Singular
21-
- For plural (adding 's'), use `sql_builder.WithPluralTableName()`
22-
- Comment generation: Use `sql_builder.WithCommentGenerate()`
97+
- Database: `mysql` (use `sqlize.WithPostgresql()`, `sqlize.WithSqlite()`, etc.)
98+
- SQL syntax: Uppercase (use `sqlize.WithSqlLowercase()` for lowercase)
99+
- Table naming: Singular (use `sqlize.WithPluralTableName()` for plural)
100+
- Comment generation: `sqlize.WithCommentGenerate()`
23101

24102
### SQL Tag Options
25103

@@ -53,12 +131,12 @@ Additionally, SQLize offers advanced features, including `Avro Schema` export (M
53131
- MySQL data types are implicitly changed:
54132

55133
```sql
56-
TINYINT => tinyint(4)
57-
INT => int(11)
58-
BIGINT => bigint(20)
134+
TINYINT => tinyint(4)
135+
INT => int(11)
136+
BIGINT => bigint(20)
59137
```
60138

61-
- Pointer values must be declared in the struct or predefined data types.
139+
- Pointer values must be declared in the struct or predefined data types:
62140

63141
```golang
64142
// your struct
@@ -84,69 +162,3 @@ type Record struct {
84162
DeletedAt sql.NullTime
85163
}
86164
```
87-
88-
## Usage
89-
90-
- Add the following code to your project as a command.
91-
- Implement `YourModels()` to return the Go models affected by the migration.
92-
- Run the command whenever you need to generate a migration.
93-
94-
```golang
95-
package main
96-
97-
import (
98-
"fmt"
99-
"log"
100-
"os"
101-
102-
"github.com/sunary/sqlize"
103-
)
104-
105-
func main() {
106-
migrationFolder := "migrations/"
107-
sqlLatest := sqlize.NewSqlize(sqlize.WithSqlTag("sql"),
108-
sqlize.WithMigrationFolder(migrationFolder),
109-
sqlize.WithCommentGenerate())
110-
111-
ms := YourModels() // TODO: implement YourModels() function
112-
err := sqlLatest.FromObjects(ms...)
113-
if err != nil {
114-
log.Fatal("sqlize FromObjects", err)
115-
}
116-
sqlVersion := sqlLatest.HashValue()
117-
118-
sqlMigrated := sqlize.NewSqlize(sqlize.WithMigrationFolder(migrationFolder))
119-
err = sqlMigrated.FromMigrationFolder()
120-
if err != nil {
121-
log.Fatal("sqlize FromMigrationFolder", err)
122-
}
123-
124-
sqlLatest.Diff(*sqlMigrated)
125-
126-
fmt.Println("sql version", sqlVersion)
127-
128-
fmt.Println("\n\n### migration up")
129-
migrationUp := sqlLatest.StringUp()
130-
fmt.Println(migrationUp)
131-
132-
fmt.Println("\n\n### migration down")
133-
fmt.Println(sqlLatest.StringDown())
134-
135-
initVersion := false
136-
if initVersion {
137-
log.Println("write to init version")
138-
err = sqlLatest.WriteFilesVersion("new version", 0, false)
139-
if err != nil {
140-
log.Fatal("sqlize WriteFilesVersion", err)
141-
}
142-
}
143-
144-
if len(os.Args) > 1 {
145-
log.Println("write to file", os.Args[1])
146-
err = sqlLatest.WriteFilesWithVersion(os.Args[1], sqlVersion, false)
147-
if err != nil {
148-
log.Fatal("sqlize WriteFilesWithVersion", err)
149-
}
150-
}
151-
}
152-
```

‎README_zh.md‎

Lines changed: 90 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,107 @@
1-
### SQLize
1+
# SQLize
22

33
![github action](https://github.com/sunary/sqlize/actions/workflows/go.yml/badge.svg)
44

55
[English](README.md) | 中文
66

7-
SQLize 是一款强大的迁移生成工具，可检测两个 SQL 状态源之间的差异。它通过对比现有 SQL 模式与 Go 模型，简化迁移创建过程，确保数据库平滑更新。
7+
## 项目目的
88

9-
SQLize 设计灵活，支持 `MySQL`、`PostgreSQL` 和 `SQLite`，并能与流行的 Go ORM 和迁移工具（如 `gorm`（gorm 标签）、`golang-migrate/migrate`（迁移版本）等）良好集成。
9+
**SQLize** 通过比较两个 schema 来源生成数据库迁移：你的 **Go 结构体**（期望状态）和 **已有迁移文件**（当前状态）。你只需在 Go 中定义模型，SQLize 会自动生成所需的 `ALTER TABLE`、`CREATE TABLE` 等语句，使数据库与模型保持同步。
1010

11-
此外，SQLize 还提供高级功能，包括 `Avro Schema` 导出（仅支持 MySQL）和 `ERD` 关系图生成（`MermaidJS`）。
11+
### 解决什么问题？
12+
13+
- **手写迁移容易出错** — 手写 `ALTER TABLE` 时容易遗漏列、索引或外键
14+
- **Schema 漂移** — Go 模型与数据库会随时间不同步
15+
- **重复劳动** — 每次 schema 变更都要手动编写 up/down 迁移
16+
17+
### 工作原理
18+
19+
1. **期望状态** — 从 Go 结构体加载 schema（通过 `FromObjects`）
20+
2. **当前状态** — 从迁移目录加载 schema（通过 `FromMigrationFolder`）
21+
3. **差异计算** — SQLize 比较两者并计算变更
22+
4. **输出** — 获取迁移 SQL（`StringUp` / `StringDown`）或直接写入文件（`WriteFilesWithVersion`）
23+
24+
```
25+
Go 结构体（期望） ──┐
26+
├──► Diff ──► 迁移 SQL（up/down）
27+
迁移文件（当前） ──┘
28+
```
29+
30+
## 功能特性
31+
32+
- **多数据库支持**：MySQL、PostgreSQL、SQLite、SQL Server
33+
- **ORM 友好**：支持结构体标签（`sql`、`gorm`），兼容 `golang-migrate/migrate`
34+
- **Schema 导出**：Avro Schema（MySQL）、ERD 图（MermaidJS）
35+
36+
## 安装
37+
38+
```bash
39+
go get github.com/sunary/sqlize
40+
```
41+
42+
## 快速开始
43+
44+
```golang
45+
package main
46+
47+
import (
48+
"fmt"
49+
"log"
50+
"os"
51+
52+
"github.com/sunary/sqlize"
53+
)
54+
55+
func main() {
56+
migrationFolder := "migrations/"
57+
sqlLatest := sqlize.NewSqlize(
58+
sqlize.WithSqlTag("sql"),
59+
sqlize.WithMigrationFolder(migrationFolder),
60+
sqlize.WithCommentGenerate(),
61+
)
62+
63+
ms := YourModels() // 返回你的 Go 模型
64+
err := sqlLatest.FromObjects(ms...)
65+
if err != nil {
66+
log.Fatal("sqlize FromObjects", err)
67+
}
68+
sqlVersion := sqlLatest.HashValue()
69+
70+
sqlMigrated := sqlize.NewSqlize(sqlize.WithMigrationFolder(migrationFolder))
71+
err = sqlMigrated.FromMigrationFolder()
72+
if err != nil {
73+
log.Fatal("sqlize FromMigrationFolder", err)
74+
}
75+
76+
sqlLatest.Diff(*sqlMigrated)
77+
78+
fmt.Println("sql version", sqlVersion)
79+
fmt.Println("\n### migration up")
80+
fmt.Println(sqlLatest.StringUp())
81+
fmt.Println("\n### migration down")
82+
fmt.Println(sqlLatest.StringDown())
83+
84+
if len(os.Args) > 1 {
85+
err = sqlLatest.WriteFilesWithVersion(os.Args[1], sqlVersion, false)
86+
if err != nil {
87+
log.Fatal("sqlize WriteFilesWithVersion", err)
88+
}
89+
}
90+
}
91+
```
1292

1393
## 约定
1494

1595
### 默认行为
1696

17-
- 数据库：默认为 `mysql`（使用 `sql_builder.WithPostgresql()` 可切换到 PostgreSQL 等）
18-
- SQL 语法：默认大写（例如：`"SELECT * FROM user WHERE id = ?"`）
19-
- 使用 `sql_builder.WithSqlLowercase()` 可切换为小写
20-
- 表名：默认单数
21-
- 使用 `sql_builder.WithPluralTableName()` 可自动添加 's' 实现复数命名
22-
- 注释生成：使用 `sql_builder.WithCommentGenerate()` 选项
97+
- 数据库：`mysql`（使用 `sqlize.WithPostgresql()`、`sqlize.WithSqlite()` 等切换）
98+
- SQL 语法：大写（使用 `sqlize.WithSqlLowercase()` 切换为小写）
99+
- 表名：单数（使用 `sqlize.WithPluralTableName()` 切换为复数）
100+
- 注释生成：`sqlize.WithCommentGenerate()`
23101

24102
### SQL 标签选项
25103

26-
- 格式：支持 `snake_case` 和 `camelCase`（例如：`sql:"primary_key"` 等同于 `sql:"primaryKey"`）
104+
- 格式：支持 `snake_case` 和 `camelCase`（例如 `sql:"primary_key"` 等同于 `sql:"primaryKey"`）
27105
- 自定义列名：`sql:"column:column_name"`
28106
- 主键：`sql:"primary_key"`
29107
- 外键：`sql:"foreign_key:user_id;references:user_id"`
@@ -46,7 +124,7 @@ SQLize 设计灵活，支持 `MySQL`、`PostgreSQL` 和 `SQLite`，并能与流
46124
- 使用 `sql:"embedded"` 或 `sql:"squash"`
47125
- 不能是指针
48126
- 支持前缀：`sql:"embedded_prefix:base_"`
49-
- 字段具有最低顺序，除了主键（始终在首位）
127+
- 字段具有最低顺序，主键除外（始终在首位）
50128

51129
### 数据类型
52130

@@ -84,69 +162,3 @@ type Record struct {
84162
DeletedAt sql.NullTime
85163
}
86164
```
87-
88-
### 使用方法
89-
90-
- 将以下代码添加到您的项目中作为命令。
91-
- 实现 YourModels()，返回受迁移影响的 Go 模型。
92-
- 需要生成迁移时，运行该命令。
93-
94-
```golang
95-
package main
96-
97-
import (
98-
"fmt"
99-
"log"
100-
"os"
101-
102-
"github.com/sunary/sqlize"
103-
)
104-
105-
func main() {
106-
migrationFolder := "migrations/"
107-
sqlLatest := sqlize.NewSqlize(sqlize.WithSqlTag("sql"),
108-
sqlize.WithMigrationFolder(migrationFolder),
109-
sqlize.WithCommentGenerate())
110-
111-
ms := YourModels() // TODO: implement YourModels() function
112-
err := sqlLatest.FromObjects(ms...)
113-
if err != nil {
114-
log.Fatal("sqlize FromObjects", err)
115-
}
116-
sqlVersion := sqlLatest.HashValue()
117-
118-
sqlMigrated := sqlize.NewSqlize(sqlize.WithMigrationFolder(migrationFolder))
119-
err = sqlMigrated.FromMigrationFolder()
120-
if err != nil {
121-
log.Fatal("sqlize FromMigrationFolder", err)
122-
}
123-
124-
sqlLatest.Diff(*sqlMigrated)
125-
126-
fmt.Println("sql version", sqlVersion)
127-
128-
fmt.Println("\n\n### migration up")
129-
migrationUp := sqlLatest.StringUp()
130-
fmt.Println(migrationUp)
131-
132-
fmt.Println("\n\n### migration down")
133-
fmt.Println(sqlLatest.StringDown())
134-
135-
initVersion := false
136-
if initVersion {
137-
log.Println("write to init version")
138-
err = sqlLatest.WriteFilesVersion("new version", 0, false)
139-
if err != nil {
140-
log.Fatal("sqlize WriteFilesVersion", err)
141-
}
142-
}
143-
144-
if len(os.Args) > 1 {
145-
log.Println("write to file", os.Args[1])
146-
err = sqlLatest.WriteFilesWithVersion(os.Args[1], sqlVersion, false)
147-
if err != nil {
148-
log.Fatal("sqlize WriteFilesWithVersion", err)
149-
}
150-
}
151-
}
152-
```

0 commit comments

Comments
 (0)