lightning

README

go-lightning

go-lightning is a lightweight, high-performance database interaction library for Go. It is designed to be slim, fast, and easy to use, especially when working with projections and Data Transfer Objects (DTOs).

The project is currently used in a production environment.

Key Features

• Unified API: The lit package provides a single API for both PostgreSQL and MySQL, with driver-specific optimizations handled internally.
• Lightweight Projections: The biggest advantage of go-lightning is its ability to load DTOs and projections with minimal effort. Regardless of your table structure, mapping a query result to a Go struct is straightforward and clean.
• MySQL and PostgreSQL Support: Register your models with the appropriate driver and the library handles query generation and driver-specific optimizations.
• Generic CRUD Operations: Automatic generation of INSERT and UPDATE queries for registered types.
• Works with DB and Tx: All operations accept both *sql.DB and *sql.Tx via the Executor interface.
• Minimal Dependencies: Keeps your project slim and focused.

Docs

Documentation is available at https://tracewayapp.github.io/go-lightning

Usage Limitations

• ID Column Requirement: For automatic Insert and Update operations, the library requires your tables to have an id column. It does not support tables without a primary id field for these specific automatic operations.

Installation

go get github.com/tracewayapp/go-lightning/lit

Configuration & Usage

1. Registration

Every model you intend to use with generic functions must be registered with a specific driver.

import "github.com/tracewayapp/go-lightning/lit"

type User struct {
    Id        int
    FirstName string
    LastName  string
    Email     string
}

func init() {
    // Register for PostgreSQL
    lit.RegisterModel[User](lit.PostgreSQL)
    // OR Register for MySQL
    lit.RegisterModel[User](lit.MySQL)
}

Placeholder Syntax: PostgreSQL uses $1, $2, $3... placeholders while MySQL uses ? placeholders. The examples below use PostgreSQL syntax.

2. Basic Usage

import (
    "github.com/tracewayapp/go-lightning/lit"
    _ "github.com/jackc/pgx/v5/stdlib"
)

func example(db *sql.DB) {
    // Insert - returns auto-generated ID
    id, _ := lit.Insert(db, &User{FirstName: "Jane", LastName: "Smith"})

    // Select Single
    user, _ := lit.SelectSingle[User](db, "SELECT * FROM users WHERE id = $1", id)

    // Select Multiple
    users, _ := lit.Select[User](db, "SELECT * FROM users WHERE last_name = $1", "Smith")

    // Update
    user.Email = "jane@example.com"
    _ = lit.Update(db, user, "id = $1", user.Id)

    // Delete
    _ = lit.Delete(db, "DELETE FROM users WHERE id = $1", user.Id)
}

3. Working with Transactions

All operations work with both *sql.DB and *sql.Tx:

func exampleWithTx(db *sql.DB) error {
    tx, err := db.Begin()
    if err != nil {
        return err
    }
    defer tx.Rollback()

    // All operations accept tx
    id, err := lit.Insert(tx, &User{FirstName: "John"})
    if err != nil {
        return err
    }

    user, err := lit.SelectSingle[User](tx, "SELECT * FROM users WHERE id = $1", id)
    if err != nil {
        return err
    }

    return tx.Commit()
}

4. UUID Support

For models with string ID fields, use UUID-specific insert functions:

type Product struct {
    Id    string
    Name  string
    Price int
}

func init() {
    lit.RegisterModel[Product](lit.PostgreSQL)
}

func example(db *sql.DB) {
    // Auto-generate UUID
    uuid, _ := lit.InsertUuid(db, &Product{Name: "Widget", Price: 100})

    // Use existing UUID
    product := &Product{Id: "my-custom-uuid", Name: "Gadget", Price: 200}
    _ = lit.InsertExistingUuid(db, product)
}

5. Helper Functions

// JoinForIn - for integer IN clauses
ids := []int{1, 2, 3}
query := fmt.Sprintf("SELECT * FROM users WHERE id IN (%s)", lit.JoinForIn(ids))

