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)).
- Go 1.26+
- Installation via
go get -u github.com/apache/arrow-go/v18/arrow/flight/flightsql - Backend speaking FlightSQL
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)
}
// ...A Data Source Name has the following format:
flightsql://[user[:password]@]<address>[:port][?param1=value1&...¶mN=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 asflightsql://.grpc+tls://enables TLS by default, see thetlsparameter.grpc+unix:///path/to/socketconnects 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.
The following common parameters exist
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.
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.
The tls parameter allows to enable and customize Transport-Layer-Security
settings. There are some special values for the parameters:
disabledorfalsewill disable TLS for this server connection. In this case all other settings are ignored.enabledortruewill force TLS for this server connection. In this case the system settings for trusted CAs etc will be used.skip-verifywill 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).
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()
...
}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.
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.
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.