Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/databendcloud/databend-go
Golang driver for databend cloud
https://github.com/databendcloud/databend-go
Last synced: 3 months ago
JSON representation
Golang driver for databend cloud
- Host: GitHub
- URL: https://github.com/databendcloud/databend-go
- Owner: datafuselabs
- License: apache-2.0
- Created: 2022-10-20T03:28:16.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-07T02:48:25.000Z (3 months ago)
- Last Synced: 2024-08-12T18:19:45.761Z (3 months ago)
- Language: Go
- Size: 497 KB
- Stars: 19
- Watchers: 7
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# databend-go
Golang driver for [databend cloud](https://www.databend.com/)
## Installation
```
go get github.com/datafuselabs/databend-go
```
## Key features
- Supports native Databend HTTP client-server protocol
- Compatibility with [`database/sql`](#std-databasesql-interface)
# Examples
## Connecting
Connection can be achieved either via a DSN string with the
format `https://user:password@host/database?=` and sql/Open method such
as `https://username:[email protected]/test`.
```go
import (
"database/sql"
_ "github.com/datafuselabs/databend-go"
)
func ConnectDSN() error {
dsn, cfg, err := getDSN()
if err != nil {
log.Fatalf("failed to create DSN from Config: %v, err: %v", cfg, err)
}
conn, err := sql.Open("databend", dsn)
if err != nil {
return err
}
return conn.Ping()
}
```
## Connection Settings
If you are using the [databend cloud](https://app.databend.com/) you can get the connection settings using the following
way.
- host - the connect host such as `tenant--warehousename.ch.datafusecloud.com` that you can get from databend cloud as
follows:
- username/password - auth credentials that you can get from databend cloud connect page as above
- database - select the current default database
## Execution
Once a connection has been obtained, users can issue sql statements for execution via the Exec method.
```go
dsn, cfg, err := getDSN()
if err != nil {
log.Fatalf("failed to create DSN from Config: %v, err: %v", cfg, err)
}
conn, err := sql.Open("databend", dsn)
if err != nil {
fmt.Println(err)
}
conn.Exec(`DROP TABLE IF EXISTS data`)
_, err = conn.Exec(`
CREATE TABLE IF NOT EXISTS data(
Col1 TINYINT,
Col2 VARCHAR
)`)
if err != nil {
fmt.Println(err)
}
_, err = conn.Exec("INSERT INTO data VALUES (1, 'test-1')")
```
## Batch Insert
If the create table SQL is `CREATE TABLE test (
i64 Int64,
u64 UInt64,
f64 Float64,
s String,
s2 String,
a16 Array(Int16),
a8 Array(UInt8),
d Date,
t DateTime)`
you can use the next code to batch insert data:
```go
package main
import (
"database/sql"
"fmt"
_ "github.com/datafuselabs/databend-go"
)
func main() {
conn, err := sql.Open("databend", "http://databend:databend@localhost:8000/default?sslmode=disable")
tx, err := conn.Begin()
if err != nil {
fmt.Println(err)
}
batch, err := tx.Prepare(fmt.Sprintf("INSERT INTO %s VALUES", "test"))
for i := 0; i < 10; i++ {
_, err = batch.Exec(
"1234",
"2345",
"3.1415",
"test",
"test2",
"[4, 5, 6]",
"[1, 2, 3]",
"2021-01-01",
"2021-01-01 00:00:00",
)
}
err = tx.Commit()
}
```
## Querying Row/s
Querying a single row can be achieved using the QueryRow method. This returns a *sql.Row, on which Scan can be invoked
with pointers to variables into which the columns should be marshaled.
```go
package main
import (
"database/sql"
"fmt"
_ "github.com/datafuselabs/databend-go"
)
func main() {
// create table data (col1 uint8, col2 string);
// insert into data values(1,'col2');
conn, err := sql.Open("databend", "http://databend:databend@localhost:8000/default?sslmode=disable")
if err != nil {
fmt.Println(err)
}
row := conn.QueryRow("SELECT * FROM data")
var (
col1 uint8
col2 string
)
if err := row.Scan(&col1, &col2); err != nil {
fmt.Println(err)
}
fmt.Println(col2)
}
```
Iterating multiple rows requires the Query method. This returns a *sql.Rows struct on which Next can be invoked to
iterate through the rows. QueryContext equivalent allows passing of a context.
```go
package main
import (
"database/sql"
"fmt"
_ "github.com/datafuselabs/databend-go"
)
func main() {
// create table data (col1 uint8, col2 string);
// insert into data values(1,'col2');
conn, err := sql.Open("databend", "http://databend:databend@localhost:8000/default?sslmode=disable")
if err != nil {
fmt.Println(err)
}
row, err := conn.Query("SELECT * FROM data")
var (
col1 uint8
col2 string
)
for row.Next() {
if err := row.Scan(&col1, &col2); err != nil {
fmt.Println(err)
}
fmt.Println(col2)
}
}
```
## Type Mapping
The following table outlines the mapping between Databend types and Go types:
| Databend Type | Go Type |
|--------------------|-----------|
| TINYINT | int8 |
| SMALLINT | int16 |
| INT | int32 |
| BIGINT | int64 |
| TINYINT UNSIGNED | uint8 |
| SMALLINT UNSIGNED | uint16 |
| INT UNSIGNED | uint32 |
| BIGINT UNSIGNED | uint64 |
| Float32 | float32 |
| Float64 | float64 |
| Bitmap | string |
| Decimal | decimal.Decimal|
| String | string |
| Date | time.Time |
| DateTime | time.Time |
| Array(T) | string |
| Tuple(T1, T2, ...) | string |
| Variant | string |
## Compatibility
- If databend version >= v0.9.0 or later, you need to use databend-go version >= v0.3.0.
- If databend version < 1.2.371, you need to use databend-go version < 0.5.7 and if your databend version >= 1.2.371, you need the databend-go version >=0.5.7. Because from [1.2.371](https://github.com/datafuselabs/databend/releases/tag/v1.2.371), databend support transaction and databend-go has some brake changes.