// JoinStringForIn - generates driver-appropriate placeholders
// PostgreSQL: $1,$2,$3 (with offset support)
// MySQL: ?,?,?
names := []string{"a", "b", "c"}
placeholders := lit.JoinStringForIn[User](0, names)

// Or specify driver explicitly
placeholders := lit.JoinStringForInWithDriver(lit.PostgreSQL, 0, 3) // "$1,$2,$3"
placeholders := lit.JoinStringForInWithDriver(lit.MySQL, 0, 3)      // "?,?,?"

6. Column Naming

By default, go-lightning converts Go struct field names from CamelCase to snake_case for database column names:

Struct Field	Database Column
Id	id
FirstName	first_name
LastName	last_name
Email	email

Custom Column Names with lit Tags

You can override the default naming by using the lit struct tag:

type User struct {
    Id        int    `lit:"id"`
    FirstName string `lit:"first_name"`
    LastName  string `lit:"surname"`       // Maps to "surname" instead of "last_name"
    Email     string `lit:"email_address"` // Maps to "email_address" instead of "email"
}

The lit tag is used for:

• INSERT queries: Column names in the generated INSERT statement
• UPDATE queries: Column names in the generated UPDATE statement
• SELECT queries: Mapping database columns back to struct fields

Mixing Tagged and Untagged Fields

You can use lit tags on only some fields. Fields without tags use the default snake_case conversion:

type User struct {
    Id          int                       // Uses default: "id"
    FirstName   string `lit:"given_name"` // Uses tag: "given_name"
    LastName    string                    // Uses default: "last_name"
    PhoneNumber string `lit:"phone"`      // Uses tag: "phone"
}

Custom Naming Strategy

For more control over naming conventions, you can implement the DbNamingStrategy interface and use RegisterModelWithNaming:

type MyNamingStrategy struct{}

func (m MyNamingStrategy) GetTableNameFromStructName(name string) string {
    return strings.ToLower(name) // e.g., "User" -> "user"
}

func (m MyNamingStrategy) GetColumnNameFromStructName(name string) string {
    return strings.ToLower(name) // e.g., "FirstName" -> "firstname"
}

func init() {
    lit.RegisterModelWithNaming[User](lit.PostgreSQL, MyNamingStrategy{})
}

Note: The lit tag takes precedence over any naming strategy.

Contributions

We welcome all contributions to the go-lightning project. You can open issues or PR and we will review and promptly merge them.

Roadmap

• Named query parameters
• Add a project homepage
• Add support for composite primary keys
• Escaping SQL keywords for field names and table names
• Add support for ClickHouse - we're not doing this as clickhouse has a driver that is basically already doing this
• Add more examples - the usercrud example is mostly complete - we'll add more if we get a git issue filed to do so
• Add project docs
• Add support for named fields lit:"column_name"

Project Philosophy

• Developer Written: All core logic and architectural decisions were made and implemented by an actual developer.
• AI Assisted Testing: AI was utilized to help generate a comprehensive test suite as well as help out with documentation.

License

MIT

Documentation

Index

