Overview

The db package is a shared database layer used by NetLifeGuru database drivers.

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

The db package is not a standalone database driver.

You do not normally install and use github.com/netlifeguru/db by itself. To connect to a real database, install one of the supported driver packages.

How It Fits Together

The database stack is split into three layers:

A typical application installs a driver package.

The driver package depends on:

github.com/netlifeguru/db
github.com/netlifeguru/mapper

This means that installing a driver gives you the complete stack needed to connect, query, execute statements, and map results.

Driver-Based Usage

Choose the driver that matches your database:

go get github.com/netlifeguru/db-mysql

go get github.com/netlifeguru/db-postgres

go get github.com/netlifeguru/db-scylla

After installing a driver, you create a connection through that driver.

For example, with MySQL:

conn := mysql.New()

With PostgreSQL:

conn := postgres.New()

With Scylla:

conn := scylla.New()

Each driver implements the shared db.Conn interface, so the rest of your application can use the same db APIs.

Common API Across Drivers

Once a connection is created, the shared API is the same across supported drivers.

For example, list users:

users, err := db.List[User](ctx, conn, `
	SELECT * FROM users
	ORDER BY created_at DESC
`)

Get one user:

user, found, err := db.Get[User](ctx, conn, `
	SELECT * FROM users
	WHERE id = ?
`, id)

Read a scalar value:

total, found, err := db.Value[int64](ctx, conn, `
	SELECT COUNT(*) FROM users
`)

Execute a statement:

result, err := db.Update(ctx, conn, `
	UPDATE users
	SET active = ?
	WHERE id = ?
`, active, id)

The exact SQL placeholder style still depends on the selected driver.

For example:

The db package does not hide SQL differences. It gives you one Go API while keeping SQL explicit.

What DB Provides

The shared db layer provides:

• typed query helpers such as List, Get, Value, and Maps
• query object helpers such as Raw, ListQuery, GetQuery, ValueQuery, and MapsQuery
• execution helpers such as Exec, Insert, Update, and Delete
• dialect SQL helpers for multi-driver applications
• SQL model loading from driver-specific files
• transaction helpers for drivers that support transactions
• context helpers for storing and retrieving a connection
• integration with mapper for struct and map scanning

What DB Does Not Do

The db package is not an ORM.

It does not:

• generate SQL
• define models
• manage migrations
• manage schemas
• infer relationships
• build queries automatically
• hide database-specific behavior

You write SQL explicitly.

The db package focuses on making execution, result mapping, driver selection, and common database workflows consistent.

Driver Differences Still Matter

Even though the Go API is shared, database engines are not identical.

Some behavior is driver-specific:

Shared APIs are documented once in the DB documentation.

Driver-specific differences are documented separately so the same concepts are not repeated across MySQL, PostgreSQL, and Scylla pages.

Recommended Learning Path

Start with installation and one driver-specific getting started page.

Then read the shared query documentation.

Recommended order:

1. Install a driver
2. Create a connection
3. Use db.List, db.Get, db.Value, or db.Maps
4. Use db.Insert, db.Update, and db.Delete
5. Learn dialect SQL and SQL files if your application may support multiple drivers
6. Learn transactions or Scylla batches depending on your selected database

Next Step

Continue with the Installation guide to choose and install a database driver.