Documentation
¶
Index ¶
- func ClearGlobalRegistry()
- type Column
- type ColumnMetadata
- func (cm *ColumnMetadata) Alias() string
- func (cm *ColumnMetadata) All() []string
- func (cm *ColumnMetadata) AllFields(instance any) (columns []string, values []any)
- func (cm *ColumnMetadata) As(alias string) dbtypes.Columns
- func (cm *ColumnMetadata) Col(fieldName string) string
- func (cm *ColumnMetadata) Cols(fieldNames ...string) []string
- func (cm *ColumnMetadata) FieldMap(instance any) map[string]any
- type ColumnRegistry
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClearGlobalRegistry ¶
func ClearGlobalRegistry()
ClearGlobalRegistry clears the global column registry cache. WARNING: Only call this in tests to reset state between test cases.
Types ¶
type Column ¶
type Column struct {
// FieldName is the Go struct field name (e.g., "UserID")
FieldName string
// DBColumn is the raw database column name from the db tag (e.g., "user_id")
DBColumn string
// QuotedColumn is the vendor-specific quoted column name (e.g., `"USER_ID"` for Oracle)
QuotedColumn string
// FieldIndex is the index of this field in the struct (for reflection-based value extraction)
FieldIndex int
// FieldType is the reflect.Type of the struct field
FieldType reflect.Type
}
Column represents metadata for a single database column extracted from a struct field.
type ColumnMetadata ¶
type ColumnMetadata struct {
// TypeName is the name of the struct type (e.g., "User")
TypeName string
// Columns is the ordered list of all columns extracted from the struct
Columns []Column
// contains filtered or unexported fields
}
ColumnMetadata represents cached metadata for a struct type, including all database columns extracted from `db:"column_name"` tags.
This struct is cached per vendor to ensure vendor-specific column quoting (e.g., Oracle reserved words) is applied once at registration time, eliminating per-query reflection overhead.
v2.4 Enhancement: Supports immutable aliasing via As() method for zero-copy table qualification.
func RegisterColumns ¶
func RegisterColumns(vendor string, structPtr any) *ColumnMetadata
RegisterColumns is the main entry point for extracting column metadata from a struct. It lazily parses the struct on first use and caches the result forever.
Parameters:
- vendor: Database vendor name (e.g., "oracle", "postgres")
- structPtr: Pointer to a struct with `db:"column_name"` tags
Returns:
- *ColumnMetadata: Cached column metadata for the struct type
Panics if:
- structPtr is not a pointer to a struct
- No fields with `db` tags are found
- Any db tag contains dangerous SQL characters
Example:
type User struct {
ID int64 `db:"id"`
Name string `db:"name"`
Level string `db:"level"` // Oracle reserved word
}
cols := RegisterColumns(dbtypes.Oracle, &User{})
cols.Get("ID") // Returns: `"ID"` (Oracle, quoted)
cols.Get("Level") // Returns: `"LEVEL"` (Oracle reserved word, quoted)
func (*ColumnMetadata) Alias ¶
func (cm *ColumnMetadata) Alias() string
Alias returns the current table alias, or empty string if unaliased.
Example:
cols.Alias() // ""
cols.As("u").Alias() // "u"
func (*ColumnMetadata) All ¶
func (cm *ColumnMetadata) All() []string
All returns vendor-quoted column names for all columns in the struct, in the order they were declared in the struct definition.
Example (unaliased):
cols := qb.Columns(&User{})
cols.All() // ["id", "name", "email"]
Example (aliased):
u := cols.As("u")
u.All() // ["u.id", "u.name", "u.email"]
func (*ColumnMetadata) AllFields ¶
func (cm *ColumnMetadata) AllFields(instance any) (columns []string, values []any)
AllFields extracts all field values from a struct instance as separate slices. Returns (columns, values) suitable for bulk INSERT/UPDATE operations. Only fields with `db` tags are included. Zero values are included.
Example:
user := User{ID: 123, Name: "Alice", Email: "alice@example.com"}
cols, vals := cols.AllFields(&user)
// cols: ["id", "name", "email"]
// vals: [123, "Alice", "alice@example.com"]
Panics if instance is not a struct or pointer to struct.
func (*ColumnMetadata) As ¶
func (cm *ColumnMetadata) As(alias string) dbtypes.Columns
As returns a new ColumnMetadata instance bound to the specified table alias. The returned instance shares the underlying column metadata (zero-copy). This method is immutable - the original ColumnMetadata instance remains unchanged.
Example:
cols := qb.Columns(&User{})
u := cols.As("u")
p := cols.As("p")
u.Col("ID") // "u.id"
p.Col("ID") // "p.id"
cols.Col("ID") // "id" (original unaffected)
Panics if alias is empty (fail-fast for development-time errors).
func (*ColumnMetadata) Col ¶
func (cm *ColumnMetadata) Col(fieldName string) string
Col retrieves the vendor-quoted column name for the given struct field name. If aliased via As(), returns qualified column (e.g., "u.id").
Example (unaliased):
type User struct {
ID int64 `db:"id"`
Level string `db:"level"` // Oracle reserved word
}
cols := qb.Columns(&User{})
cols.Col("ID") // Returns: "id" (PostgreSQL) or "ID" (Oracle)
cols.Col("Level") // Returns: "level" (PostgreSQL) or "LEVEL" (Oracle, quoted)
Example (aliased):
u := cols.As("u")
u.Col("ID") // Returns: "u.id" (PostgreSQL) or "u.\"ID\"" (Oracle)
u.Col("Level") // Returns: "u.\"LEVEL\"" (Oracle reserved word with table qualification)
Panics if the field name is not found (fail-fast for development-time typos).
func (*ColumnMetadata) Cols ¶
func (cm *ColumnMetadata) Cols(fieldNames ...string) []string
Cols retrieves vendor-quoted column names for multiple struct field names. If aliased, returns qualified columns.
Example (unaliased):
cols := qb.Columns(&User{})
cols.Cols("ID", "Name", "Email") // ["id", "name", "email"]
Example (aliased):
u := cols.As("u")
u.Cols("ID", "Name") // ["u.id", "u.name"]
Panics if any field name is not found (fail-fast).
func (*ColumnMetadata) FieldMap ¶
func (cm *ColumnMetadata) FieldMap(instance any) map[string]any
FieldMap extracts field values from a struct instance into a map. The map keys are vendor-quoted column names (respecting alias if set). Only fields with `db` tags are included. Zero values are included.
Example (unaliased):
user := User{ID: 123, Name: "Alice", Email: "alice@example.com"}
cols.FieldMap(&user)
// Returns: {"id": 123, "name": "Alice", "email": "alice@example.com"}
Example (aliased):
cols.As("u").FieldMap(&user)
// Returns: {"u.id": 123, "u.name": "Alice", "u.email": "alice@example.com"}
Panics if instance is not a struct or pointer to struct.
type ColumnRegistry ¶
type ColumnRegistry struct {
// contains filtered or unexported fields
}
ColumnRegistry maintains a cache of struct column metadata per database vendor. It uses lazy initialization: struct types are parsed on first use and cached forever.
Thread-safety: Uses sync.Map for lock-free reads after first write. Memory overhead: ~1-2KB per registered struct type. Performance: ~2µs first-use parsing, ~50ns cached access.
func (*ColumnRegistry) Clear ¶
func (cr *ColumnRegistry) Clear()
Clear removes all cached metadata (useful for testing). WARNING: Only call this in tests, not production code.
func (*ColumnRegistry) Get ¶
func (cr *ColumnRegistry) Get(vendor string, structPtr any) *ColumnMetadata
Get retrieves column metadata for a struct type, lazily parsing on first use. Subsequent calls with the same type and vendor return the cached metadata.
Source Files