sqlds

README

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 repitition 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.

Documentation

Index

• Variables
• func NewDatasource(c Driver) datasource.ServeOpts
• type Datasource
  • func (ds *Datasource) CheckHealth(ctx context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error)
  • func (ds *Datasource) NewDatasource(settings backend.DataSourceInstanceSettings) (instancemgmt.Instance, error)
  • func (ds *Datasource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error)
• type Driver
• type FormatQueryOption
• type MacroFunc
• type Macros
• type Query
  • func GetQuery(query backend.DataQuery) (*Query, error)
  • func (q *Query) WithSQL(query string) *Query

Variables

var (
	// ErrorBadDatasource ...
	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")
)

var (
	// ErrorNoArguments is returned when a macro is used but there were no arguments
	// TODO: Note that it's possible that not every macro has an argument, and we should maybe adjust for this case
	ErrorNoArguments = errors.New("there were no arguments provided to the macro")
	// ErrorBadArgumentCount is returned from macros when the wrong number of arguments were provided
	ErrorBadArgumentCount = errors.New("unexpected number of arguments")
)

Functions

func NewDatasource

func NewDatasource(c Driver) datasource.ServeOpts

NewDatasource initializes the Datasource wrapper and instance manager

Types

type Datasource

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

Datasource contains the entrypoints / handlers for the plugin, and manages the plugin instance

func (*Datasource) CheckHealth

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

CheckHealth calls the wrapped instance's CheckHealth function

func (*Datasource) NewDatasource

func (ds *Datasource) NewDatasource(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 (*Datasource) QueryData

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

QueryData calls the wrapped instance's QueryData function

type Driver

type Driver interface {
	// Connect connects to the database. It does not need to call `db.Ping()`
	Connect(backend.DataSourceInstanceSettings) (*sql.DB, error)
	FillMode() *data.FillMissing
	Macros() Macros
	StringConverters() []sqlutil.StringConverter
}

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 FormatQueryOption

type FormatQueryOption uint32

FormatQueryOption defines how the user has chosen to represent the data

const (
	// FormatOptionTimeSeries formats the query results as a timeseries using "WideToLong"
	FormatOptionTimeSeries FormatQueryOption = iota
	// FormatOptionTable formats the query results as a table using "LongToWide"
	FormatOptionTable
)

type MacroFunc

type MacroFunc func(*Query, []string) (string, error)

MacroFunc defines a signature for applying a query macro Query macro implementations are defined by users / consumers of this package

type Macros

type Macros map[string]MacroFunc

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

type Query

type Query struct {
	RawSQL string            `json:"rawSql"`
	Format FormatQueryOption `json:"format"`

	Interval      time.Duration     `json:"-"`
	TimeRange     backend.TimeRange `json:"-"`
	MaxDataPoints int64             `json:"-"`
}

Query is the model that represents the query that users submit from the panel / queryeditor. For the sake of backwards compatibility, when making changes to this type, ensure that changes are only additive.

func GetQuery

func GetQuery(query backend.DataQuery) (*Query, error)

GetQuery returns a Query object given a backend.DataQuery using json.Unmarshal

func (*Query) WithSQL

func (q *Query) WithSQL(query string) *Query

WithSQL copies the Query, but with a different RawSQL value. This is mostly useful in the Interpolate function, where the RawSQL value is modified in a loop