sqltemplate

README

go-sqltemplate

Rewrite a SQL template into a parameterized query. A statement carries two kinds of variable: {{name}} becomes an ordered, value-deduplicated bind placeholder ($1, $2, …) whose values are returned alongside the query, and {{.name}} is substituted verbatim (sanitized) for composing SQL fragments such as a sub-query source.

Install

go get github.com/gomatic/go-sqltemplate

Usage

package main

import (
	"fmt"

	"github.com/gomatic/go-sqltemplate"
)

func main() {
	result, err := sqltemplate.Parameterize(
		"select * from ({{.source}}) as s where name={{name}}::text and value={{value}}::text",
		sqltemplate.Params{"source": "select 1", "name": "abc", "value": "123"},
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.SQL)      // select * from (select 1) as s where name=$1::text and value=$2::text
	fmt.Println(result.Bindings) // [abc 123]
}

Verbatim values are sanitized before substitution; bind values are passed through untouched for the driver to parameterize. A statement that cannot be parsed or rendered returns an error matchable with errors.Is(err, sqltemplate.ErrInvalidStatement).

Maintenance

The shared build config (Makefile, .golangci.yaml, .editorconfig, .gitignore, .github/) is owned and distributed by nicerobot/tools.repository — do not edit it in-tree; per-repo divergence belongs in a Makefile.local.

Documentation

Overview

Package sqltemplate rewrites a SQL template into a parameterized query.

A statement carries two kinds of variables:

{{name}}  - rewritten into ordered bind placeholders ($1, $2, ...) whose
            values are returned alongside the query. Identical values are
            deduplicated to a single placeholder.
{{.name}} - substituted verbatim into the statement (for composing SQL
            fragments such as a sub-query source).

For example, given the statement

select * from ({{.source}}) as s where name={{name}}::text and value={{value}}::text

and the parameters name="abc", value="123", source="select 1" the engine produces

select * from (select 1) as s where name=$1::text and value=$2::text

with bindings ["abc", "123"]. Bind values ({{name}}) are passed to the driver untouched — the $N placeholders make them injection-safe regardless of content.

Verbatim values ({{.name}}) are substituted directly into the SQL text, so they must be TRUSTED fragments (e.g. a controlled sub-query source). The strip of ;'" is only a backstop, not a defense against injection; never feed untrusted input through {{.name}} — use a {{name}} bind placeholder instead.

The package is pure and has no dependencies beyond the standard library: it performs only string and text/template work and never touches a database or driver.

Index

• type Error
  • func (e Error) Error() string
• type Name
• type Params
• type Query
• type Result
  • func Parameterize(statement Statement, params Params) (Result, error)
• type Statement
  • func Normalize(statement Statement) Statement
• type Value

Types

type Error

type Error string

Error is the sentinel error type for the sqltemplate package.

const ErrInvalidStatement Error = "sqltemplate: invalid sql statement"

ErrInvalidStatement is returned when a statement cannot be parsed or rendered into a parameterized query.

func (Error) Error

func (e Error) Error() string

Error returns the error message.

type Name

type Name string

Name is the identifier of a template variable.

type Params

type Params map[Name]Value

Params maps variable names to their values.

type Query

type Query string

Query is a rendered statement whose binds are $1, $2, ... placeholders.

type Result

type Result struct {
	SQL      Query   `json:"sql"`
	Bindings []Value `json:"bindings"`
}

Result is the outcome of rendering a statement.

func Parameterize

func Parameterize(statement Statement, params Params) (Result, error)

Parameterize renders statement against params into a query plus bindings.

type Statement

type Statement string

Statement is a SQL template containing {{name}} and {{.name}} variables.

func Normalize

func Normalize(statement Statement) Statement

Normalize collapses runs of whitespace in a statement to single spaces.

type Value

type Value string

Value is the textual value bound to a template variable.