doc.go

/*
sqlslog is a logger for Go SQL database drivers without modifying existing [*sql.DB] stdlib usage.
sqlslog uses [*slog.Logger] to log SQL database driver operations.

# How to use

	db, logger, err := sqlslog.Open(ctx, "mysql", dsn)

You can also use options to customize the logger's behavior.

[Open] takes [Option] s to customize the logging behavior.
[Option] is created by using functions like [HandlerFunc], [ConnPrepareContext], [StmtQueryContext], etc.

# HandlerFunc / Handler

[HandlerFunc] sets the function to create a [slog.Handler] for the logger.
slogslog provides [NewTextHandler] and [NewJSONHandler] to create a [slog.Handler] for sqlslog.

You can also use your own [slog.Handler] by using [Handler] with your [slog.Handler].
But your own [slog.Handler] should know how to log [LevelTrace] and [LevelVerbose] log levels.
So you should use [sqlslog.ReplaceLevelAttr] with your [slog.Handler].

# Level

sqlslog has 6 log levels: [LevelVerbose], [LevelTrace], [LevelDebug], [LevelInfo], [LevelWarn], and [LevelError].
[LevelDebug], [LevelInfo], [LevelWarn], and [LevelError] are the same as slog's log levels.
[LevelVerbose] and [LevelTrace] are extra log levels for sqlslog.
[LevelVerbose] is the lowest log level, and [LevelTrace] is the second lowest log level.

# Step and Event

A [Step] is a logical operation in the database driver, such as a query, a ping, a prepare, etc.
An [Event] is an event that occurs during a [Step], such as [EventStart], [EventError], and [EventComplete].
A [StepOptions] is a set of options for logging a [Step] and has [EventOptions] for each event.
sqlslog provides a way to customize the log message and log [Level] for each step event.
You can customize them by using functions that take [StepOptions] and return [Option], like [ConnPrepareContext] or [StmtQueryContext].

# DefaultStepEventMsgBuilder

The default step event message builder is [StepEventMsgWithEventName].
You can change the default step event message builder by calling [SetStepEventMsgBuilder].

# Duration

sqlslog measures the duration of each step and logs it.
You can change the duration unit by calling [Duration] function and can change
the key name of the duration by calling [DurationKey] function.

# Tracking ID

sqlslog provides a way to track connections, transactions and statements by using a tracking ID.
Each tracking ID is a unique identifier for a connection, transaction or statement.
Tracking ID key in logs is conn_id, tx_id or stmt_id.
Tracking IDs are generated by the ID generator function. The default ID generator function is [IDGeneratorDefault].
You can change the ID generator function by calling [IDGenerator] with functions created by [RandIntIDGenerator] or
[RandReadIDGenerator] with [IDGenErrorSuppressor].

[*sql.DB]: https://pkg.go.dev/database/sql#DB
[*slog.Logger]: https://pkg.go.dev/log/slog#Logger
[slog.Handler]: https://pkg.go.dev/log/slog#Handler
*/
package sqlslog