baranka

README

baranka

A simple and flexible helper for preparing SQL queries with positional parameters for SQL databases like PostgreSQL, MySQL, or SQLite.

Features

• Generates SQL value blocks with correct placeholders ($1, $2, ... or ?)
• Supports custom value templates (e.g., (%s))
• Collects arguments for use with database drivers
• Supports SQL expressions with placeholders and arguments
• Easily extensible with options

Installation

go get github.com/kaatinga/baranka

Usage

Basic Example

import "github.com/kaatinga/baranka"

b := baranka.New()
b.Add(1, "foo")
b.Add(2, "bar")

query := "INSERT INTO my_table (id, name) VALUES " + b.Values()
args := b.Args()
// Use query and args with your database/sql driver

Using Options

You can customize the placeholder format and value template:

b := baranka.New(
    baranka.WithIncludeTemplate("(%s)"),
    baranka.WithPlaceholderFormat(baranka.PlaceholderFormatQuestionMark),
)

b.Add(1, "foo")
b.Add(2, "bar")

query := "INSERT INTO my_table (id, name) VALUES " + b.Values()
// VALUES (?,?),\n(?,?)
args := b.Args()
// [1, "foo", 2, "bar"]

Using Expressions

You can embed SQL expressions with their own placeholders and arguments using the Expression type.

How to use Expression

• Create expressions with NewExpression(template, args...).
• The template uses %s for each argument you want to substitute with a placeholder.
• The number of %s in the template must match the number of arguments — NewExpression panics on a mismatch or if the template contains any other % verb.
• Placeholders ($1, $2, ?, etc.) will be substituted for each %s in the template, and the corresponding values will be appended to the argument list.

Example

b := baranka.New(baranka.WithPlaceholderFormat(baranka.PlaceholderFormatDollar))

b.Add(baranka.NewExpression("POINT(%s %s)", 10.1, 20.2))
b.Add(baranka.NewExpression("POINT(%s %s)", 11.1, 21.2))

query := "INSERT INTO points (geom) VALUES " + b.Values()
// Resulting VALUES: (POINT($1 $2)),\n(POINT($3 $4))
args := b.Args()
// [10.1, 20.2, 11.1, 21.2]

API

New(opts ...option) *Baranka

Creates a new Baranka helper with optional configuration.

(*Baranka) Add(args ...any)

Adds a new block of values and collects arguments. Supports Expression for SQL fragments.

(*Baranka) Args() []any

Returns an independent snapshot of the collected arguments in order. The returned slice remains unchanged if the Baranka instance is reset, reused, or modified later.

(*Baranka) Reset()

Clears the collected arguments and value blocks, releases references to their contents, and restarts dollar placeholders at $1. Allocated slice capacity is kept so the instance can be reused efficiently.

(*Baranka) Values() string

Returns the SQL value blocks as a string, e.g. ($1,$2),\n($3,$4) or (?,?).

Options

• WithIncludeTemplate(template string)
  Sets the template for value blocks (default: (%s)). The template must contain exactly one %s and no other % verbs; invalid templates are ignored.

• WithPlaceholderFormat(format PlaceholderFormat)
  Sets the placeholder format:

  • PlaceholderFormatDollar (default, for PostgreSQL: $1, $2, ...)
  • PlaceholderFormatQuestionMark (for MySQL/SQLite: ?)

• WithBlocksLength(length int)
  Pre-allocates the argument and value-block slices for performance. The length must be non-negative; a negative length causes an immediate panic.

Example: Bulk Insert

b := baranka.New(
    baranka.WithIncludeTemplate("(%s)"),
    baranka.WithPlaceholderFormat(baranka.PlaceholderFormatDollar),
)

for _, row := range rows {
    b.Add(row.ID, row.Name)
}

query := "INSERT INTO users (id, name) VALUES " + b.Values()
args := b.Args()
// db.Exec(query, args...)

Testing

Run tests with:

go test ./...

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Documentation

Index

• func WithBlocksLength(length int) option
• func WithIncludeTemplate(template string) option
• func WithPlaceholderFormat(format PlaceholderFormat) option
• type Baranka
  • func New(opts ...option) *Baranka
  • func (b *Baranka) Add(newArgs ...any)
  • func (b *Baranka) Args() []any
  • func (b *Baranka) Reset()
  • func (b *Baranka) Values() string
• type Expression
  • func NewExpression(template string, args ...any) Expression
• type PlaceholderFormat

Functions

func WithBlocksLength

func WithBlocksLength(length int) option

WithBlocksLength sets the expected number of blocks for the Baranka instance. It panics if length is negative.

func WithIncludeTemplate

func WithIncludeTemplate(template string) option

WithIncludeTemplate sets the template for value blocks (default: "(%s)"). The template must contain exactly one %s and no other % verbs; invalid templates are ignored and the default is kept.

func WithPlaceholderFormat

func WithPlaceholderFormat(format PlaceholderFormat) option

WithPlaceholderFormat sets the placeholder format for the Baranka instance.

Types

type Baranka

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

func New

func New(opts ...option) *Baranka

New creates a new Baranka.

func (*Baranka) Add

func (b *Baranka) Add(newArgs ...any)

Add appends a new block of arguments and generates corresponding placeholders.

func (*Baranka) Args

func (b *Baranka) Args() []any

Args returns an independent snapshot of the collected arguments in order.

func (*Baranka) Reset

func (b *Baranka) Reset()

Reset clears the collected arguments and blocks, releasing their references while keeping allocated capacity so the instance can be reused without re-allocating.

func (*Baranka) Values

func (b *Baranka) Values() string

Values returns the SQL value blocks as a string, e.g. ($1,$2),\n($3,$4).

type Expression

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

Expression is a SQL fragment with its own placeholders, e.g. "POINT(%s %s)". Each %s in the template is replaced with a placeholder ($1, ?, ...) and the corresponding argument is collected for the driver. Construct it with NewExpression. Literal % characters are not supported in the template.

func NewExpression

func NewExpression(template string, args ...any) Expression

NewExpression creates an Expression. It panics if the number of %s verbs in the template does not match the number of arguments, or if the template contains any other % verb — both would silently produce invalid SQL.

type PlaceholderFormat

type PlaceholderFormat byte

PlaceholderFormat specifies the placeholder style for SQL queries.

const (
	// PlaceholderFormatDollar uses $1, $2, ... (PostgreSQL style).
	PlaceholderFormatDollar PlaceholderFormat = iota
	// PlaceholderFormatQuestionMark uses ?, ?, ... (MySQL/SQLite style).
	PlaceholderFormatQuestionMark
)