sqlds

package module
v4.1.4 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2024 License: Apache-2.0 Imports: 23 Imported by: 11

README

Build Status

sqlds

sqlds stands for SQL Datasource.

Most SQL-driven datasources, like Postgres, MySQL, and MSSQL share extremely similar codebases.

The sqlds package is intended to remove the repetition of these datasources and centralize the datasource logic. The only thing that the datasources themselves should have to define is connecting to the database, and what driver to use, and the plugin frontend.

Usage

if err := datasource.Manage("my-datasource", datasourceFactory, datasource.ManageOpts{}); err != nil {
  log.DefaultLogger.Error(err.Error())
  os.Exit(1)
}

func datasourceFactory(ctx context.Context, s backend.DataSourceInstanceSettings) (instancemgmt.Instance, error) {
  ds := sqlds.NewDatasource(&myDatasource{})
  return ds.NewDatasource(ctx, s)
}

Standardization

Macros

The sqlds package formerly defined a set of default macros, but those have been migrated to grafana-plugin-sdk-go: see the code for details.

Documentation

Index

Constants

View Source 
const (
	StatusOK         Status   = "ok"
	StatusError      Status   = "error"
	EndpointHealth   Endpoint = "health"
	EndpointQuery    Endpoint = "query"
	SourceDownstream Source   = "downstream"
	SourcePlugin     Source   = "plugin"
)
View Source 
const (
	// FormatOptionTimeSeries formats the query results as a timeseries using "LongToWide"
	FormatOptionTimeSeries = sqlutil.FormatOptionTimeSeries
	// FormatOptionTable formats the query results as a table using "LongToWide"
	FormatOptionTable = sqlutil.FormatOptionTable
	// FormatOptionLogs sets the preferred visualization to logs
	FormatOptionLogs = sqlutil.FormatOptionLogs
	// FormatOptionsTrace sets the preferred visualization to trace
	FormatOptionTrace = sqlutil.FormatOptionTrace
	// FormatOptionMulti formats the query results as a timeseries using "LongToMulti"
	FormatOptionMulti = sqlutil.FormatOptionMulti
)

Deprecated: use the values in sqlutil directly instead

View Source 
const MockDataFolder = "/mock-data"

MockDataFolder is the default folder that will contain data files

Variables

View Source 
var (
	// ErrorNotImplemented is returned if the function is not implemented by the provided Driver (the Completable pointer is nil)
	ErrorNotImplemented = errors.New("not implemented")
	// ErrorWrongOptions when trying to parse Options with a invalid JSON
	ErrorWrongOptions = errors.New("error reading query options")
)
View Source 
var (
	ErrorMissingMultipleConnectionsConfig = PluginError(errors.New("received connection arguments but the feature is not enabled"))
	ErrorMissingDBConnection              = PluginError(errors.New("unable to get default db connection"))
	HeaderKey                             = "grafana-http-headers"
	// Deprecated: ErrorMissingMultipleConnectionsConfig should be used instead
	MissingMultipleConnectionsConfig = ErrorMissingMultipleConnectionsConfig
	// Deprecated: ErrorMissingDBConnection should be used instead
	MissingDBConnection = ErrorMissingDBConnection
)
View Source 
var (
	// ErrorBadDatasource is returned if the data source could not be asserted to the correct type (this should basically never happen?)
	ErrorBadDatasource = errors.New("type assertion to datasource failed")
	// ErrorJSON is returned when json.Unmarshal fails
	ErrorJSON = errors.New("error unmarshaling query JSON the Query Model")
	// ErrorQuery is returned when the query could not complete / execute
	ErrorQuery = errors.New("error querying the database")
	// ErrorTimeout is returned if the query has timed out
	ErrorTimeout = errors.New("query timeout exceeded")
	// ErrorNoResults is returned if there were no results returned
	ErrorNoResults = errors.New("no results returned from query")
)
View Source 
var DefaultMacros = sqlutil.DefaultMacros

Deprecated: use sqlutil.DefaultMacros directly

View Source 
var (
	ErrorParsingMacroBrackets = errors.New("failed to parse macro arguments (missing close bracket?)")
)

Functions

func CreateMockData 

func CreateMockData(table string, folder string, csvData string) error

CreateData will create a "table" (csv file) in the data folder that can be queried with SQL

func CreateMockTable 

func CreateMockTable(table string, folder string) error

Create will create a "table" (csv file) in the data folder that can be queried with SQL

func DownstreamError 

func DownstreamError(err error, override ...bool) error

func ErrorSource 

