Skip to main content

Golang

Databend offers a driver (databend-go) written in Golang, which facilitates the development of applications using the Golang programming language and establishes connectivity with Databend.

For installation instructions, examples, and the source code, see the GitHub databend-go repo.

Data Type Mappings

This table illustrates the correspondence between Databend data types and their corresponding Go equivalents:

DatabendGo
TINYINTint8
SMALLINTint16
INTint32
BIGINTint64
TINYINT UNSIGNEDuint8
SMALLINT UNSIGNEDuint16
INT UNSIGNEDuint32
BIGINT UNSIGNEDuint64
Float32float32
Float64float64
Bitmapstring
Decimaldecimal.Decimal
Stringstring
Datetime.Time
DateTimetime.Time
Array(T)string
Tuple(T1, T2, ...)string
Variantstring

Databend Go Driver Behavior Summary

The Databend Go Driver is compatible with the "database/sql" interface specification. Below are some common basic behaviors, along with the key functions involved and the principles behind them.

Basic BehaviorKey Functions InvolvedPrinciple
Creating a connectionDB.OpenEstablish a connection to Databend using the DSN string and the DB.Open method.

The DSN string format is https://user:password@host/database?<query_option>=<value>.
Executing statementsDB.ExecThe DB.Exec method executes SQL statements using the v1/query interface for creating, deleting tables and inserting data.
Bulk insertionDB.Begin, Tx.Prepare, Stmt.Exec, Tx.CommitBulk insert/replace data (INSERT INTO and REPLACE INTO) are processed through transactions.

Use Stmt.Exec to add as much data as possible to a prepared statement object; data will be appended to a file.

Executing Tx.Commit() will finally upload the data to the built-in Stage and perform the insert/replace operation, using Stage Attachment.
Querying single rowDB.QueryRow, Row.ScanUse the DB.QueryRow method to query a single row of data and return a *sql.Row, then call Row.Scan to map the column data to variables.
Iterating over rowsDB.Query, Rows.Next, Rows.ScanUse the DB.Query method to query multiple rows of data and return a *sql.Rows structure, iterate over rows using the Rows.Next method, and map the data to variables using Rows.Scan.
Uploading to internal StageAPIClient.UploadToStageUpload data to Stage. By default, use PRESIGN UPLOAD to get a URL, or if PRESIGN is disabled, use the v1/upload_to_stage API.

Tutorial-1: Integrating with Databend using Golang

Before you start, make sure you have successfully installed a local Databend. For detailed instructions, see Local and Docker Deployments.

Step 1. Prepare a SQL User Account

To connect your program to Databend and execute SQL operations, you must provide a SQL user account with appropriate privileges in your code. Create one in Databend if needed, and ensure that the SQL user has only the necessary privileges for security.

This tutorial uses a SQL user named 'user1' with password 'abc123' as an example. As the program will write data into Databend, the user needs ALL privileges. For how to manage SQL users and their privileges, see User & Role.

CREATE USER user1 IDENTIFIED BY 'abc123';
GRANT ALL on *.* TO user1;

Step 2. Write a Golang Program

In this step, you'll create a simple Golang program that communicates with Databend. The program will involve tasks such as creating a table, inserting data, and executing data queries.

1

Copy and paste the following code to the file main.go
Copy Link

note
  • The code below connects to a local Databend with a SQL user named 'user1' and password 'abc123' as an example. Feel free to use your own values while maintaining the same format.
  • The value of hostname in the code below must align with your HTTP handler settings for Databend query service.
main.go
package main

import (
"database/sql"
"fmt"
"log"

_ "github.com/databendcloud/databend-go"
)

const (
username = "user1"
password = "abc123"
hostname = "127.0.0.1:8000"
)

type Book struct {
Title string
Author string
Date string
}

func dsn() string {
return fmt.Sprintf("http://%s:%s@%s", username, password, hostname)
}

