Mapper

Mapper is a small standalone utility package for scanning database rows into Go structs, maps, or custom row handlers.

You usually do not need to learn it deeply unless you want direct control over row scanning. When using NetLifeGuru database drivers, mapper is already used internally.

It works with any database driver that can be adapted to the mapper.Rows interface.

Note

Mapper is database-agnostic and can be used with different SQL-compatible systems such as MySQL, PostgreSQL, ScyllaDB, CockroachDB, MariaDB, and similar drivers. The package does not depend on a specific database engine; it only needs rows that can be adapted to the mapper.Rows interface. For clarity and consistency, the examples in this documentation use MySQL, but the same mapping concepts apply to other supported database systems.

Features

• Standalone Package: Can be used independently without the NetLifeGuru database layer
• Database Agnostic: Works with any driver that can expose rows through the mapper.Rows interface
• Struct Mapping: Scans database rows directly into Go structs
• Column Name Matching: Maps columns by name instead of relying on scan position
• Tag Support: Uses db tags first, then json tags, and falls back to field names
• Snake Case Fallback: Automatically supports snake_case column names for exported struct fields
• Map Scanning: Scans rows into map[string]any for dynamic use cases
• Custom Mapping: Supports custom row mapping through the ScanMapper interface
• Nullable Value Support: Handles nullable-style structs with fields such as String, Time, Bool, Int64, Float64, and Valid
• Pointer Support: Assigns scanned values into pointer fields when needed
• JSON Field Support: Can assign JSON strings or byte slices into slices and maps
• Typed Row Helpers: Provides helper methods for reading int, int64, string, bool, and time.Time from row maps
• Scan Plan Cache: Caches struct metadata and scan plans for repeated row scanning
• Workspace Pooling: Reuses internal scan workspaces to reduce allocation overhead
• Standard Go Friendly: Designed around simple interfaces, structs, generics, and database/sql-style row behavior

Requirements

This package requires Go 1.22 or newer.

It is designed for modern Go projects and may use language and standard library features introduced in recent Go versions.

• Go: 1.22 or newer
• Dependencies: Standard library only
• Features used: Generics, reflection, concurrency primitives

Quick Example

type User struct {
	ID        string    `db:"id"`
	Name      string    `db:"name"`
	Email     string    `db:"email"`
	Active    bool      `db:"active"`
	CreatedAt time.Time `db:"created_at"`
}

rows, err := db.Query(`
	SELECT *
	FROM users
	ORDER BY created_at DESC
`)

if err != nil {
	return err
}
defer rows.Close()

users, err := mapper.ScanStructSlice[User](rows)
if err != nil {
	return err
}

Main APIs