trino

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 7, 2021 License: Apache-2.0 Imports: 23 Imported by: 0

README

Trino client

A Trino client for the Go programming language.

Features

  • Native Go implementation
  • Connections over HTTP or HTTPS
  • HTTP Basic and Kerberos authentication
  • Per-query user information for access control
  • Support custom HTTP client (tunable conn pools, timeouts, TLS)
  • Supports conversion from Trino to native Go data types
    • string, sql.NullString
    • int64, trino.NullInt64
    • float64, trino.NullFloat64
    • map, trino.NullMap
    • time.Time, trino.NullTime
    • Up to 3-dimensional arrays to Go slices, of any supported type

Requirements

  • Go 1.12 or newer
  • Trino 0.16x or newer

Installation

You need a working environment with Go installed and $GOPATH set.

Download and install Trino database/sql driver:

go get github.com/CryBecase/trino

Make sure you have Git installed and in your $PATH.

Usage

This Trino client is an implementation of Go's database/sql/driver interface. In order to use it, you need to import the package and use the database/sql API then.

Only read operations are supported, such as SHOW and SELECT.

Use trino as driverName and a valid DSN as the dataSourceName.

Example:

import "database/sql"
import _ "github.com/CryBecase/trino"

dsn := "http://user@localhost:8080?catalog=default&schema=test"
db, err := sql.Open("trino", dsn)
Authentication

Both HTTP Basic and Kerberos authentication are supported.

HTTP Basic authentication

If the DSN contains a password, the client enables HTTP Basic authentication by setting the Authorization header in every request to Trino.

HTTP Basic authentication is only supported on encrypted connections over HTTPS.

Kerberos authentication

This driver supports Kerberos authentication by setting up the Kerberos fields in the Config struct.

Please refer to the Coordinator Kerberos Authentication for server-side configuration.

System access control and per-query user information

It's possible to pass user information to Trino, different from the principal used to authenticate to the coordinator. See the System Access Control documentation for details.

In order to pass user information in queries to Trino, you have to add a NamedArg to the query parameters where the key is X-Presto-User. This parameter is used by the driver to inform Trino about the user executing the query regardless of the authentication method for the actual connection, and its value is NOT passed to the query.

Example:

db.Query("SELECT * FROM foobar WHERE id=?", 1, sql.Named("X-Presto-User", string("Alice")))

The position of the X-Presto-User NamedArg is irrelevant and does not affect the query in any way.

DSN (Data Source Name)

The Data Source Name is a URL with a mandatory username, and optional query string parameters that are supported by this driver, in the following format:

http[s]://user[:pass]@host[:port][?parameters]

The easiest way to build your DSN is by using the Config.FormatDSN helper function.

The driver supports both HTTP and HTTPS. If you use HTTPS it's recommended that you also provide a custom http.Client that can validate (or skip) the security checks of the server certificate, and/or to configure TLS client authentication.

Parameters

Parameters are case-sensitive

Refer to the Trino Concepts documentation for more information.

source
Type:           string
Valid values:   string describing the source of the connection to Trino
Default:        empty

The source parameter is optional, but if used, can help Trino admins troubleshoot queries and trace them back to the original client.

catalog
Type:           string
Valid values:   the name of a catalog configured in the Trino server
Default:        empty

The catalog parameter defines the Trino catalog where schemas exist to organize tables.

schema
Type:           string
Valid values:   the name of an existing schema in the catalog
Default:        empty

The schema parameter defines the Trino schema where tables exist. This is also known as namespace in some environments.

session_properties
Type:           string
Valid values:   comma-separated list of key=value session properties
Default:        empty

The session_properties parameter must contain valid parameters accepted by the Trino server. Run SHOW SESSION in Trino to get the current list.

custom_client
Type:           string
Valid values:   the name of a client previously registered to the driver
Default:        empty (defaults to http.DefaultClient)

The custom_client parameter allows the use of custom http.Client for the communication with Trino.