func main() {
db, err := sql.Open("databend", dsn())

if err != nil {
log.Fatal(err)
}
defer db.Close()

err = db.Ping()
if err != nil {
log.Fatal(err)
}
log.Println("Connected")

// Create db if do not exist
dbSql := "CREATE DATABASE IF NOT EXISTS book_db"
_, err = db.Exec(dbSql)
if err != nil {
log.Fatal(err)
}
log.Println("Create database book_db success")

// Use book_db database
_, err = db.Exec("USE book_db")
if err != nil {
log.Fatal(err)
}

// Create table.
sql := "create table if not exists books(title VARCHAR, author VARCHAR, date VARCHAR)"
_, err = db.Exec(sql)
if err != nil {
log.Fatal(err)
}
log.Println("Create table: books")

// Insert 1 row.
_, err = db.Exec("INSERT INTO books VALUES(?, ?, ?)", "mybook", "author", "2022")
if err != nil {
log.Fatal(err)
}
log.Println("Insert 1 row")

// Select.
res, err := db.Query("SELECT * FROM books")
if err != nil {
log.Fatal(err)
}

for res.Next() {
var book Book
err := res.Scan(&book.Title, &book.Author, &book.Date)
if err != nil {
log.Fatal(err)
}

log.Printf("Select:%v", book)
}
db.Exec("drop table books")
db.Exec("drop database book_db")
}
2

Install dependencies.
Copy Link

go mod init databend-golang
go.mod
module databend-golang

go 1.20

require github.com/databendcloud/databend-go v0.3.10

require (
github.com/BurntSushi/toml v1.2.1 // indirect
github.com/avast/retry-go v3.0.0+incompatible // indirect
github.com/google/uuid v1.3.0 // indirect
github.com/pkg/errors v0.9.1 // indirect
github.com/sirupsen/logrus v1.9.0 // indirect
golang.org/x/sys v0.5.0 // indirect
)
3

Run the program.
Copy Link

go run main.go
Outputs
2023/02/24 23:57:31 Connected
2023/02/24 23:57:31 Create database book_db success
2023/02/24 23:57:31 Create table: books
2023/02/24 23:57:31 Insert 1 row
2023/02/24 23:57:31 Select:{mybook author 2022}

Tutorial-2: Integrating with Databend Cloud using Golang

Before you start, make sure you have successfully created a warehouse and obtained the connection information. For how to do that, see Connecting to a Warehouse.

Step 1. Create a Go Module

$ mkdir sample
$ cd sample
$ go mod init cloud.databend.com/sample

Step 2. Install Dependencies

$ go get github.com/databendcloud/databend-go

Step 3. Connect with databend-go

Create a file named main.go with the following code:

package main

import (
"database/sql"
"fmt"

_ "github.com/databendcloud/databend-go"
)

func main() {
dsn := "databend://{USER}:{PASSWORD}@${HOST}:443/{DATABASE}?&warehouse={WAREHOUSE_NAME}";
conn, err := sql.Open("databend", dsn)
if err != nil {
fmt.Println(err)
}
conn.Exec(`DROP TABLE IF EXISTS data`)
createTable := `CREATE TABLE IF NOT EXISTS data (
i64 Int64,
u64 UInt64,
f64 Float64,
s String,
s2 String,
a16 Array(Int16),
a8 Array(UInt8),
d Date,
t DateTime)`
_, err = conn.Exec(createTable)
if err != nil {
fmt.Println(err)
}
scope, err := conn.Begin()
batch, err := scope.Prepare(fmt.Sprintf("INSERT INTO %s VALUES", "data"))
if err != nil {
fmt.Println(err)
}
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 = scope.Commit()
if err != nil {
fmt.Println(err)
}
}
tip

Replace {USER}, {PASSWORD}, {HOST}, {WAREHOUSE_NAME} and {DATABASE} in the code with your connection information. For how to obtain the connection information, see Connecting to a Warehouse.

Step 4. Run main.go

$ go run main.go
Did this page help you?
Yes
No