fireboltgosdk

README

Firebolt GO SDK

Firebolt GO driver is an implementation of database/sql/driver.

Installation

go get github.com/firebolt-db/firebolt-go-sdk

Example

Here is an example of establishing a connection and executing a simple select query. For it to run successfully, you have to specify your credentials, and have a default engine up and running.

package main

import (
	"database/sql"
	"fmt"
	// we need to import firebolt-go-sdk, so it is able to register its driver
	_ "github.com/firebolt-db/firebolt-go-sdk"
)

func main() {

	// constructing a dsn string, you need to set your credentials
	clientId := ""
	clientSecret := ""
	accountName := ""
	databaseName := ""
	dsn := fmt.Sprintf("firebolt:///%s?account_name=%s&client_id=%s&client_secret=%s", databaseName, accountName, clientId, clientSecret)

	// opening the firebolt driver
	db, err := sql.Open("firebolt", dsn)
	if err != nil {
		fmt.Println("error during opening a driver: %v", err)
	}

	// executing a simple select query
	rows, err := db.Query("SELECT 1 UNION SELECT 2")
	if err != nil {
		fmt.Println("error during select query: %v", err)
	}

	// iterating over the resulting rows
	defer rows.Close()
	for rows.Next() {
		var id int
		if err := rows.Scan(&id); err != nil {
			fmt.Println("error during scan: %v", err)
		}
		fmt.Println(id)
	}
}

DSN (Data source name)

All information for the connection should be specified using the DSN string. The firebolt dsn string has the following format:

firebolt://[/database]?account_name=account_name&client_id=client_id&client_secret=client_secret[&engine=engine]

• client_id - credentials client id.
• client_secret - credentials client secret.
• account_name - the name of Firebolt account to log in to.
• database - (optional) the name of the database to connect to.
• engine - (optional) the name of the engine to run SQL on.

Limitations

Although, all interfaces are available, not all of them are implemented or could be implemented:

• driver.Result is a dummy implementation and doesn't return the real result values.

Documentation

Index

• Constants
• func ConstructNestedError(message string, err error) error
• func ConstructUserAgentString() (ua_string string)
• func GetHostNameURL() string
• func ParseDSNString(dsn string) (*fireboltSettings, error)
• func SplitStatements(sql string) ([]string, error)
• func WithClientParams(accountID string, token string, userAgent string) driverOption
• func WithDatabaseName(databaseName string) driverOption
• func WithEngineUrl(engineUrl string) driverOption
• type AuthenticationResponse
• type BaseClient
  • func (c *BaseClient) Query(ctx context.Context, engineUrl, query string, parameters map[string]string, ...) (*QueryResponse, error)
• type Client
  • func Authenticate(settings *fireboltSettings, apiEndpoint string) (Client, error)
• type ClientImpl
  • func MakeClient(settings *fireboltSettings, apiEndpoint string) (*ClientImpl, error)
  • func (c *ClientImpl) GetConnectionParameters(ctx context.Context, engineName, databaseName string) (string, map[string]string, error)
• type ClientImplV0
  • func MakeClientV0(settings *fireboltSettings, apiEndpoint string) (*ClientImplV0, error)
  • func (c *ClientImplV0) GetConnectionParameters(ctx context.Context, engineName, databaseName string) (string, map[string]string, error)
• type Column
• type FireboltConnector
  • func FireboltConnectorWithOptions(opts ...driverOption) *FireboltConnector
  • func (c *FireboltConnector) Connect(ctx context.Context) (driver.Conn, error)
  • func (c *FireboltConnector) Driver() driver.Driver
• type FireboltDriver
  • func (d *FireboltDriver) Open(dsn string) (driver.Conn, error)
  • func (d *FireboltDriver) OpenConnector(dsn string) (driver.Connector, error)
• type FireboltResult
  • func (r FireboltResult) LastInsertId() (int64, error)
  • func (r FireboltResult) RowsAffected() (int64, error)
• type QueryResponse

Constants

const (
	ContentTypeForm = "application/x-www-form-urlencoded"
	ContentTypeJSON = "application/json"
)

const (
	ServiceAccountLoginURLSuffix = "/oauth/token"
	EngineUrlByAccountName       = "/web/v3/account/%s/engineUrl"
	AccountInfoByAccountName     = "/web/v3/account/%s/resolve"
	//API v0
	UsernamePasswordURLSuffix  = "/auth/v1/login"
	DefaultAccountURL          = "/iam/v2/account"
	AccountIdByNameURL         = "/iam/v2/accounts:getIdByName"
	EngineIdByNameURL          = "/core/v1/accounts/%s/engines:getIdByName"
	EngineByIdURL              = "/core/v1/accounts/%s/engines/%s"
	EngineUrlByDatabaseNameURL = "/core/v1/accounts/%s/engines:getURLByDatabaseName"
)

const AuthAudienceValue = "https://api.firebolt.io"

Functions

func ConstructNestedError