Register your custom client in the driver, then refer to it by name in the DSN, on the call to sql.Open:

foobarClient := &http.Client{
    Transport: &http.Transport{
        Proxy: http.ProxyFromEnvironment,
        DialContext: (&net.Dialer{
            Timeout:   30 * time.Second,
            KeepAlive: 30 * time.Second,
            DualStack: true,
        }).DialContext,
        MaxIdleConns:          100,
        IdleConnTimeout:       90 * time.Second,
        TLSHandshakeTimeout:   10 * time.Second,
        ExpectContinueTimeout: 1 * time.Second,
        TLSClientConfig:       &tls.Config{
        // your config here...
        },
    },
}
trino.RegisterCustomClient("foobar", foobarClient)
db, err := sql.Open("trino", "https://user@localhost:8080?custom_client=foobar")
Examples
http://user@localhost:8080?source=hello&catalog=default&schema=foobar

https://user@localhost:8443?session_properties=query_max_run_time=10m,query_priority=2

License

As described in the LICENSE file.

Documentation

Overview

Package trino provides a database/sql driver for Trino.

The driver should be used via the database/sql package: 

import "database/sql"
import _ "github.com/CryBecase/trino"

dsn := "http://user@localhost:8080?catalog=default&schema=test"
db, err := sql.Open("trino", dsn)

Index

Constants

View Source 
const (
	XTrinoUserHeader = "X-Trino-User"

	XPrestoUserHeader = "X-Presto-User"

	CallbackHeader = "Callback"

	KerberosEnabledConfig = "KerberosEnabled"

	SSLCertPathConfig = "SSLCertPath"
)

Variables

View Source 
var (
	// DefaultQueryTimeout is the default timeout for queries executed without a context.
	DefaultQueryTimeout = 60 * time.Second

	// DefaultCancelQueryTimeout is the timeout for the request to cancel queries in Trino.
	DefaultCancelQueryTimeout = 30 * time.Second

	// ErrOperationNotSupported indicates that a database operation is not supported.
	ErrOperationNotSupported = errors.New("trino: operation not supported")

	// ErrQueryCancelled indicates that a query has been cancelled.
	ErrQueryCancelled = errors.New("trino: query cancelled")
)

Functions

func DeregisterCustomClient 

func DeregisterCustomClient(key string)

DeregisterCustomClient removes the client associated to the key.

func RegisterCustomClient 

func RegisterCustomClient(key string, client *http.Client) error

RegisterCustomClient associates a client to a key in the driver's registry.

Register your custom client in the driver, then refer to it by name in the DSN, on the call to sql.Open: 

foobarClient := &http.Client{
	Transport: &http.Transport{
		Proxy: http.ProxyFromEnvironment,
		DialContext: (&net.Dialer{
			Timeout:   30 * time.Second,
			KeepAlive: 30 * time.Second,
			DualStack: true,
		}).DialContext,
		MaxIdleConns:          100,
		IdleConnTimeout:       90 * time.Second,
		TLSHandshakeTimeout:   10 * time.Second,
		ExpectContinueTimeout: 1 * time.Second,
		TLSClientConfig:       &tls.Config{
		// your config here...
		},
	},
}
trino.RegisterCustomClient("foobar", foobarClient)
db, err := sql.Open("trino", "https://user@localhost:8080?custom_client=foobar")

func Serial 

func Serial(v interface{}) (string, error)

Serial converts any supported value to its equivalent string for as a Trino parameter See https://trino.io/docs/current/language/types.html

func VersionPresto added in v0.1.1 

func VersionPresto()

func VersionTrino added in v0.1.1 

func VersionTrino()

Types

type CancelQuery 

type CancelQuery func() error

type Config 