func ErrorSource(err error) backend.ErrorSource

func Interpolate 

func Interpolate(driver Driver, query *Query) (string, error)

Interpolate wraps sqlutil.Interpolate for temporary backwards-compatibility Deprecated: use sqlutil.Interpolate directly

func PluginError 

func PluginError(err error, override ...bool) error

Types

type CheckHealthMutator added in v4.1.0 

type CheckHealthMutator interface {
	MutateCheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (context.Context, *backend.CheckHealthRequest)
}

CheckHealthMutator is an additional interface that could be implemented by driver. This adds ability to the driver to optionally mutate the CheckHealth before it's run

type Completable 

type Completable interface {
	Schemas(ctx context.Context, options Options) ([]string, error)
	Tables(ctx context.Context, options Options) ([]string, error)
	Columns(ctx context.Context, options Options) ([]string, error)
}

Completable will be used to autocomplete Tables Schemas and Columns for SQL languages

type Connection 

type Connection interface {
	Close() error
	Ping() error
	PingContext(ctx context.Context) error
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
}

Connection represents a SQL connection and is satisfied by the *sql.DB type For now, we only add the functions that we need / actively use. Some other candidates for future use could include the ExecContext and BeginTxContext functions

type Connector 

type Connector struct {
	UID string
	// contains filtered or unexported fields
}

func NewConnector 

func NewConnector(ctx context.Context, driver Driver, settings backend.DataSourceInstanceSettings, enableMultipleConnections bool) (*Connector, error)

func (*Connector) Connect 

func (c *Connector) Connect(ctx context.Context, headers http.Header) (*dbConnection, error)

func (*Connector) Dispose added in v4.1.3 

func (c *Connector) Dispose()

Dispose is called when an existing SQLDatasource needs to be replaced

func (*Connector) GetConnectionFromQuery 

func (c *Connector) GetConnectionFromQuery(ctx context.Context, q *Query) (string, dbConnection, error)

func (*Connector) Reconnect 

func (c *Connector) Reconnect(ctx context.Context, dbConn dbConnection, q *Query, cacheKey string) (*sql.DB, error)

type DBQuery 

type DBQuery struct {
	DB Connection

	Settings backend.DataSourceInstanceSettings

	DSName string
	// contains filtered or unexported fields
}

func NewQuery 

func NewQuery(db Connection, settings backend.DataSourceInstanceSettings, converters []sqlutil.Converter, fillMode *data.FillMissing) *DBQuery

func (*DBQuery) Run 

func (q *DBQuery) Run(ctx context.Context, query *Query, args ...interface{}) (data.Frames, error)

Run sends the query to the connection and converts the rows to a dataframe.

type Driver 

type Driver interface {
	// Connect connects to the database. It does not need to call `db.Ping()`
	Connect(context.Context, backend.DataSourceInstanceSettings, json.RawMessage) (*sql.DB, error)
	// Settings are read whenever the plugin is initialized, or after the data source settings are updated
	Settings(context.Context, backend.DataSourceInstanceSettings) DriverSettings
	Macros() Macros
	Converters() []sqlutil.Converter
}

Driver is a simple interface that defines how to connect to a backend SQL datasource Plugin creators will need to implement this in order to create a managed datasource

type DriverSettings 

type DriverSettings struct {
	FillMode       *data.FillMissing
	RetryOn        []string
	Timeout        time.Duration
	Retries        int
	Pause          int
	ForwardHeaders bool
	Errors         bool
}

type Endpoint 

type Endpoint string

type FormatQueryOption 

type FormatQueryOption = sqlutil.FormatQueryOption

FormatQueryOption defines how the user has chosen to represent the data Deprecated: use sqlutil.FormatQueryOption directly instead

type HealthChecker 

type HealthChecker struct {
	Connector *Connector
	Metrics   Metrics
}

func (*HealthChecker) Check 

func (hc *HealthChecker) Check(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error)

type MacroFunc 

type MacroFunc = sqlutil.MacroFunc

MacroFunc defines a signature for applying a query macro Query macro implementations are defined by users / consumers of this package Deprecated: use sqlutil.MacroFunc directly

type Macros 

type Macros = sqlutil.Macros

Macros is a list of MacroFuncs. The "string" key is the name of the macro function. This name has to be regex friendly. Deprecated: use sqlutil.Macros directly

type Metrics 

type Metrics struct {
	DSName   string
	DSType   string
	Endpoint Endpoint
}

func NewMetrics 

func NewMetrics(dsName, dsType string, endpoint Endpoint) Metrics

