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

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

Documentation

Index

• Variables
• func NewDatasource(c Driver) *sqldatasource
• type Completable
• type Driver
• type FormatQueryOption
• type MacroFunc
• type Macros
• type Query
  • func GetQuery(query backend.DataQuery) (*Query, error)
  • func (q *Query) WithSQL(query string) *Query
• type Response
  • func NewResponse(res *backend.QueryDataResponse) *Response
  • func (r *Response) Response() *backend.QueryDataResponse
  • func (r *Response) Set(refID string, res backend.DataResponse)

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 (
	// 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) *sqldatasource

NewDatasource initializes the Datasource wrapper and instance manager

Types

type Completable

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

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

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
	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 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"`

	RefID         string            `json:"-"`
	Interval      time.Duration     `json:"-"`
	TimeRange     backend.TimeRange `json:"-"`
	MaxDataPoints int64             `json:"-"`
	FillMissing   *data.FillMissing `json:"fillMode,omitempty"`

	// Macros
	Schema string `json:"schema,omitempty"`
	Table  string `json:"table,omitempty"`
	Column string `json:"column,omitempty"`
}

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

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)