array

Documentation

Overview

Package array provides the `array` table-valued SQL function — a way to feed a Go slice into a SQL query as a single-column table.

The vtab is a Go-native re-implementation of SQLite's bundled carray (https://sqlite.org/carray.html) and the equivalent ncruces/ext/array module.

Transparent binding (preferred)

Wrap the slice with sqlite.Pointer and pass it as a regular query argument. SQLite's destructor callback releases the binding when the statement finalizes — no caller-side cleanup needed.

import (
    sqlite "gosqlite.org"
    "gosqlite.org/ext/array"
)

if err := array.Register(conn); err != nil { ... }

rows, _ := db.QueryContext(ctx,
    `SELECT value FROM array(?) ORDER BY value`,
    sqlite.Pointer([]int{10, 20, 30}))

Explicit Bind / Release (escape hatch)

For long-lived bindings (same slice across many queries) or when an int64 sentinel is more convenient than a wrapped argument, the explicit pair stays available:

token, release := array.Bind(conn, []int{10, 20, 30})
defer release()
rows, _ := db.QueryContext(ctx,
    `SELECT value FROM array(?) ORDER BY value`, token)

Supported element types

Bind accepts any of:

• []int, []int8, []int16, []int32, []int64
• []uint8 (treated as a single BLOB), []uint16, []uint32, []uint64
• []float32, []float64
• []bool
• []string
• [][]byte
• []any (each element coerced as above; nil becomes SQL NULL)

Anything else is reflect-walked; element kinds not in the list above surface a clear MISMATCH error from the cursor.

Blank-import auto-registration

For a pool-wide install via [gosqlite.org.Driver.ConnectHook], blank-import the auto sub-package:

import _ "gosqlite.org/ext/array/auto"

Index

• Constants
• Variables
• func Bind(c *sqlite.Conn, slice any) (token int64, release func())
• func Register(c *sqlite.Conn) error

Constants

const ModuleName = "array"

ModuleName is the SQL module name the vtab registers under: `array`.

Variables

var ErrUnknownToken = errors.New("array: unknown token; was the binding already released?")

ErrUnknownToken is returned by the array vtab cursor when Filter receives a token that has no corresponding Bind entry (typically because the binding was already released or the token was forged).

Functions

func Bind

func Bind(c *sqlite.Conn, slice any) (token int64, release func())

Bind registers slice for use with the array vtab and returns a token plus a release function. The token must be passed as the array() argument in the SQL:

token, release := array.Bind(conn, my[]int{...})
defer release()
rows, _ := db.Query(`SELECT value FROM array(?)`, token)

release frees the binding; calling it more than once is a no-op. Failing to release leaks the entry until process exit (the binding is held in a process-global map keyed by token). For long-running services, ALWAYS defer release immediately after Bind.

slice must be a slice / array / pointer-to-array of one of the supported element types listed in the package doc. Bind itself does not validate — invalid kinds surface as a MISMATCH error from the cursor's Column.

func Register

func Register(c *sqlite.Conn) error

Register installs the array module on c as an eponymous virtual table — callers can `SELECT … FROM array(?)` directly without a preceding CREATE VIRTUAL TABLE. Idempotent at the SQLite level; re-registering the same module name on the same connection is a no-op the driver tolerates.