feat: fix query mode & update readme (#10)

* revert: dns modes

mode names should match api server define

* docs: readme

* docs: update readme

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://<API_SERVER_HOST>:<API_SERVER_PORT>/<DB_NAME>
+openmldb://<API_SERVER_HOST>:<API_SERVER_PORT>/<DB_NAME>?mode=<MODE_NAME>
 ```
 
 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")
 ```
 
 `<DB_NAME>` is mandatory in DSN, and at this time (version 0.2.0), you must ensure the database `<DB_NAME>` created before open go connection.
+DSN parameters (the `?mode=<MODE_NAME>` part) are optional.
+
+
+### Query Mode (Optional)
+
+The execution mode for OpenMLDB, defined as `mode=<MODE_NAME>`, 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
 

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 {

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)