type Config struct {
	ServerURI          string            // URI of the Trino server, e.g. http://user@localhost:8080
	Source             string            // Source of the connection (optional)
	Catalog            string            // Catalog (optional)
	Schema             string            // Schema (optional)
	SessionProperties  map[string]string // Session properties (optional)
	CustomClientName   string            // Custom client name (optional)
	KerberosEnabled    string            // KerberosEnabled (optional, default is false)
	KerberosKeytabPath string            // Kerberos Keytab Path (optional)
	KerberosPrincipal  string            // Kerberos Principal used to authenticate to KDC (optional)
	KerberosRealm      string            // The Kerberos Realm (optional)
	KerberosConfigPath string            // The krb5 config path (optional)
	SSLCertPath        string            // The SSL cert path for TLS verification (optional)
}

Config is a configuration that can be encoded to a DSN string.

func (*Config) FormatDSN 

func (c *Config) FormatDSN() (string, error)

FormatDSN returns a DSN string from the configuration.

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a Trino connection. implements driver.Conn & driver.ConnPrepareContext

func (*Conn) Begin 

func (c *Conn) Begin() (driver.Tx, error)

Begin implements the driver.Conn interface.

func (*Conn) Close 

func (c *Conn) Close() error

Close implements the driver.Conn interface.

func (*Conn) Prepare 

func (c *Conn) Prepare(query string) (driver.Stmt, error)

Prepare implements the driver.Conn interface.

func (*Conn) PrepareContext 

func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

PrepareContext implements the driver.ConnPrepareContext interface.

func (*Conn) ResetSession 

func (c *Conn) ResetSession(ctx context.Context) error

ResetSession implements driver.SessionResetter

type ErrQueryFailed 

type ErrQueryFailed struct {
	StatusCode int
	Reason     error
}

ErrQueryFailed indicates that a query to Trino failed.

func (*ErrQueryFailed) Error 

func (e *ErrQueryFailed) Error() string

Error implements the error interface.

type NullMap 

type NullMap struct {
	Map   map[string]interface{}
	Valid bool
}

NullMap represents a map type that may be null.

func (*NullMap) Scan 

