dbx

README

dbx – SQL-first Data Access for Go

[2025-07-06] Module path fix: This commit is to force the Go proxy to fetch the correct module path after a case-sensitive update.

A lightweight, opinionated data access layer for Go that keeps SQL front and center while eliminating boilerplate.

Philosophy

• ✅ Raw SQL - You write the SQL, we handle the mapping
• ✅ No ORM - No magic, no hidden queries, no abstraction layers
• ✅ Explicit mapping - Use db:"table.column" tags for clarity
• ✅ Flexible output - Get maps, structs, or JSON as needed
• ✅ Team-friendly - Code that's obvious to any Go developer

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/jfinlinson/dbx"
)

type User struct {
    Users_ID    int    `db:"users.id"`
    Users_Name  string `db:"users.name"`
    Users_Email string `db:"users.email"`
}

func main() {
    ctx := context.Background()
    dbpool, err := pgxpool.New(ctx, "postgres://user:pass@localhost:5432/dbname")
    if err != nil {
        log.Fatal(err)
    }
    defer dbpool.Close()

    // Query into maps (no struct needed)
    rows, err := dbx.QueryMaps(ctx, dbpool, "SELECT * FROM users WHERE email LIKE $1", "%@example.com")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Users: %+v\n", rows)

    // Query into structs
    var users []User
    err = dbx.QueryStructs(ctx, dbpool, "SELECT * FROM users", &users)
    if err != nil {
        log.Fatal(err)
    }

    // Insert a struct
    user := User{Users_Name: "Alice", Users_Email: "alice@example.com"}
    err = dbx.InsertStruct(ctx, dbpool, "users", user)
    if err != nil {
        log.Fatal(err)
    }
}

Features

QueryMaps

Get query results as []map[string]interface{} - perfect for dynamic data, APIs, or when you don't want to define structs.

rows, err := dbx.QueryMaps(ctx, db, "SELECT * FROM users WHERE active = $1", true)

QueryStructs

Map query results into structs using db:"table.column" tags for explicit mapping.

type Invoice struct {
    Invoice_Amount  float64 `db:"invoice.amount"`
    Customer_Email  string  `db:"customer.email"`
}

var invoices []Invoice
err := dbx.QueryStructs(ctx, db, "SELECT invoice.amount, customer.email FROM invoice JOIN customer ON ...", &invoices)

InsertStruct

Insert a struct into a table, automatically mapping fields to columns.

user := User{Users_Name: "Bob", Users_Email: "bob@example.com"}
err := dbx.InsertStruct(ctx, db, "users", user)

QueryJSON

Get query results as JSON bytes - great for APIs.

jsonData, err := dbx.QueryJSON(ctx, db, "SELECT * FROM users")

Design Principles

1. SQL First - You write SQL, we handle the rest
2. Explicit Mapping - Use db:"table.column" tags to make relationships clear
3. No Magic - Everything is visible and debuggable
4. Performance - Built on pgx for maximum PostgreSQL performance
5. Team Clarity - Code that any Go developer can understand immediately

Installation

go get github.com/JoeFinlinson/dbx

License

MIT License - see LICENSE file for details.

Documentation

Overview

Package dbx provides SQL-first data access helpers for Go, built on top of pgx. It eliminates boilerplate while keeping SQL front and center.

Key features:

• QueryMaps: Get results as []map[string]interface{}
• QueryStructs: Map results into structs using db:"table.column" tags
• InsertStruct: Insert structs into tables automatically
• QueryJSON: Get results as JSON bytes

Example:

rows, err := dbx.QueryMaps(ctx, db, "SELECT * FROM users WHERE active = $1", true)
var users []User
err = dbx.QueryStructs(ctx, db, "SELECT * FROM users", &users)
err = dbx.InsertStruct(ctx, db, "users", user)

Index

• func InsertStruct(ctx context.Context, db DB, table string, data any) error
• func QueryJSON(ctx context.Context, db DB, sql string, args ...any) ([]byte, error)
• func QueryStructs(ctx context.Context, db DB, sql string, dest any, args ...any) error
• type DB
• type RowMap
  • func QueryMaps(ctx context.Context, db DB, sql string, args ...any) ([]RowMap, error)

Functions

func InsertStruct

func InsertStruct(ctx context.Context, db DB, table string, data any) error

InsertStruct inserts a struct into the specified table. It uses db:"column" tags to map struct fields to table columns. Fields without db tags or with db:"-" are ignored.

func QueryJSON

func QueryJSON(ctx context.Context, db DB, sql string, args ...any) ([]byte, error)

QueryJSON executes a query and returns results as JSON bytes. This is useful for APIs or when you need JSON output directly.

func QueryStructs

func QueryStructs(ctx context.Context, db DB, sql string, dest any, args ...any) error

QueryStructs executes a query and maps results into the provided struct slice. It uses db:"table.column" tags to map columns to struct fields. The dest parameter must be a pointer to a slice of structs.

Types

type DB

type DB interface {
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
}

DB is an interface that provides the methods needed for database operations

type RowMap

type RowMap map[string]interface{}

RowMap represents a single database row as a map

func QueryMaps

func QueryMaps(ctx context.Context, db DB, sql string, args ...any) ([]RowMap, error)

QueryMaps executes a query and returns results as a slice of maps. Each map represents a row with column names as keys.