func (*Metrics) CollectDuration 

func (m *Metrics) CollectDuration(source Source, status Status, duration float64)

func (*Metrics) WithEndpoint 

func (m *Metrics) WithEndpoint(endpoint Endpoint) Metrics

type Options 

type Options map[string]string

Options are used to query schemas, tables and columns. They will be encoded in the request body (e.g. {"database": "mydb"})

func ParseOptions 

func ParseOptions(rawOptions json.RawMessage) (Options, error)

type Query deprecated 

type Query = sqlutil.Query

Deprecated: use sqlutil.Query directly instead

func GetQuery 

func GetQuery(query backend.DataQuery, headers http.Header, setHeaders bool) (*Query, error)

GetQuery wraps sqlutil's GetQuery to add headers if needed

type QueryArgSetter 

type QueryArgSetter interface {
	SetQueryArgs(ctx context.Context, headers http.Header) []interface{}
}

QueryArgSetter is an additional interface that could be implemented by driver. This adds the ability to the driver to optionally set query args that are then sent down to the database.

type QueryDataMutator added in v4.1.0 

type QueryDataMutator interface {
	MutateQueryData(ctx context.Context, req *backend.QueryDataRequest) (context.Context, *backend.QueryDataRequest)
}

QueryDataMutator is an additional interface that could be implemented by driver. This adds ability to the driver to optionally mutate the query before it's run with the QueryDataRequest.

type QueryMutator 

type QueryMutator interface {
	MutateQuery(ctx context.Context, req backend.DataQuery) (context.Context, backend.DataQuery)
}

QueryMutator is an additional interface that could be implemented by driver. This adds ability to the driver it can mutate query before run.

type Response 

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

func NewResponse 

func NewResponse(res *backend.QueryDataResponse) *Response

func (*Response) Response 

func (r *Response) Response() *backend.QueryDataResponse

func (*Response) Set 

func (r *Response) Set(refID string, res backend.DataResponse)

type ResponseMutator 

type ResponseMutator interface {
	MutateResponse(ctx context.Context, res data.Frames) (data.Frames, error)
}

ResponseMutator is an additional interface that could be implemented by driver. This adds ability to the driver, so it can mutate a response from the driver before its returned to the client.

type SQLDatasource 

type SQLDatasource struct {
	Completable
	backend.CallResourceHandler

	CustomRoutes map[string]func(http.ResponseWriter, *http.Request)

	EnableMultipleConnections bool
	// contains filtered or unexported fields
}

func NewDatasource 

func NewDatasource(c Driver) *SQLDatasource

NewDatasource initializes the Datasource wrapper and instance manager

func (*SQLDatasource) CheckHealth 

func (ds *SQLDatasource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error)

CheckHealth pings the connected SQL database

func (*SQLDatasource) Dispose 

func (ds *SQLDatasource) Dispose()

Dispose cleans up datasource instance resources. Note: Called when testing and saving a datasource

func (*SQLDatasource) DriverSettings 

func (ds *SQLDatasource) DriverSettings() DriverSettings

func (*SQLDatasource) GetDBFromQuery 

func (ds *SQLDatasource) GetDBFromQuery(ctx context.Context, q *Query) (*sql.DB, error)

func (*SQLDatasource) NewDatasource 

func (ds *SQLDatasource) NewDatasource(ctx context.Context, settings backend.DataSourceInstanceSettings) (instancemgmt.Instance, error)

NewDatasource creates a new `SQLDatasource`. It uses the provided settings argument to call the ds.Driver to connect to the SQL server

func (*SQLDatasource) QueryData 

func (ds *SQLDatasource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error)

QueryData creates the Responses list and executes each query

type SQLMock 

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

SQLMock connects to a local folder with csv files

func (*SQLMock) Connect 

func (h *SQLMock) Connect(_ context.Context, _ backend.DataSourceInstanceSettings, msg json.RawMessage) (*sql.DB, error)

Connect opens a sql.DB connection using datasource settings

func (*SQLMock) Converters 

func (h *SQLMock) Converters() []sqlutil.Converter

Converters defines list of string convertors

func (*SQLMock) Macros 

func (h *SQLMock) Macros() Macros

Macros returns list of macro functions convert the macros of raw query

func (*SQLMock) Settings 

func (h *SQLMock) Settings(_ context.Context, _ backend.DataSourceInstanceSettings) DriverSettings

type Source 

type Source string

type Status 

type Status string

Source Files

View all Source files

Directories

Path Synopsis
csv

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.