func (m *NullMap) Scan(v interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice2Bool 

type NullSlice2Bool struct {
	Slice2Bool [][]sql.NullBool
	Valid      bool
}

NullSlice2Bool represents a two-dimensional slice of bool that may be null.

func (*NullSlice2Bool) Scan 

func (s *NullSlice2Bool) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice2Float64 

type NullSlice2Float64 struct {
	Slice2Float64 [][]sql.NullFloat64
	Valid         bool
}

NullSlice2Float64 represents a two-dimensional slice of float64 that may be null.

func (*NullSlice2Float64) Scan 

func (s *NullSlice2Float64) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice2Int64 

type NullSlice2Int64 struct {
	Slice2Int64 [][]sql.NullInt64
	Valid       bool
}

NullSlice2Int64 represents a two-dimensional slice of int64 that may be null.

func (*NullSlice2Int64) Scan 

func (s *NullSlice2Int64) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice2Map 

type NullSlice2Map struct {
	Slice2Map [][]NullMap
	Valid     bool
}

NullSlice2Map represents a two-dimensional slice of NullMap that may be null.

func (*NullSlice2Map) Scan 

func (s *NullSlice2Map) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice2String 

type NullSlice2String struct {
	Slice2String [][]sql.NullString
	Valid        bool
}

NullSlice2String represents a two-dimensional slice of string that may be null.

func (*NullSlice2String) Scan 

func (s *NullSlice2String) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice2Time 

type NullSlice2Time struct {
	Slice2Time [][]NullTime
	Valid      bool
}

NullSlice2Time represents a two-dimensional slice of time.Time that may be null.

func (*NullSlice2Time) Scan 

func (s *NullSlice2Time) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice3Bool 

type NullSlice3Bool struct {
	Slice3Bool [][][]sql.NullBool
	Valid      bool
}

NullSlice3Bool implements a three-dimensional slice of bool that may be null.

func (*NullSlice3Bool) Scan 

func (s *NullSlice3Bool) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice3Float64 

type NullSlice3Float64 struct {
	Slice3Float64 [][][]sql.NullFloat64
	Valid         bool
}

NullSlice3Float64 represents a three-dimensional slice of float64 that may be null.

func (*NullSlice3Float64) Scan 

func (s *NullSlice3Float64) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice3Int64 

type NullSlice3Int64 struct {
	Slice3Int64 [][][]sql.NullInt64
	Valid       bool
}

NullSlice3Int64 implements a three-dimensional slice of int64 that may be null.

func (*NullSlice3Int64) Scan 

func (s *NullSlice3Int64) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice3Map 

type NullSlice3Map struct {
	Slice3Map [][][]NullMap
	Valid     bool
}

NullSlice3Map represents a three-dimensional slice of NullMap that may be null.

func (*NullSlice3Map) Scan 

func (s *NullSlice3Map) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice3String 

type NullSlice3String struct {
	Slice3String [][][]sql.NullString
	Valid        bool
}

NullSlice3String implements a three-dimensional slice of string that may be null.

func (*NullSlice3String) Scan 

func (s *NullSlice3String) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSlice3Time 

type NullSlice3Time struct {
	Slice3Time [][][]NullTime
	Valid      bool
}

NullSlice3Time represents a three-dimensional slice of time.Time that may be null.

func (*NullSlice3Time) Scan 

func (s *NullSlice3Time) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSliceBool 

type NullSliceBool struct {
	SliceBool []sql.NullBool
	Valid     bool
}

NullSliceBool represents a slice of bool that may be null.

func (*NullSliceBool) Scan 

func (s *NullSliceBool) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSliceFloat64 

type NullSliceFloat64 struct {
	SliceFloat64 []sql.NullFloat64
	Valid        bool
}

NullSliceFloat64 represents a slice of float64 that may be null.

func (*NullSliceFloat64) Scan 

func (s *NullSliceFloat64) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSliceInt64 

type NullSliceInt64 struct {
	SliceInt64 []sql.NullInt64
	Valid      bool
}

NullSliceInt64 represents a slice of int64 that may be null.

func (*NullSliceInt64) Scan 

func (s *NullSliceInt64) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSliceMap 

type NullSliceMap struct {
	SliceMap []NullMap
	Valid    bool
}

NullSliceMap represents a slice of NullMap that may be null.

func (*NullSliceMap) Scan 

func (s *NullSliceMap) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSliceString 

type NullSliceString struct {
	SliceString []sql.NullString
	Valid       bool
}

NullSliceString represents a slice of string that may be null.

func (*NullSliceString) Scan 

func (s *NullSliceString) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullSliceTime 

type NullSliceTime struct {
	SliceTime []NullTime
	Valid     bool
}

NullSliceTime represents a slice of time.Time that may be null.

func (*NullSliceTime) Scan 

func (s *NullSliceTime) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type NullTime 

type NullTime struct {
	Time  time.Time
	Valid bool
}

NullTime represents a time.Time value that can be null. The NullTime supports presto's Date, Time and Timestamp data types, with or without time zone.

func (*NullTime) Scan 

func (s *NullTime) Scan(value interface{}) error

Scan implements the sql.Scanner interface.

type Numeric 

type Numeric string

Numeric is a string representation of a number, such as "10", "5.5" or in scientific form If another string format is used it will error to serialise

type QueryCallBack 

type QueryCallBack interface {
	OnUpdated(QueryInfo)
}

type QueryInfo 

type QueryInfo struct {
	Id         string      `json:"id"`
	QueryStats stmtStats   `json:"query_stats"`
	Cancel     CancelQuery `json:"cancel"`
}

type UnsupportedArgError 

type UnsupportedArgError struct {
	// contains filtered or unexported fields
}

func (UnsupportedArgError) Error 

func (e UnsupportedArgError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.