Home

Awesome

Exasol Go SQL Driver

Build Status Go Reference

Quality Gate Status

Maintainability Rating Bugs Code Smells Coverage

This repository contains a Go library for connection to the Exasol database.

This library uses the standard Golang SQL driver interface for easy use.

Prerequisites

To use the Exasol Go Driver you need an Exasol database in the latest 7.1 or 8 version. Older versions might work but are not supported.

Usage

Create Connection

With Exasol Config

We recommend using the provided builder to build a connection string. The builder ensures all values are escaped properly.

package main

import (
    "database/sql"
    "github.com/exasol/exasol-driver-go"
)

func main() {
    database, err := sql.Open("exasol", exasol.NewConfig("<username>", "<password>").
                                              Host("<host>").
                                              Port(8563).
                                              String())
    // ...
}

If you want to login via OpenID tokens use exasol.NewConfigWithRefreshToken("token") or exasol.NewConfigWithAccessToken("token"). See the documentation about how to configure OpenID authentication in Exasol. OpenID authentication is only supported with Exasol 7.1.x and later.

With Exasol DSN

You can also create a connection replacing the builder with a simple string:

package main

import (
    "database/sql"
    _ "github.com/exasol/exasol-driver-go"
)

func main() {
    database, err := sql.Open("exasol",
            "exa:<host>:<port>;user=<username>;password=<password>")
    // ...
}

If a value in the connection string contains a ; you need to escape it with \;. This ensures that the driver can parse the connection string as expected.

Execute Statement

result, err := exasol.Exec(`
    INSERT INTO CUSTOMERS
    (NAME, CITY)
    VALUES('Bob', 'Berlin');`)

Query Statement

rows, err := exasol.Query("SELECT * FROM CUSTOMERS")

Use Prepared Statements

preparedStatement, err := exasol.Prepare(`
    INSERT INTO CUSTOMERS
    (NAME, CITY)
    VALUES(?, ?)`)
result, err = preparedStatement.Exec("Bob", "Berlin")
preparedStatement, err := exasol.Prepare("SELECT * FROM CUSTOMERS WHERE NAME = ?")
rows, err := preparedStatement.Query("Bob")

Transaction Commit and Rollback

To control the transaction state manually, you need to disable autocommit (enabled by default):

database, err := sql.Open("exasol",
                "exa:<host>:<port>;user=<username>;password=<password>;autocommit=0")
// or
database, err := sql.Open("exasol", exasol.NewConfig("<username>", "<password>")
                                          .Port(<port>)
                                          .Host("<host>")
                                          .Autocommit(false)
                                          .String())

After that you can begin a transaction:

transaction, err := exasol.Begin()
result, err := transaction.Exec( ... )
result2, err := transaction.Exec( ... )

To commit a transaction use Commit():

err = transaction.Commit()

To rollback a transaction use Rollback():

err = transaction.Rollback()

Import Local CSV Files

Use the sql driver to load data from one or more CSV files into your Exasol Database. These files must be local to the machine where you execute the IMPORT statement.

Limitations:

result, err := exasol.Exec(`
IMPORT INTO CUSTOMERS FROM LOCAL CSV FILE './testData/data.csv' FILE './testData/data_part2.csv'
  COLUMN SEPARATOR = ';' 
  ENCODING = 'UTF-8' 
  ROW SEPARATOR = 'LF'
`)

See also the usage notes about the file_src element for local files of the IMPORT statement.

Connection String

The golang Driver uses the following URL structure for Exasol:

exa:<host>[,<host_1>]...[,<host_n>]:<port>[;<prop_1>=<value_1>]...[;<prop_n>=<value_n>]

Host-Range-Syntax is supported (e.g. exasol1..3). A range like exasol1..exasol3 is not valid.

Supported Driver Properties

PropertyValueDefaultDescription
autocommit0=off, 1=on1Switch autocommit on or off.
clientnamestringGo clientTell the server the application name.
clientversionstringTell the server the version of the application.
compression0=off, 1=on0Switch data compression on or off.
encryption0=off, 1=on1Switch automatic encryption on or off.
validateservercertificate0=off, 1=on1TLS certificate verification. Disable it if you want to use a self-signed or invalid certificate (server side).
certificatefingerprintstringExpected fingerprint of the server's TLS certificate. See below for details.
fetchsizenumeric, >0128*1024Amount of data in kB which should be obtained by Exasol during a fetch. The application can run out of memory if the value is too high.
passwordstringExasol password.
resultsetmaxrowsnumericSet the max amount of rows in the result set.
schemastringExasol schema name.
userstringExasol username.

Configuring TLS

We recommend to always enable TLS encryption. This is on by default, but you can enable it explicitly via driver property encryption=1 or config.Encryption(true). Please note that starting with version 8, Exasol does not support unencrypted connections anymore, so you can't use encryption=0 or config.Encryption(false).

There are two driver properties that control how TLS certificates are verified: validateservercertificate and certificatefingerprint. You have these three options depending on your setup:

Configure Logging

Error Logger

By default the driver will log warnings and error messages to stderr. You can configure a custom error logger with

logger.SetLogger(log.New(os.Stderr, "[exasol] ", log.LstdFlags|log.Lshortfile))

Trace Logger

By default the driver does not log any trace or debug messages. To investigate problems you can configure a custom trace logger with

logger.SetTraceLogger(log.New(os.Stderr, "[exasol-trace] ", log.LstdFlags|log.Lshortfile))

You can deactivate trace logging with

logger.SetTraceLogger(nil)

Information for Users

Information for Developers