NLG Database Layer

A shared database layer for NetLife Guru Go database drivers.

Use db as the common query, execution, transaction, dialect SQL, and result-mapping layer behind the NetLife Guru database drivers.

---

About

db is a shared database layer used by NetLife Guru database drivers.

It provides common APIs for querying, executing statements, handling transactions, loading SQL models, working with dialect-specific SQL, and mapping database results into Go structs, maps, or scalar values.

This package is not a standalone database driver and does not open database connections by itself.

Applications should normally use one of the concrete driver packages built on top of this layer.

Usage Model

db sits between application repositories and concrete database drivers.

Application code normally connects through a driver package, while repository code can depend on the shared db.Conn interface.

The mapper package is used by this layer for scanning database rows into structs, maps, and scalar values.

Layer	Package	Purpose
Mapper	github.com/netlifeguru/mapper	Row-to-struct and map scanning
DB	github.com/netlifeguru/db	Shared query and repository API
Driver	driver packages	Real database connections

Driver Packages

Concrete drivers are released as separate packages:

• github.com/netlifeguru/db-mysql
• github.com/netlifeguru/db-postgres
• github.com/netlifeguru/db-scylla

Install a concrete driver package in application projects. The driver will use this shared db layer internally.

Features

• Shared Database Layer: Provides common querying and execution APIs for supported drivers
• Driver-Based Usage: Works through concrete database drivers
• Unified Connection Interface: Uses a common db.Conn interface across drivers
• Typed Query Helpers: Supports helpers such as List, Get, Value, and Maps
• Prepared Query Objects: Supports reusable db.Query values through Raw and query-based helpers
• Dialect SQL Support: Selects SQL automatically from db.DialectSQL based on the active driver
• SQL Model Loading: Loads driver-specific SQL files such as model.sql, model.psql, and model.cql
• Result Mapping: Integrates with github.com/netlifeguru/mapper for scanning rows into structs and maps
• Semantic Exec Helpers: Provides Insert, Update, and Delete as readable wrappers around Exec
• Transaction Support: Supports transactions for drivers that provide transaction behavior
• Scylla Batch Support: Provides shared support for driver-specific batch workflows
• Multi-Driver Applications: Helps applications support multiple database engines with one repository layer
• Standard Go Friendly: Designed around interfaces, structs, generics, context-aware operations, and explicit SQL

Requirements

This package requires Go 1.22 or newer.

• Go: 1.22 or newer
• Shared dependency: github.com/netlifeguru/mapper
• Driver packages: mysql, postgres, and scylla

Example Usage

Application code should normally install and use a concrete driver package.

go get github.com/netlifeguru/db-mysql

Then use the driver together with the shared db package:

import (
"context"

"github.com/netlifeguru/db"
"github.com/netlifeguru/db-mysql"
)

Once a driver creates a connection, repository code can work with the shared db.Conn interface:

func ListUsers(ctx context.Context, conn db.Conn) ([]User, error) {
return db.List[User](ctx, conn, db.Raw(`
		SELECT * FROM users
		ORDER BY created_at DESC
	`))
}

The same repository style can be used with any driver that implements the shared connection interface.

Dialect SQL

For multi-driver applications, db.DialectSQL can hold driver-specific SQL or CQL variants.

type Queries struct {
GetUser db.DialectSQL `json:"GetUser"`
}

Example:

queries := Queries{
GetUser: db.DialectSQL{
Postgres: `SELECT * FROM users WHERE id = $1`,
Mysql:      `SELECT * FROM users WHERE id = ?`,
Scylla:     `SELECT * FROM users WHERE id = ?`,
},
}

The active connection decides which query string is used.

SQL Model Files

The shared db package can load driver-specific SQL or CQL files into typed query models.

Driver	File
MySQL	model.sql
PostgreSQL	model.psql
Scylla	model.cql

This is useful for:

• larger queries
• multi-driver applications
• keeping SQL readable
• separating query text from repository code
• using different SQL syntax per driver
• sharing one Go query model across supported database engines

---

Documentation

Full package documentation, guides, and examples are available at:

https://netlife.guru/docs/go/db

API reference is also available on pkg.go.dev:

https://pkg.go.dev/github.com/netlifeguru/db

---

Notes

• This package is a shared layer and is not normally installed directly by applications.
• Install a concrete driver package to create real database connections.
• Driver packages are released separately: mysql, postgres, and scylla.
• Review package-specific concurrency behavior before using it in highly parallel workloads.
• Check performance characteristics when using this package in latency-sensitive paths.
• See the package documentation and examples for limitations and recommended usage patterns.

---

Versioning

This project follows Semantic Versioning.

See CHANGELOG.md for release history and breaking changes.

---

Contributing

Community contributions, feedback, and improvements are welcome.

Please read CONTRIBUTING.md before submitting pull requests or opening issues.

---

Code of Conduct

This project follows a Code of Conduct.

Please read CODE_OF_CONDUCT.md before contributing or participating in discussions.

---

Author

Created and maintained by NetLife Guru s.r.o.

• Documentation: https://netlife.guru/docs/go/db
• GitHub: https://github.com/netlifeguru
• Contact: info@netlife.guru

---

License

MIT License. See LICENSE.