dsquery

Documentation

Overview

Package dsquery provides mechanisms for managing templated queries to be executed against a data source.

The types in this package are agnostic to the type of data source being used (e.g. RDBMS, NoSQL, cache). Instead, these types are concerned with reading templated queries from files and populating those templates with variables a runtime. The actual execution of queries is the responsibility of clients that understand the type of data source in use (see the rdbms package).

Most Granitic applications requiring access to a data source will enable the QueryManager facility which provides access to an instance of the TemplatedQueryManager type defined in this package. Instructions on configuring and using the QueryManager facility can be found at https://granitic.io/ref/query-management also see the package documentation for the facility/querymanager package for some basic examples.

Index

• type ConfigurableProcessor
  • func (cp *ConfigurableProcessor) EscapeParamValue(v *ParamValueContext)
  • func (cp *ConfigurableProcessor) SubstituteUnset(v *ParamValueContext) error
• type ParamValueContext
• type ParamValueProcessor
• type QueryManager
• type SQLProcessor
  • func (sp *SQLProcessor) EscapeParamValue(v *ParamValueContext)
  • func (sp *SQLProcessor) SubstituteUnset(v *ParamValueContext) error
• type TemplatedQueryManager
  • func NewTemplatedQueryManager() *TemplatedQueryManager
  • func (qm *TemplatedQueryManager) BuildQueryFromID(qid string, params map[string]interface{}) (string, error)
  • func (qm *TemplatedQueryManager) FragmentFromID(qid string) (string, error)
  • func (qm *TemplatedQueryManager) StartComponent() error

Types

type ConfigurableProcessor

type ConfigurableProcessor struct {
	// Whether string parameters should have their contents wrapped with the string defined in StringWrapWith before
	// being injected into the query. For example, SQL RDBMSs usually require strings to be wrapped with ' or "
	WrapStrings bool

	// Whether or not strings that are set to the same value as DefaultParameterValue should be wrapped
	DisableWrapWhenDefaultParameterValue bool

	// Use the value of 'DefaultParameterValue' instead of returning an error if a parameter required for a query is missing
	UseDefaultForMissingParameter bool

	// The value to use when populating a query if the named value is missing
	DefaultParameterValue interface{}

	// If a default value has been substituted for a missing parameter, prevent further escaping
	EscapeDefaultValues bool

	// A string that will be used as a prefix and suffix to a string parameter if WrapStrings is true.
	StringWrapWith string
}

ConfigurableProcessor allows missing parameter values to be substituted for a defined value and for string (and nilable string) values to be wrapped with a defined character (e.g. ')

func (*ConfigurableProcessor) EscapeParamValue

func (cp *ConfigurableProcessor) EscapeParamValue(v *ParamValueContext)

EscapeParamValue implements ParamValueProcessor.EscapeParamValue

func (*ConfigurableProcessor) SubstituteUnset

func (cp *ConfigurableProcessor) SubstituteUnset(v *ParamValueContext) error

SubstituteUnset implements ParamValueProcessor.SubstituteUnset

type ParamValueContext

type ParamValueContext struct {
	Key     string
	Value   interface{}
	QueryID string
	Escaped bool
}

ParamValueContext holds the value of parameter to be injected into a query along with meta-data to aid processing and substitution

type ParamValueProcessor

type ParamValueProcessor interface {
	EscapeParamValue(v *ParamValueContext)
	SubstituteUnset(v *ParamValueContext) error
}

ParamValueProcessor is implemented by components able to escape the value of a parameter to a query and handle unset parameters

type QueryManager

type QueryManager interface {
	// BuildQueryFromID finds a template with the supplied query ID and uses the supplied named parameters to populate
	// that template. Returns the populated query or an error if the template could not be found or there was a problem
	// populating the query.
	BuildQueryFromID(qid string, params map[string]interface{}) (string, error)

	// FragmentFromID is used to recover a template which does not have any parameters to populate (a fragment). This is most commonly
	// used when code needs to dynamically construct a query from several fragments and templates. Returns the fragment
	// or an error if the fragment could not be found.
	FragmentFromID(qid string) (string, error)
}

A QueryManager is a type that is able to populate a pre-defined template query given a set of named parameters and return a complete query ready for execution against some data source.

type SQLProcessor

type SQLProcessor struct {
	BoolTrue  string
	BoolFalse string
}

SQLProcessor replaces missing values with the word null, wraps strings with single quotes and replaces bool values with the value the BoolTrue and BoolFalse members

func (*SQLProcessor) EscapeParamValue

func (sp *SQLProcessor) EscapeParamValue(v *ParamValueContext)

EscapeParamValue modifies the value in the supplied parameter + value so that is beocomes valid SQL (e.g. quotes strings, converts to RDBMS specific representation of booleans)

func (*SQLProcessor) SubstituteUnset

func (sp *SQLProcessor) SubstituteUnset(v *ParamValueContext) error

SubstituteUnset changes the value of a unset parameter value to null

type TemplatedQueryManager

type TemplatedQueryManager struct {

	// The path to a folder where template files are stored.
	TemplateLocation string

	// A regular expression that allows variable names to be recognised in queries.
	VarMatchRegEx string

	// Logger used by Granitic framework components. Automatically injected.
	FrameworkLogger logging.Logger

	// Lines in a template file starting with this string are considered to indicate the start of a new query template. The remainder
	// of the line will be used as the ID of that query template.
	QueryIDPrefix string

	// Whether or not query IDs should have leading and trailing whitespace removed.
	TrimIDWhiteSpace bool

	// A component able to handle missing parameter values and the escaping of supplied parameters
	ValueProcessor ParamValueProcessor

	// Whether or not a stock ParamValueProcessor should be injected into this component (set to false if defining your own)
	CreateDefaultValueProcessor bool

	// The character sequence that indicates a new line in a template file (e.g. \n)
	NewLine string

	// The separator string to use been elements of a processed array parameter (e.g , )
	ElementSeparator string
	// contains filtered or unexported fields
}

TemplatedQueryManager is an implementation of QueryManager that reads files containing template queries, tokenizes them and populates them on demand with maps of named parameters. This is the implementation provided by the QueryManager facility. See https://granitic.io/ref/query-management for details.

func NewTemplatedQueryManager

func NewTemplatedQueryManager() *TemplatedQueryManager

NewTemplatedQueryManager creates a new, empty TemplatedQueryManager.

func (*TemplatedQueryManager) BuildQueryFromID

func (qm *TemplatedQueryManager) BuildQueryFromID(qid string, params map[string]interface{}) (string, error)

BuildQueryFromID implements QueryManager.BuildQueryFromID

func (*TemplatedQueryManager) FragmentFromID

func (qm *TemplatedQueryManager) FragmentFromID(qid string) (string, error)

FragmentFromID implements QueryManager.FragmentFromID

func (*TemplatedQueryManager) StartComponent

func (qm *TemplatedQueryManager) StartComponent() error

StartComponent is called by the IoC container. Loads, parses and tokenizes query templates. Returns an error if there was a problem loading, parsing or tokenizing.