diff --git a/README.md b/README.md index b116e11..1df2cd8 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,12 @@ Pure Go [OpenMLDB](https://github.com/4paradigm/OpenMLDB) driver for database/sq ## Features +- Lightweight +- Pure Go implementation, No C-bindings +- Connection over HTTP +- Full OpenMLDB SQL support, work with online and offline mode +- Numeric, bool, string, date, timestamp data type support + ## Requirements - OpenMLDB with all components version >= 0.6.2 @@ -19,7 +25,7 @@ go get github.com/4paradigm/openmldb-go-sdk ## Data Source Name (DSN) ``` -openmldb://:/ +openmldb://:/?mode= ``` For example, to open a database to `test_db` by api server at `127.0.0.1:8080`: @@ -28,6 +34,60 @@ db, err := sql.Open("openmldb", "openmldb://127.0.0.1:8080/test_db") ``` `` is mandatory in DSN, and at this time (version 0.2.0), you must ensure the database `` created before open go connection. +DSN parameters (the `?mode=` part) are optional. + + +### Query Mode (Optional) + +The execution mode for OpenMLDB, defined as `mode=`, default to `online`, available values are: +- `online`: online preview mode +- `offsync`: offline mode with system variable `sync_job = true` +- `offasync`: offline mode with system variable `sync_job = false` + + +## Data type support + +int16, int32, int64, float, double, bool, date, timestamp and string types in OpenMLDB SQL are supported. +Since Go types are flexible by design, you may choose any type in Go by your favor, as long as that type implements +[sql#Scanner](https://pkg.go.dev/database/sql#Scanner) interface. + +For example, a SQL string type, can be represented in Go with `string`, `sql.NullString`, `sql.Null[string]`, `string` is able +to represent SQL string when it is not NULL, error reported if you want to save a NULL value into string, while the later two types +are able to save all SQL string, regardless nullable: + +```go +import ( + "database/sql" +) + +// ... + +{ + var s string + err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s) + // err returned from Scan if NULL value returned from query +} + + +{ + var s sql.NullString + err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s) + // NullString is safe for query returns NULL + // ... + + if s.Valid { + // use s.String + } else { + // NULL value + } +} +``` + +### Timestamp and date support + +We use `time.Time` internally represents SQL timestamp and date type, so you can choose whatever type that is +scannable from `time.Time`, like `sql.NullTime`, or simply `time.Time` itself. + ## Getting Start diff --git a/conn.go b/conn.go index 7beccb0..8b36499 100644 --- a/conn.go +++ b/conn.go @@ -38,24 +38,26 @@ type queryMode string func (m queryMode) String() string { switch m { - case ModeOffline: - return "offline" - case ModeOnline: - return "online" + case ModeOffsync: + return "offsync" + case ModeOffasync: + return "offasync" default: return "unknown" } } const ( - ModeOffline queryMode = "offline" - ModeOnline queryMode = "online" + ModeOffsync queryMode = "offsync" + ModeOffasync queryMode = "offasync" + ModeOnline queryMode = "online" // TODO(someone): "request" ) var allQueryMode = map[string]queryMode{ - "offline": ModeOffline, - "online": ModeOnline, + "offsync": ModeOffsync, + "offasync": ModeOffasync, + "online": ModeOnline, } type conn struct { diff --git a/driver_test.go b/driver_test.go index 56c426b..89e34cc 100644 --- a/driver_test.go +++ b/driver_test.go @@ -17,7 +17,8 @@ func Test_parseDsn(t *testing.T) { }{ {"openmldb://127.0.0.1:8080/test_db", "127.0.0.1:8080", "test_db", ModeOnline, nil}, {"openmldb://127.0.0.1:8080/test_db?mode=online", "127.0.0.1:8080", "test_db", ModeOnline, nil}, - {"openmldb://127.0.0.1:8080/test_db?mode=offline", "127.0.0.1:8080", "test_db", ModeOffline, nil}, + {"openmldb://127.0.0.1:8080/test_db?mode=offasync", "127.0.0.1:8080", "test_db", ModeOffasync, nil}, + {"openmldb://127.0.0.1:8080/test_db?mode=offsync", "127.0.0.1:8080", "test_db", ModeOffsync, nil}, {"openmldb://127.0.0.1:8080/test_db?mode=unknown", "127.0.0.1:8080", "test_db", "", errors.New("")}, } { host, db, mode, err := parseDsn(tc.dsn)