runtime

Documentation

Index

• type DB
  • func NewDB(rawDB *sql.DB, dialect Dialect, opts ...Option) *DB
  • func (db *DB) Close() error
  • func (db *DB) Dialect() Dialect
  • func (db *DB) Executor() Executor
  • func (db *DB) RawDB() *sql.DB
  • func (db *DB) Tx(ctx context.Context, fn func(tx *Tx) error) error
  • func (db *DB) TxWithOptions(ctx context.Context, opts *sql.TxOptions, fn func(tx *Tx) error) error
• type DBError
• type Dialect
• type Executor
• type Feature
• type LogLevel
• type Logger
• type Option
  • func WithLogger(l Logger) Option
• type Tx
  • func (tx *Tx) Commit() error
  • func (tx *Tx) Dialect() Dialect
  • func (tx *Tx) Executor() Executor
  • func (tx *Tx) Rollback() error

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB wraps a database connection with ORM-specific functionality.

func NewDB

func NewDB(rawDB *sql.DB, dialect Dialect, opts ...Option) *DB

NewDB creates a new DB instance from a *sql.DB connection.

func (*DB) Close

func (db *DB) Close() error

Close closes the underlying database connection.

func (*DB) Dialect

func (db *DB) Dialect() Dialect

Dialect returns the database dialect.

func (*DB) Executor

func (db *DB) Executor() Executor

Executor returns the underlying executor.

func (*DB) RawDB

func (db *DB) RawDB() *sql.DB

RawDB returns the underlying *sql.DB.

func (*DB) Tx

func (db *DB) Tx(ctx context.Context, fn func(tx *Tx) error) error

Tx executes a function within a database transaction. If the function returns an error, the transaction is rolled back. Otherwise, the transaction is committed.

func (*DB) TxWithOptions

func (db *DB) TxWithOptions(ctx context.Context, opts *sql.TxOptions, fn func(tx *Tx) error) error

TxWithOptions executes a function within a transaction with specific options.

type DBError

type DBError = gcoerr.DBError

DBError is a type alias for the classified database error from the errors package. It carries an ErrorCode, message, optional detail/meta, and the original cause.

type Dialect

type Dialect interface {
	// Name returns the dialect name (e.g., "postgresql", "mysql", "sqlite").
	Name() string

	// Placeholder returns the parameter placeholder for the nth parameter (1-based).
	// PostgreSQL: $1, $2, ...
	// MySQL/SQLite: ?
	Placeholder(n int) string

	// QuoteIdent quotes one or more identifier parts.
	// e.g., QuoteIdent("public", "users") → "public"."users" (PostgreSQL)
	QuoteIdent(parts ...string) string

	// SupportsReturning indicates if the dialect supports RETURNING clause.
	SupportsReturning() bool

	// SupportsSchemas indicates if the dialect supports database schemas/namespaces.
	SupportsSchemas() bool

	// RewriteLimitOffset rewrites LIMIT/OFFSET for the dialect.
	RewriteLimitOffset(limit, offset *int) string

	// ClassifyError maps a raw database error to a structured DBError.
	// Returns nil when the error is not recognized by this dialect.
	ClassifyError(err error) *DBError

	// TypeMapping returns the SQL type for a schema type name.
	TypeMapping(schemaType string, isOptional bool) string

	// DefaultValueExpression returns the SQL expression for a default value.
	DefaultValueExpression(funcName string, args []string) string

	// SupportsFeature checks if a specific feature is supported.
	SupportsFeature(feature Feature) bool
}

Dialect abstracts database-specific SQL differences.

type Executor

type Executor interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Executor is the minimal database execution interface. Both DB and Tx implement this interface.

type Feature

type Feature int

Feature represents a database feature that may vary across dialects.

const (
	FeatureReturning Feature = iota
	FeatureSchemas
	FeatureJSON
	FeatureUUID
	FeatureArrays
	FeatureEnumType
	FeatureCascadeDelete
	FeatureSerialType
	FeatureIdentityColumn
	FeatureUpsert
	FeaturePartialIndex
)

type LogLevel

type LogLevel int

LogLevel represents the severity of a log message.

const (
	LogLevelDebug LogLevel = iota
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

type Logger

type Logger interface {
	Log(ctx context.Context, level LogLevel, msg string, args ...any)
}

Logger defines the interface for structured logging within the ORM.

type Option

type Option func(*DB)

Option configures a DB instance.

func WithLogger

func WithLogger(l Logger) Option

WithLogger sets the logger for the DB.

type Tx

type Tx struct {
	// contains filtered or unexported fields
}

Tx wraps a database transaction with ORM-specific functionality.

func (*Tx) Commit

func (tx *Tx) Commit() error

Commit commits the transaction.

func (*Tx) Dialect

func (tx *Tx) Dialect() Dialect

Dialect returns the database dialect.

func (*Tx) Executor

func (tx *Tx) Executor() Executor

Executor returns the transaction executor.

func (*Tx) Rollback

func (tx *Tx) Rollback() error

Rollback rolls back the transaction.