// Package sql implements the standard SQL database interface.
package sql

import (
	"context"
	"database/sql"
)

// SQL is a distinct type for SQL statements to prevent accidental
// SQL injection by directly manipulating or concatenating strings.
type SQL string

// Result summarizes an executed SQL command.
type Result = sql.Result

// DB defines the method required for a database pool.
type DB interface {
	Queryer
	Begin(context.Context) (Txer, error)
	BeginFunc(context.Context, func(Txer) error) error
	Close() error
}

// Txer is a database transaction. It implements Queryer, and adds methods
// to Commit or Rollback the transaction. Calling Rollback on a committed
// transaction returns an error and is otherwise a no-op, so a useful idiom
// is to defer a call to Rollback after starting a transaction, and call
// Commit when needed, which will invalidate the Rollback.
type Txer interface {
	Queryer
	Commit(context.Context) error
	Rollback(context.Context) error
}

// Cursor implement an efficient, iterable database result. Typical usage
// is to use an inifinite for loop and exit when Next returns false.
// It must be closed after use. Consult Err to find any error that may
// have caused early exit from the loop.
type Cursor interface {
	Close() error
	Err() error
	Next() bool
	Scan(interface{}) error
}

// Queryer is the common interface to query and execute SQL
// statements.
type Queryer interface {
	Exec(context.Context, SQL, ...interface{}) (Result, error)
	QueryOne(context.Context, interface{}, SQL, ...interface{}) error
	QueryMany(context.Context, interface{}, SQL, ...interface{}) error
	Cursor(context.Context, SQL, ...interface{}) Cursor
}