Skip to content

Latest commit

 

History

History

driver

README.md

FlightSQL driver

A FlightSQL-Driver for Go's database/sql package. This driver is a lightweight wrapper around the FlightSQL client in pure Go. It provides all advantages of a database/sql driver like automatic connection pooling, transactions combined with ease of use (see (#usage)).



Prerequisites

  • Go 1.26+
  • Installation via go get -u github.com/apache/arrow-go/v18/arrow/flight/flightsql
  • Backend speaking FlightSQL

Usage

Go FlightQL Driver is an implementation of Go's database/sql/driver interface to use the database/sql framework. The driver is registered as flightsql and configured using a data-source name (DSN).

A basic example using a SQLite backend looks like this

import (
    "database/sql"
    "time"

    _ "github.com/apache/arrow-go/v18/arrow/flight/flightsql"
)

// Open the connection to an SQLite backend
db, err := sql.Open("flightsql", "flightsql://localhost:12345?timeout=5s")
if err != nil {
    panic(err)
}
// Make sure we close the connection to the database
defer db.Close()

// Use the connection e.g. for querying
rows, err := db.Query("SELECT * FROM mytable")
if err != nil {
    panic(err)
}
// ...

Data Source Name (DSN)

A Data Source Name has the following format:

flightsql://[user[:password]@]<address>[:port][?param1=value1&...&paramN=valueN]

The data-source-name (DSN) requires the address of the backend with an optional port setting. The user and password parameters are passed to the backend as GRPC Basic-Auth headers. If your backend requires a token based authentication, please use a token parameter (see common parameters below).

For consistency with other Flight SQL clients, the following schemes are accepted as well:

  • grpc+tcp:// is the same as flightsql://.
  • grpc+tls:// enables TLS by default, see the tls parameter.
  • grpc+unix:///path/to/socket connects to a Unix domain socket at the given absolute path, e.g. grpc+unix://user:password@/tmp/flightsql.sock.

Please note: All parameters are case-sensitive!

Alternatively to specifying the DSN directly you can use the DriverConfig structure to generate the DSN string. See the Driver config usage section for details.

Common parameters

The following common parameters exist

token

The token parameter can be used to specify the token for token-based authentication. The value is passed on to the backend as a GRPC Bearer-Auth header.

timeout

The timeout parameter can be set using a duration string e.g. timeout=5s to limit the maximum time an operation can take. This prevents calls that wait forever, e.g. if the backend is down or a query is taking very long. When not set, the driver will use an infinite timeout.

tls

The tls parameter allows to enable and customize Transport-Layer-Security settings. There are some special values for the parameters:

  • disabled or false will disable TLS for this server connection. In this case all other settings are ignored.
  • enabled or true will force TLS for this server connection. In this case the system settings for trusted CAs etc will be used.
  • skip-verify will enable TLS for this server connection but will not verify the server certificate. This is a security risk and should not be used!

Any other value will be interpreted as the name of a custom configuration. Those configurations must be registered either by creating the DSN from configuration or by calling RegisterTLSConfig() (see TLS setup for details).

Driver config usage

Alternatively to specifying the DSN directly you can fill the DriverConfig structure and generate the DSN out of this. Here is some example

package main

import (
    "database/sql"
    "log"
    "time"

    "github.com/apache/arrow-go/v18/arrow/flight/flightsql"
)

func main() {
    config := flightsql.DriverConfig{
        Address: "localhost:12345",
        Token:   "your token",
        Timeout: 10 * time.Second,
        Params: map[string]string{
            "my-custom-parameter": "foobar",
        },
    }
    db, err := sql.Open("flightsql", config.DSN())
    if err != nil {
        log.Fatalf("open failed: %v", err)
    }
    defer db.Close()

    ...
}

TLS setup

By specifying the tls parameter you can enable Transport-Layer-Security. Using tls=enabled the system settings are used for verifying the server's certificate. Custom TLS configurations, e.g. when using self-signed certificates, are referenced by a user-selected name. The underlying TLS configuration needs to be registered (using the same name) in two ways.

TLS setup using DriverConfig

The first way is to create a DriverConfig with the TLSConfig field set to the custom config and TLSConfigName set to the chosen name. For example

    ...

    config := flightsql.DriverConfig{
        Address: "localhost:12345",
        TLSEnabled:    true,
        TLSConfigName: "myconfig",
        TLSConfig: &tls.Config{
            MinVersion: tls.VersionTLS12,
        },
    }
    dsn := config.DSN()

    ...

will enable TLS forcing the minimum TLS version to 1.2. This custom config will be registered with the name myconfig and the resulting DSN reads

flightsql://localhost:12345?tls=myconfig`

If the TLSConfigName is omitted a random unique name (UUID) is generated and referenced in the DSN. This prevents errors from using an already registered name leading to errors.

TLS setup using manual registration

The second alternative is the manual registration of the custom TLS configuration. In this case you need to call RegisterTLSConfig() in your code

    myconfig := &tls.Config{MinVersion: tls.VersionTLS12}
    if err := flightsql.RegisterTLSConfig("myconfig", myconfig); err != nil {
        ...
    }
    dsn := "flightsql://localhost:12345?tls=myconfig"

    ...

This will register the custom configuration, constraining the minimum TLS version, as myconfig and then references the registered configuration by name in the DSN. You can reuse the same TLS configuration by registering once and then reference in multiple DSNs. Registering multiple configurations with the same name will throw an error to prevent unintended side-effects due to the driver-global registry.