Skip to content

Update client readme and example #160

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

Merged
xq262144 merged 3 commits into from
Dec 26, 2018
Merged

Update client readme and example #160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2053d1b
Update client README.md. Add create dsn and drop dsn in simple example.
laodouya Dec 26, 2018
87a1b4a
Update client README to compatible with chain bus new scheme
Dec 26, 2018
7c67456
Merge branch 'develop' into feature/clientReadme
leventeliu Dec 26, 2018
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
121 changes: 43 additions & 78 deletions client/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,28 +11,33 @@ $ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils

and import `client` package if you want to use it in your code.


## Initialize a CovenantSQL Client

You need to provide a config and a master key for initialization. The master key is used to encrypt/decrypt local key pair. Here is how to generate a default config with master key

### Generating Default Config File

Run `cql-utils` like below. Enter a master key (like a password) for generating local key pair. After that, it may take a few seconds with a private key file and config.yaml file generated in `conf` folder.

```bash
$ cql-utils -tool confgen -root bp
$ cql-utils -tool confgen -root conf
Generating key pair...
Enter master key(press Enter for default: ""):
⏎
Private key file: bp/private.key
Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd
Private key file: conf/private.key
Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75
Generated key pair.
Generating nonce...
nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9}
node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9
INFO[0005] cpu: 1
INFO[0005] position: 0, shift: 0x0, i: 0
nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514}
node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514
Generated nonce.
Generating config file...
Generated nonce.
```

## Initialize a CovenantSQL Client

You need to provide a config and a master key for initialization. The master key is used to encrypt/decrypt local key pair. If you generate a config file with `cql-utils`, you can find the config file in the directory that `cql-utils` create.

After you prepare your master key and config file, CovenantSQL client can be initialized by:

```go
Expand All @@ -46,91 +51,51 @@ client.Init(configFile, masterKey)
To create a new SQL Chain, the number of node should be provided:

```go
var dsn string
dsn, err := client.ResourceMeta{Node: uint16(nodeCnt)}
// process err
var cfg *client.Config
cfg, err = client.ParseDSN(dsn)
var (
dsn string
meta client.ResourceMeta
)
meta.Node = uint16(nodeCount)
dsn, err = client.Create(meta)
// process err
```
And you will get a dsn string. It represents a database instance, use it for queries.

Database ID can be found in `cfg`:
### Query and Exec

When you get the dsn, you can query or execute some sql on SQL Chain as follows:

```go
databaseID := cfg.DatabaseID
```

In all:
db, err := sql.Open("covenantsql", dsn)
// process err

```go
func Create(nodeCnt uint16) (dbID string, err error) {
var dsn string
if dsn, err = client.Create(client.ResourceMeta{Node: uint16(nodeCnt)}); err != nil {
return
}

var cfg *client.Config
if cfg, err = client.ParseDSN(dsn); err != nil {
return
}

dbID = cfg.DatabaseID
return
}
```
_, err = db.Exec("CREATE TABLE testSimple ( column int );")
// process err

### Query and Exec
_, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42)
// process err

When you get the database ID, you can query or execute some sql on SQL Chain as follows:
row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;")

var result int
err = row.Scan(&result)
// process err
fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result)

err = db.Close()
// process err

```go
func Query(dbID string, query string) (result , err error) {
var conn *sql.DB
if conn, err = s.getConn(dbID); err != nil {
return
}
defer conn.Close()

var rows *sql.Rows
if rows, err = conn.Query(query); err != nil {
return
}
defer rows.Close()

// read the rows of rows
}

func Exec(dbID string, query string) (err error) {
var conn *sql.DB
if conn, err = s.getConn(dbID); err != nil {
return
}
defer conn.Close()

_, err = conn.Exec(query)

return
}

func getConn(dbID string) (db *sql.DB, err error) {
cfg := client.NewConfig()
cfg.DatabaseID = dbID

return sql.Open("covenantsql", cfg.FormatDSN())
}
```
It just like other standard go sql database.

### Drop the Database

Drop your database on SQL Chain is very easy with your database ID:
Drop your database on SQL Chain is very easy with your dsn string:

```go
func Drop(dbID string) (err error) {
cfg := client.NewConfig()
cfg.DatabaseID = dbID
err = client.Drop(cfg.FormatDSN())
return
}
err = client.Drop(dsn)
// process err
```

### Full Example
Expand Down
10 changes: 9 additions & 1 deletion client/_example/simple.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,19 @@ func main() {
log.Fatal(err)
}

if dsn == "" {
dsn, err = client.Create(client.ResourceMeta{Node: uint16(2)})
if err != nil {
log.Fatal(err)
}
defer client.Drop(dsn)
}

db, err := sql.Open("covenantsql", dsn)
if err != nil {
log.Fatal(err)
}
defer db.Close()

_, err = db.Exec("DROP TABLE IF EXISTS testSimple;")
if err != nil {
Expand Down Expand Up @@ -73,5 +82,4 @@ func main() {
}
fmt.Printf("SELECT nonIndexedColumn FROM testSimple LIMIT 1; result %d\n", result)

err = db.Close()
}