• Variables
• func Delete(tx *sql.Tx, query string, args ...any) error
• func GetPointersForColumns[T any](columns []string, fieldMap *FieldMap, t *T) *[]interface{}
• func Insert[T any](tx *sql.Tx, t *T) (int, error)
• func InsertExistingUuid[T any](tx *sql.Tx, t *T) error
• func InsertNative(tx *sql.Tx, query string, args ...any) (int, error)
• func InsertUuid[T any](tx *sql.Tx, t *T) (string, error)
• func JoinForIn(ids []int) string
• func Register[T any](namingStrategy DbNamingStrategy, queryGenerator InsertUpdateQueryGenerator)
• func Select[T any](tx *sql.Tx, query string, args ...any) ([]*T, error)
• func SelectMultipleNative[T any](tx *sql.Tx, mapLine func(*sql.Rows, *T) error, query string, args ...any) ([]*T, error)
• func SelectSingle[T any](tx *sql.Tx, query string, args ...any) (*T, error)
• func SelectSingleNative[T any](tx *sql.Tx, mapLine func(*sql.Rows, *T) error, query string, args ...any) (*T, error)
• func Update[T any](tx *sql.Tx, t *T, where string, args ...any) error
• func UpdateNative(tx *sql.Tx, query string, args ...any) error
• func ValidateColumns[T any](columns []string, fieldMap *FieldMap) error
• type DbNamingStrategy
• type DefaultDbNamingStrategy
  • func (d DefaultDbNamingStrategy) GetColumnNameFromStructName(input string) string
  • func (d DefaultDbNamingStrategy) GetTableNameFromStructName(input string) string
• type FieldMap
  • func GetFieldMap(t reflect.Type) (*FieldMap, error)
• type InsertUpdateQueryGenerator

Variables

var StructToFieldMap = make(map[reflect.Type]*FieldMap)

Functions

func Delete

func Delete(tx *sql.Tx, query string, args ...any) error

func GetPointersForColumns

func GetPointersForColumns[T any](columns []string, fieldMap *FieldMap, t *T) *[]interface{}

func Insert

func Insert[T any](tx *sql.Tx, t *T) (int, error)

func InsertExistingUuid

func InsertExistingUuid[T any](tx *sql.Tx, t *T) error

func InsertNative

func InsertNative(tx *sql.Tx, query string, args ...any) (int, error)

func InsertUuid

func InsertUuid[T any](tx *sql.Tx, t *T) (string, error)

func JoinForIn

func JoinForIn(ids []int) string

func Register

func Register[T any](namingStrategy DbNamingStrategy, queryGenerator InsertUpdateQueryGenerator)

func Select

func Select[T any](tx *sql.Tx, query string, args ...any) ([]*T, error)

func SelectMultipleNative

func SelectMultipleNative[T any](tx *sql.Tx, mapLine func(*sql.Rows, *T) error, query string, args ...any) ([]*T, error)

func SelectSingle

func SelectSingle[T any](tx *sql.Tx, query string, args ...any) (*T, error)

func SelectSingleNative

func SelectSingleNative[T any](tx *sql.Tx, mapLine func(*sql.Rows, *T) error, query string, args ...any) (*T, error)

func Update

func Update[T any](tx *sql.Tx, t *T, where string, args ...any) error

func UpdateNative

func UpdateNative(tx *sql.Tx, query string, args ...any) error

func ValidateColumns

func ValidateColumns[T any](columns []string, fieldMap *FieldMap) error

Types

type DbNamingStrategy

type DbNamingStrategy interface {
	GetTableNameFromStructName(string) string
	GetColumnNameFromStructName(string) string
}

type DefaultDbNamingStrategy

type DefaultDbNamingStrategy struct{}

func (DefaultDbNamingStrategy) GetColumnNameFromStructName

func (d DefaultDbNamingStrategy) GetColumnNameFromStructName(input string) string

func (DefaultDbNamingStrategy) GetTableNameFromStructName

func (d DefaultDbNamingStrategy) GetTableNameFromStructName(input string) string

type FieldMap

type FieldMap struct {
	ColumnsMap map[string]int
	ColumnKeys []string
	HasIntId   bool

	InsertQuery   string
	UpdateQuery   string
	InsertColumns []string
}

func GetFieldMap

func GetFieldMap(t reflect.Type) (*FieldMap, error)

type InsertUpdateQueryGenerator

type InsertUpdateQueryGenerator interface {
	GenerateInsertQuery(tableName string, columnKeys []string, hasIntId bool) (string, []string)
	GenerateUpdateQuery(tableName string, columnKeys []string) string
}