Skip to content

Commit 30e2099

Browse files
Fs02Fs02
authored
add primary-replica and migration api docs (#31)
1 parent 0160f45 commit 30e2099

File tree

9 files changed

+120
-4
lines changed

9 files changed

+120
-4
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ jobs:
3737
'mkdocs-material-extensions==1.0.1' \
3838
'mkdocs-minify-plugin==0.3.0' \
3939
'mkdocs-macros-plugin==0.4.15' \
40-
'mkdocs-git-revision-date-plugin==0.3'
40+
'mkdocs-git-revision-date-plugin==0.3' \
41+
'mkdocs-meta-descriptions-plugin===1.0.2'
4142
- name: Install godoc2md
4243
working-directory: doc
4344
run: go get github.com/Yarn-e/godoc2md

‎docs/adapters.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,38 @@ Rel uses adapter in order to generate and execute query to a database, below is
88
| PostgreSQL | github.com/go-rel/postgres | [![GoDoc](https://godoc.org/github.com/go-rel/postgres?status.svg)](https://godoc.org/github.com/go-rel/postgres) |
99
| MSSQL | github.com/go-rel/mssql | [![GoDoc](https://godoc.org/github.com/go-rel/mssql?status.svg)](https://godoc.org/github.com/go-rel/mssql) |
1010
| SQLite3 | github.com/go-rel/sqlite3 | [![GoDoc](https://godoc.org/github.com/go-rel/sqlite3?status.svg)](https://godoc.org/github.com/go-rel/sqlite3) |
11+
12+
## Using Primary Replica Connections
13+
14+
REL Read Write separation for primary replica connections by using intermediary adapters.
15+
16+
```go
17+
package main
18+
19+
import (
20+
"context"
21+
22+
_ "github.com/go-sql-driver/mysql"
23+
"github.com/go-rel/primaryreplica"
24+
"github.com/go-rel/mysql"
25+
"github.com/go-rel/rel"
26+
)
27+
func main() {
28+
// open mysql connections.
29+
// note: `clientFoundRows=true` is required for update and delete to works correctly.
30+
adapter := primaryreplica.New(
31+
mysql.MustOpen("root@(source:3306)/rel_test?charset=utf8&parseTime=True&loc=Local"),
32+
mysql.MustOpen("root@(replica1:3306)/rel_test?charset=utf8&parseTime=True&loc=Local"),
33+
mysql.MustOpen("root@(replica2:3306)/rel_test?charset=utf8&parseTime=True&loc=Local"),
34+
)
35+
defer adapter.Close()
36+
37+
// initialize REL's repo.
38+
repo := rel.New(adapter)
39+
repo.Ping(context.TODO())
40+
}
41+
```
42+
43+
### Load Balancing of Replicas
44+
45+
REL only implements a very primitive load balancing for multiple replicas. For large scale application we recommend you to use external load balancing solution.

‎docs/migration.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Migrate and rollback function name is the camel cased file name without version.
1313
!!! note
1414
Sample project that demonstrate this setup can be found at https://github.com/go-rel/gin-example
1515

16-
{{ embed_code("examples/migrations/20202806225100_create_todos.go") }}
16+
{{ embed_code("examples/db/migrations/20202806225100_create_todos.go") }}
1717

1818
## Running Migration
1919

@@ -76,3 +76,9 @@ By default, REL will try to use database connection info that available as envir
7676
```bash
7777
rel migrate -adapter=github.com/go-rel/rel/adapter/sqlite3 -driver=github.com/mattn/go-sqlite3 -dsn=:memory:
7878
```
79+
80+
## Migration API
81+
82+
If you need more flexibility, migration API can be used to manually execute migrations.
83+
84+
{{ embed_code("examples/db/api.go") }}

‎examples/db/api.go‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
package main
2+
3+
import (
4+
"context"
5+
6+
"github.com/go-rel/doc/examples/db/migrations"
7+
"github.com/go-rel/mysql"
8+
"github.com/go-rel/rel"
9+
"github.com/go-rel/rel/migrator"
10+
_ "github.com/go-sql-driver/mysql"
11+
)
12+
13+
func main() {
14+
var (
15+
ctx = context.TODO()
16+
repo = rel.New(mysql.MustOpen("root@(source:3306)/rel_test?charset=utf8&parseTime=True&loc=Local"))
17+
m = migrator.New(repo)
18+
)
19+
20+
// Register migrations
21+
m.Register(20202806225100, migrations.MigrateCreateTodos, migrations.RollbackCreateTodos)
22+
23+
// Run migrations
24+
m.Migrate(ctx)
25+
// OR:
26+
// m.Rollback(ctx)
27+
}

examples/migrations/20202806225100_create_todos.go renamed to examples/db/migrations/20202806225100_create_todos.go

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
package migrations
44

55
import (
6+
"context"
7+
68
"github.com/go-rel/rel"
79
)
810

@@ -18,6 +20,11 @@ func MigrateCreateTodos(schema *rel.Schema) {
1820
})
1921

2022
schema.CreateIndex("todos", "order", []string{"order"})
23+
24+
schema.Do(func(repo rel.Repository) error {
25+
// add seeds
26+
return repo.Insert(context.TODO(), &Todo{Title: "Do homework"})
27+
})
2128
}
2229

2330
// RollbackCreateTodos definition

‎examples/db/migrations/todo.go‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
package migrations
2+
3+
type Todo struct {
4+
ID int
5+
Title string
6+
}

‎go.mod‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,14 @@ module github.com/go-rel/doc
33
go 1.14
44

55
require (
6+
github.com/go-rel/mysql v0.4.0
67
github.com/go-rel/rel v0.28.0
78
github.com/go-sql-driver/mysql v1.6.0
8-
github.com/stretchr/objx v0.3.0 // indirect
9+
github.com/kr/pretty v0.1.0 // indirect
910
github.com/stretchr/testify v1.7.0
11+
golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4 // indirect
12+
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1 // indirect
13+
golang.org/x/text v0.3.7 // indirect
14+
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 // indirect
15+
gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b // indirect
1016
)

‎go.sum‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,15 @@ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
44
github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
55
github.com/fsnotify/fsnotify v1.4.9 h1:hsms1Qyu0jgnwNXIxa+/V/PDsU6CfLf6CNO8H7IWoS4=
66
github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
7+
github.com/go-rel/mysql v0.4.0 h1:VvvB6a3jmBe6MycMgJB08GBYAc/ppkLvJM6lKofdAWs=
8+
github.com/go-rel/mysql v0.4.0/go.mod h1:SvS4lhN5UQmcZAGG59J8tUyoVMvVHsr/o6y+uzLrLHs=
9+
github.com/go-rel/primaryreplica v0.1.0 h1:ARt8QHa55Tmz7hJYtGunz4B3THQiFDOJb0yZBgnrzx4=
10+
github.com/go-rel/primaryreplica v0.1.0/go.mod h1:j/b9RmL4gdnuQMh4UPBeE1h6RpQCtiUIC9QHIvgjIs8=
11+
github.com/go-rel/rel v0.27.0/go.mod h1:zaIYPmM3AfJrh0xBmm7KoVKRgTNvr0cgZfcJ88gVA2U=
712
github.com/go-rel/rel v0.28.0 h1:gRcQjNbwuFL35RxeHFMKSy3a/xV+WbtkA8wP24dWPEA=
813
github.com/go-rel/rel v0.28.0/go.mod h1:zaIYPmM3AfJrh0xBmm7KoVKRgTNvr0cgZfcJ88gVA2U=
14+
github.com/go-rel/sql v0.5.0 h1:+TVS9JvEl06Q8rswwuWlY6VZ+gwSBX9um+vKuZ9gsyY=
15+
github.com/go-rel/sql v0.5.0/go.mod h1:2YwenlIaHpTqdD/KPVYG7Y5Ub1+sn1winlC8TrighRU=
916
github.com/go-sql-driver/mysql v1.6.0 h1:BCTh4TKNUYmOmMUcQ3IipzF5prigylS7XXjEkfCHuOE=
1017
github.com/go-sql-driver/mysql v1.6.0/go.mod h1:DCzpHaOWr8IXmIStZouvnhqoel9Qv2LBy8hT2VhHyBg=
1118
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
@@ -23,6 +30,12 @@ github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/
2330
github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
2431
github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
2532
github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
33+
github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
34+
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
35+
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
36+
github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
37+
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
38+
github.com/lib/pq v1.10.3 h1:v9QZf2Sn6AmjXtQeFpdoq/eaNtYP6IN+7lcrygsIAtg=
2639
github.com/lib/pq v1.10.3/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
2740
github.com/mattn/go-sqlite3 v1.14.9 h1:10HX2Td0ocZpYEjhilsuo6WWtUqttj2Kb0KtD86/KYA=
2841
github.com/mattn/go-sqlite3 v1.14.9/go.mod h1:NyWgC/yNuGj7Q9rpYnZvas74GogHl5/Z4A/KQRfk6bU=
@@ -59,6 +72,8 @@ golang.org/x/net v0.0.0-20200520004742-59133d7f0dd7/go.mod h1:qpuaurCH72eLCgpAm/
5972
golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
6073
golang.org/x/net v0.0.0-20201202161906-c7110b5ffcbb h1:eBmm0M9fYhWpKZLjQUUKka/LtIxf46G4fxeEz5KJr9U=
6174
golang.org/x/net v0.0.0-20201202161906-c7110b5ffcbb/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
75+
golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4 h1:4nGaVu0QrbjT/AK2PRLuQfQuh6DJve+pELhqTdAj3x0=
76+
golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
6277
golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
6378
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
6479
golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -70,11 +85,18 @@ golang.org/x/sys v0.0.0-20191005200804-aed5e4c7ecf9/go.mod h1:h1NjWce9XRLGQEsW7w
7085
golang.org/x/sys v0.0.0-20191120155948-bd437916bb0e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
7186
golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
7287
golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
88+
golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
7389
golang.org/x/sys v0.0.0-20210112080510-489259a85091 h1:DMyOG0U+gKfu8JZzg2UQe9MeaC1X+xQWlAKcRnjxjCw=
7490
golang.org/x/sys v0.0.0-20210112080510-489259a85091/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
91+
golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
92+
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1 h1:SrN+KX8Art/Sf4HNj6Zcz06G7VEz+7w9tdXTPOZ7+l4=
93+
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
94+
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
7595
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
7696
golang.org/x/text v0.3.3 h1:cokOdA+Jmi5PJGXLlLllQSgYigAEfHXJAERHVMaCc2k=
7797
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
98+
golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk=
99+
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
78100
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
79101
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
80102
golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
@@ -92,6 +114,8 @@ google.golang.org/protobuf v1.23.0 h1:4MY060fB1DLGMB/7MBTLnwQUY6+F09GEiz6SsrNqyz
92114
google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
93115
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
94116
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
117+
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
118+
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
95119
gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
96120
gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
97121
gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
@@ -100,3 +124,5 @@ gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU=
100124
gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
101125
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
102126
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
127+
gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=
128+
gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

‎mkdocs.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
site_name: REL
2-
site_description: Modern Database Access Layer for Golang - Testable, Extendable and Crafted Into a Clean and Elegant API
2+
site_description: Modern ORM for Golang - Testable, Extendable and Crafted Into a Clean and Elegant API
33
site_author: REL
44
site_url: https://go-rel.github.io/
55
repo_url: https://github.com/go-rel/rel
@@ -55,6 +55,7 @@ plugins:
5555
- search
5656
- git-revision-date
5757
- macros
58+
- meta-descriptions
5859
- minify:
5960
minify_html: true
6061
minify_js: true
@@ -63,6 +64,7 @@ plugins:
6364

6465
markdown_extensions:
6566
- admonition
67+
- meta
6668
- pymdownx.keys
6769
- pymdownx.superfences
6870
- pymdownx.highlight

0 commit comments

Comments
 (0)