Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README #950

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Update README #950

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4780f53
Update README
dveeden Nov 20, 2024
9fa7373
Update example about GTID
dveeden Nov 20, 2024
93870c2
Add description to examples
dveeden Nov 20, 2024
fd91ece
Add 'go mod edit' line
dveeden Nov 20, 2024
6e48ab4
Remove donate and feedback sessions, add credits
dveeden Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 35 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,33 @@
# go-mysql

A pure go library to handle MySQL network protocol and replication.
A pure go library to handle MySQL network protocol and replication as used by MySQL and MariaDB.

![semver](https://img.shields.io/github/v/tag/go-mysql-org/go-mysql)
![example workflow](https://github.com/go-mysql-org/go-mysql/actions/workflows/ci.yml/badge.svg)
![gomod version](https://img.shields.io/github/go-mod/go-version/go-mysql-org/go-mysql/master)

## How to migrate to this repo
To change the used package in your repo it's enough to add this `replace` directive to your `go.mod`:
```
replace github.com/siddontang/go-mysql => github.com/go-mysql-org/go-mysql v1.10.0
```

v1.10.0 - is the last tag in repo, feel free to choose what you want.
[![Go Reference](https://pkg.go.dev/badge/github.com/go-mysql-org/go-mysql.svg)](https://pkg.go.dev/github.com/go-mysql-org/go-mysql)

## Changelog
This repo uses [Changelog](CHANGELOG.md).

---
# Content
* [Replication](#replication)
* [Incremental dumping](#canal)
* [Client](#client)
* [Fake server](#server)
* [database/sql like driver](#driver)
* [Replication](#replication) - Process events from a binlog stream.
* [Incremental dumping](#canal) - Sync from MySQL to Redis, Elasticsearch, etc.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO the difference between this "Incremental dumping" and "Replication" item are developers need to implement interfaces (like EventHandler) or handle decoded binlog events. Maybe use "library mode" or "framework mode". I choose these two words to tell the difference like

When you use a library, you are in charge of the flow of the application. You are choosing when and where to call the library. When you use a framework, the framework is in charge of the flow. It provides some places for you to plug in your code, but it calls the code you plugged in as needed.

https://www.freecodecamp.org/news/the-difference-between-a-framework-and-a-library-bd133054023f/ (a random blog ranks top in google search "library vs framework")

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what you want me to change. Do you you want to clarify the difference between "Replication" and "Incremental dumping"?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, like

* [Use as a library](#replication) - Process events from a binlog stream and have maximum functionalities.
* [Use as a framework](#canal) - Implement `EventHandler` interface to subscribe binlog changes

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However I don't have confidence how to describe these two items. Will think about it later

* [Client](#client) - Simple MySQL client.
* [Fake server](#server) - server side of the MySQL protocol, as library.
* [database/sql like driver](#driver) - An alternative `database/sql` driver for MySQL.
* [Migration](#how-to-migrate-to-this-repo) - Information for how to migrate if you used the old location of this project.

## Examples

The `cmd` directory contains example applications that can be build by running `make build` in the root of the project. The resulting binaries will be places in `bin/`.

- `go-binlogparser`: parses a binlog file at a given offset
- `go-canal`: streams binlog events from a server to canal
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact I don't know what's canal 😂 maybe it's https://github.com/alibaba/canal?tab=readme-ov-file ? I'm not sure this library will output similar output or have similar usage as that one.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it might be similar, but I'm not sure it is the same or if it is compatible.

- `go-mysqlbinlog`: streams binlog events
- `go-mysqldump`: like `mysqldump`, but in Go
- `go-mysqlserver`: fake MySQL server

## Replication

Expand Down Expand Up @@ -54,9 +58,10 @@ syncer := replication.NewBinlogSyncer(cfg)
streamer, _ := syncer.StartSync(mysql.Position{binlogFile, binlogPos})

// or you can start a gtid replication like
// gtidSet, _ := mysql.ParseGTIDSet(mysql.MySQLFlavor, "de278ad0-2106-11e4-9f8e-6edd0ca20947:1-2")
// streamer, _ := syncer.StartSyncGTID(gtidSet)
// the mysql GTID set likes this "de278ad0-2106-11e4-9f8e-6edd0ca20947:1-2"
// the mariadb GTID set likes this "0-1-100"
// the mysql GTID set is like this "de278ad0-2106-11e4-9f8e-6edd0ca20947:1-2" and uses mysql.MySQLFlavor
// the mariadb GTID set is like this "0-1-100" and uses mysql.MariaDBFlavor

for {
ev, _ := streamer.GetEvent(context.Background())
Expand Down Expand Up @@ -110,7 +115,7 @@ Query: DROP TABLE IF EXISTS `test_replication` /* generated by server */

## Canal

Canal is a package that can sync your MySQL into everywhere, like Redis, Elasticsearch.
Canal is a package that can sync your MySQL into everywhere, like Redis, Elasticsearch.

First, canal will dump your MySQL data then sync changed data using binlog incrementally.

Expand Down Expand Up @@ -160,7 +165,7 @@ func main() {
}
```

You can see [go-mysql-elasticsearch](https://github.com/siddontang/go-mysql-elasticsearch) for how to sync MySQL data into Elasticsearch.
You can see [go-mysql-elasticsearch](https://github.com/go-mysql-org/go-mysql-elasticsearch) for how to sync MySQL data into Elasticsearch.

## Client

Expand Down Expand Up @@ -492,17 +497,19 @@ func main() {

We pass all tests in https://github.com/bradfitz/go-sql-test using go-mysql driver. :-)

## Donate

If you like the project and want to buy me a cola, you can through:

|PayPal|微信|
|------|---|
|[![](https://www.paypalobjects.com/webstatic/paypalme/images/pp_logo_small.png)](https://paypal.me/siddontang)|[![](https://github.com/siddontang/blog/blob/master/donate/weixin.png)|
## How to migrate to this repo
To change the used package in your repo it's enough to add this `replace` directive to your `go.mod`:
```
replace github.com/siddontang/go-mysql => github.com/go-mysql-org/go-mysql v1.10.0
```

## Feedback
This can be done by running this command:
```
go mod edit -replace=github.com/siddontang/go-mysql=github.com/go-mysql-org/[email protected]
```

go-mysql is still in development, your feedback is very welcome.
v1.10.0 - is the last tag in repo, feel free to choose what you want.

## Credits

Gmail: siddontang@gmail.com
go-mysql was started by @siddontang and has many [contributors](https://github.com/go-mysql-org/go-mysql/graphs/contributors)
Loading