sql

README

database/sql

The sql package provides a generic database connector built on top of database/sql. It is intended for cases where a lightweight query helper is preferred over a full ORM: open a connection, describe how to scan a row into a type, and call Query anywhere.

Import

import "github.com/raykavin/gobox/database/sql"

What it provides

• Connector[T] for executing queries and mapping each row to a caller-defined type
• ScanFunc[T] for describing how a single *sql.Rows cursor maps to T
• NewSQL for opening, pinging, and wrapping a database connection

Main types

• SQLConfig: driver name and DSN
• ScanFunc[T]: func(rows *sql.Rows) (T, error) called once per row
• Connector[T]: holds the connection and scan function, exposes Query and Close

Example

package main

import (
    "context"
    stdsql "database/sql"
    "log"

    kitql "github.com/raykavin/gobox/database/sql"
    _ "github.com/lib/pq"
)

type User struct {
    ID   int
    Name string
}

func main() {
    conn, err := kitql.NewSQL(kitql.SQLConfig{
        Driver: "postgres",
        DSN:    "postgres://user:pass@localhost/mydb?sslmode=disable",
    }, func(rows *stdsql.Rows) (User, error) {
        var u User
        return u, rows.Scan(&u.ID, &u.Name)
    })
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    users, err := conn.Query(context.Background(),
        "SELECT id, name FROM users WHERE active = $1", true)
    if err != nil {
        log.Fatal(err)
    }

    for _, u := range users {
        log.Printf("%d: %s", u.ID, u.Name)
    }
}

Notes

• the database driver must be imported separately with a blank import (e.g. _ "github.com/lib/pq")
• NewSQL calls PingContext immediately; a connection failure returns an error before the Connector is returned
• ScanFunc must call rows.Scan internally and must not advance the cursor; Query handles the rows.Next loop
• Query returns nil, nil (not an error) when the result set is empty
• Close releases the underlying connection pool; it should be called when the Connector is no longer needed

Documentation

Overview

Package sql provides a generic database connector that pairs a standard database/sql connection with a caller-supplied row scanner.

Connector[T] opens and pings the database on construction, then exposes a single Query method that executes a query and maps each row to T using the provided ScanFunc.

Usage

type User struct {
    ID   int
    Name string
}

conn, err := sql.NewSQL(sql.SQLConfig{
    Driver: "postgres",
    DSN:    "postgres://user:pass@localhost/mydb?sslmode=disable",
}, func(rows *stdsql.Rows) (User, error) {
    var u User
    return u, rows.Scan(&u.ID, &u.Name)
})
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

users, err := conn.Query(ctx, "SELECT id, name FROM users WHERE active = $1", true)

Index

• type Connector
  • func NewSQL[T any](cfg SQLConfig, scan ScanFunc[T]) (*Connector[T], error)
  • func (c *Connector[T]) Close() error
  • func (c *Connector[T]) Query(ctx context.Context, query string, args ...any) ([]T, error)
• type SQLConfig
• type ScanFunc

Types

type Connector

type Connector[T any] struct {
	// contains filtered or unexported fields
}

Connector is a generic database source that opens a connection using SQLConfig and converts each result row into T via a caller-supplied ScanFunc.

func NewSQL

func NewSQL[T any](cfg SQLConfig, scan ScanFunc[T]) (*Connector[T], error)

NewSQL opens and pings the database described by cfg, then returns a Connector ready to execute queries. The caller is responsible for calling Close when done.

func (*Connector[T]) Close

func (c *Connector[T]) Close() error

Close releases the underlying database connection pool.

func (*Connector[T]) Query

func (c *Connector[T]) Query(ctx context.Context, query string, args ...any) ([]T, error)

Query executes query with the optional args, applies the ScanFunc to each row and returns the accumulated results as []T.

type SQLConfig

type SQLConfig struct {
	// Driver is the database driver name registered via sql.Register
	// (e.g. "postgres", "mysql", "sqlite3").
	Driver string

	// DSN is the data source name passed verbatim to sql.Open.
	DSN string
}

SQLConfig holds the parameters needed to open a database connection.

type ScanFunc

type ScanFunc[T any] func(rows *sql.Rows) (T, error)

ScanFunc maps a single row from sql.Rows into a value of type T. It must call rows.Scan internally and must NOT advance the cursor - Connector.Query handles the rows.Next loop.