func ConstructNestedError(message string, err error) error

func ConstructUserAgentString

func ConstructUserAgentString() (ua_string string)

ConstructUserAgentString returns a string with go, GoSDK and os type and versions additionally user can set "FIREBOLT_GO_DRIVERS" and "FIREBOLT_GO_CLIENTS" env variable, and they will be concatenated with the final user-agent string

func GetHostNameURL

func GetHostNameURL() string

GetHostNameURL returns a hostname url, either default or overwritten with the environment variable

func ParseDSNString

func ParseDSNString(dsn string) (*fireboltSettings, error)

ParseDSNString parses a dsn in a format: firebolt://username:password@db_name[/engine_name][?account_name=organization] returns a settings object where all parsed values are populated returns an error if required fields couldn't be parsed or if after parsing some characters were left unparsed

func SplitStatements

func SplitStatements(sql string) ([]string, error)

SplitStatements split multiple statements into a list of statements

func WithClientParams

func WithClientParams(accountID string, token string, userAgent string) driverOption

WithClientParams defines client parameters for the driver

func WithDatabaseName

func WithDatabaseName(databaseName string) driverOption

WithDatabaseName defines database name for the driver

func WithEngineUrl

func WithEngineUrl(engineUrl string) driverOption

WithEngineUrl defines engine url for the driver

Types

type AuthenticationResponse

type AuthenticationResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
	TokenType    string `json:"token_type"`
	Scope        string `json:"scope"`
}

type BaseClient

type BaseClient struct {
	ClientID     string
	ClientSecret string
	AccountID    string
	ApiEndpoint  string
	UserAgent    string
	// contains filtered or unexported fields
}

func (*BaseClient) Query

func (c *BaseClient) Query(ctx context.Context, engineUrl, query string, parameters map[string]string, control connectionControl) (*QueryResponse, error)

Query sends a query to the engine URL and populates queryResponse, if query was successful

type Client

type Client interface {
	GetConnectionParameters(ctx context.Context, engineName string, databaseName string) (string, map[string]string, error)
	Query(ctx context.Context, engineUrl, query string, parameters map[string]string, control connectionControl) (*QueryResponse, error)
}

func Authenticate

func Authenticate(settings *fireboltSettings, apiEndpoint string) (Client, error)

Authenticate sends an authentication request, and returns a newly constructed client object

type ClientImpl

type ClientImpl struct {
	ConnectedToSystemEngine bool
	SystemEngineURL         string
	AccountVersion          int
	BaseClient
}

func MakeClient

func MakeClient(settings *fireboltSettings, apiEndpoint string) (*ClientImpl, error)

func (*ClientImpl) GetConnectionParameters

func (c *ClientImpl) GetConnectionParameters(ctx context.Context, engineName, databaseName string) (string, map[string]string, error)

GetConnectionParameters returns engine URL and parameters based on engineName and databaseName

type ClientImplV0

type ClientImplV0 struct {
	BaseClient
}

func MakeClientV0

func MakeClientV0(settings *fireboltSettings, apiEndpoint string) (*ClientImplV0, error)

func (*ClientImplV0) GetConnectionParameters

func (c *ClientImplV0) GetConnectionParameters(ctx context.Context, engineName, databaseName string) (string, map[string]string, error)

GetConnectionParameters returns engine URL and engine name based on engineName and accountId

type Column

type Column struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type FireboltConnector

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

FireboltConnector is an intermediate type between a Connection and a Driver which stores session data

func FireboltConnectorWithOptions

func FireboltConnectorWithOptions(opts ...driverOption) *FireboltConnector

FireboltConnectorWithOptions builds a custom connector

func (*FireboltConnector) Connect

func (c *FireboltConnector) Connect(ctx context.Context) (driver.Conn, error)

Connect returns a connection to the database

func (*FireboltConnector) Driver

func (c *FireboltConnector) Driver() driver.Driver

Driver returns the underlying driver of the Connector

type FireboltDriver

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

func (*FireboltDriver) Open

func (d *FireboltDriver) Open(dsn string) (driver.Conn, error)

Open parses the dsn string, and if correct tries to establish a connection

func (*FireboltDriver) OpenConnector

func (d *FireboltDriver) OpenConnector(dsn string) (driver.Connector, error)

type FireboltResult

type FireboltResult struct {
}

func (FireboltResult) LastInsertId

func (r FireboltResult) LastInsertId() (int64, error)

LastInsertId returns last inserted ID, not supported by firebolt

func (FireboltResult) RowsAffected

func (r FireboltResult) RowsAffected() (int64, error)

RowsAffected returns a number of affected rows, not supported by firebolt

type QueryResponse

type QueryResponse struct {
	Query      interface{}     `json:"query"`
	Meta       []Column        `json:"meta"`
	Data       [][]interface{} `json:"data"`
	Rows       int             `json:"rows"`
	Statistics interface{}     `json:"statistics"`
}