Help us shape the future of Go! Take the 2026 Go Developer Survey

rain

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package rain provides the main entry point and typed SQL builders for Rain ORM.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNestedTxControlNotAllowed = errors.New("rain: nested RunInTx callbacks cannot call Commit or Rollback directly")

ErrNestedTxControlNotAllowed is returned when nested callbacks attempt to commit or roll back the outer transaction directly.

View Source 
var ErrNestedTxNotSupported = errors.New("rain: nested transactions are not supported by this dialect")

ErrNestedTxNotSupported is returned when nested transactions are requested on a dialect without savepoint support.

View Source 
var ErrNoConnection = errors.New("rain: no database connection configured")

ErrNoConnection is returned when execution is requested without a live database handle.

View Source 
var ErrPrepareNotSupported = errors.New("rain: query runner does not support prepared statements")

ErrPrepareNotSupported is returned when the current query runner cannot prepare statements.

View Source 
var ErrPreparedArgsRequired = errors.New("rain: query contains named placeholders; call Prepare and execute with PreparedArgs")

ErrPreparedArgsRequired is returned when a query with named placeholders is executed without prepared binding.

Functions

func BindModel 

func BindModel[T any](table schema.TableReference) error

BindModel validates a model type against a table and caches the result. Deprecated: use BindTableModel for strict table-backed read/write models.

func BindTableModel 

func BindTableModel[T any](table schema.TableReference) error

BindTableModel validates a full table-backed read/write model type against a table and caches the result.

func MustBindModel 

func MustBindModel[T any](table schema.TableReference)

MustBindModel validates a model type against a table and panics on error. Deprecated: use MustBindTableModel for strict table-backed read/write models.

func MustBindTableModel 

func MustBindTableModel[T any](table schema.TableReference)

MustBindTableModel validates a full table-backed read/write model type and panics on error.

Types

type DB 

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

DB represents a database connection pool.

func Open 

func Open(driver, dsn string) (*DB, error)

Open creates a database handle for the selected dialect.

func OpenDialect 

func OpenDialect(driver string) (*DB, error)

OpenDialect creates a dialect-only handle that can compile SQL without a live database connection.

func WithReplicas 

func WithReplicas(primary *DB, replicas []*DB, selector ReplicaSelector) (*DB, error)

WithReplicas returns a DB handle that routes SELECT queries to read replicas while keeping writes, raw SQL, and transactions on the primary handle.

func (*DB) AddConstraintSQL 

func (db *DB) AddConstraintSQL(table schema.TableReference, constraintName string) (string, error)

AddConstraintSQL compiles one ALTER TABLE ... ADD ... statement for a named table constraint.

func (*DB) AddForeignKeySQL 

func (db *DB) AddForeignKeySQL(table schema.TableReference, foreignKeyName string) (string, error)

AddForeignKeySQL compiles one ALTER TABLE ... ADD ... statement for a named foreign key.

func (*DB) Begin 

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

Begin starts a new transaction.

func (*DB) Close 

func (db *DB) Close() error

Close closes the database connection.

func (*DB) ColumnDefaultSQL 

func (db *DB) ColumnDefaultSQL(table schema.TableReference, columnName string) (string, error)

ColumnDefaultSQL renders one column default expression for snapshotting and migration checks.

func (*DB) ColumnDefinitionSQL 

func (db *DB) ColumnDefinitionSQL(table schema.TableReference, columnName string) (string, error)

ColumnDefinitionSQL compiles one column definition without the ALTER TABLE wrapper.

func (*DB) CreateIndexesSQL 

func (db *DB) CreateIndexesSQL(table schema.TableReference) ([]string, error)

CreateIndexesSQL compiles schema index metadata into CREATE INDEX statements.

func (*DB) CreateTableSQL 

func (db *DB) CreateTableSQL(table schema.TableReference) (string, error)

CreateTableSQL compiles a typed schema definition into a CREATE TABLE statement.

func (*DB) Delete 

func (db *DB) Delete() *DeleteQuery

Delete starts a typed DELETE query builder.

func (*DB) Dialect 

func (db *DB) Dialect() dialect.Dialect

Dialect returns the configured SQL dialect.

func (*DB) Exec 

func (db *DB) Exec(ctx context.Context, query string, args ...any) (sql.Result, error)

Exec executes raw SQL against the database.

func (*DB) Insert 

func (db *DB) Insert() *InsertQuery

Insert starts a typed INSERT query builder.

func (*DB) InvalidateQueryCache 

func (db *DB) InvalidateQueryCache(ctx context.Context, tags ...string) error

InvalidateQueryCache removes cached query entries associated with any provided tag.

func (*DB) Primary 

func (db *DB) Primary() *DB

Primary returns a DB view that forces reads to use the primary handle.

func (*DB) Query 

func (db *DB) Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)

Query executes a SQL query and returns rows.

func (*DB) QueryRow 

func (db *DB) QueryRow(ctx context.Context, query string, args ...any) *sql.Row

QueryRow executes a query that returns a single row.

func (*DB) RunInTx 

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

RunInTx executes fn in a transaction, rolling back on error and committing on success.

func (*DB) Select 

func (db *DB) Select() *SelectQuery

Select starts a typed SELECT query builder.

func (*DB) Update 

func (db *DB) Update() *UpdateQuery

Update starts a typed UPDATE query builder.

func (*DB) WithQueryCache 

func (db *DB) WithQueryCache(cache QueryCache) *DB

WithQueryCache sets the shared SELECT query cache backend on DB.

type DeleteQuery 

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

DeleteQuery builds typed DELETE statements.

func (*DeleteQuery) Exec 

func (q *DeleteQuery) Exec(ctx context.Context) (sql.Result, error)

Exec executes the DELETE query.

func (*DeleteQuery) Returning 

func (q *DeleteQuery) Returning(exprs ...schema.Expression) *DeleteQuery

Returning adds RETURNING expressions when supported by the dialect.

func (*DeleteQuery) Scan 

func (q *DeleteQuery) Scan(ctx context.Context, dest any) error

Scan executes a DELETE ... RETURNING query and scans results into dest.

func (*DeleteQuery) Table 

func (q *DeleteQuery) Table(table schema.TableReference) *DeleteQuery

Table sets the DELETE target table.

func (*DeleteQuery) ToSQL 

func (q *DeleteQuery) ToSQL() (string, []any, error)

ToSQL compiles the delete into SQL and args.

func (*DeleteQuery) Unbounded 

func (q *DeleteQuery) Unbounded() *DeleteQuery

Unbounded allows DELETE without a WHERE clause.

func (*DeleteQuery) Where 

func (q *DeleteQuery) Where(predicate schema.Predicate) *DeleteQuery

Where appends a WHERE predicate joined with AND.

type InsertConflictBuilder 

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

InsertConflictBuilder configures conflict behavior for INSERT statements.

func (*InsertConflictBuilder) DoNothing 

func (b *InsertConflictBuilder) DoNothing() *InsertQuery

DoNothing configures ON CONFLICT ... DO NOTHING.

func (*InsertConflictBuilder) DoUpdateSet 

func (b *InsertConflictBuilder) DoUpdateSet(columns ...schema.ColumnReference) *InsertQuery

DoUpdateSet configures ON CONFLICT ... DO UPDATE SET using EXCLUDED values.

type InsertQuery 

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

InsertQuery builds typed INSERT statements.

func (*InsertQuery) Exec 

func (q *InsertQuery) Exec(ctx context.Context) (sql.Result, error)

Exec executes the INSERT query.

func (*InsertQuery) Model 

func (q *InsertQuery) Model(model any) *InsertQuery

Model sets a struct payload for the insert. Plain fields are treated as explicit values, including zero values. Nil pointers are omitted, and rain.Set[T]{Valid:false} omits a value so schema defaults can apply.

func (*InsertQuery) Models 

func (q *InsertQuery) Models(models any) *InsertQuery

Models sets multiple struct payloads for a bulk insert.

func (*InsertQuery) OnConflict 

func (q *InsertQuery) OnConflict(columns ...schema.ColumnReference) *InsertConflictBuilder

OnConflict starts an upsert clause for PostgreSQL and SQLite dialects.

func (*InsertQuery) Returning 

func (q *InsertQuery) Returning(exprs ...schema.Expression) *InsertQuery

Returning adds RETURNING expressions when supported by the dialect.

func (*InsertQuery) Scan 

func (q *InsertQuery) Scan(ctx context.Context, dest any) error

Scan executes an INSERT ... RETURNING query and scans one row into dest.

func (*InsertQuery) Set 

func (q *InsertQuery) Set(column schema.ColumnReference, value any) *InsertQuery

Set adds an explicit column assignment.

func (*InsertQuery) Table 

func (q *InsertQuery) Table(table schema.TableReference) *InsertQuery

Table sets the INSERT target table.

func (*InsertQuery) ToSQL 

func (q *InsertQuery) ToSQL() (string, []any, error)

ToSQL compiles the insert into SQL and args.

func (*InsertQuery) Values 

func (q *InsertQuery) Values(rows ...map[schema.ColumnReference]any) *InsertQuery

Values appends explicit row value sets for a bulk insert.

type JSON 

type JSON[T any] struct {
	V T
}

JSON wraps a typed Go value for JSON/JSONB columns.

func (*JSON[T]) Scan 

func (j *JSON[T]) Scan(src any) error

Scan implements sql.Scanner.

func (JSON[T]) Value 

func (j JSON[T]) Value() (driver.Value, error)

Value implements driver.Valuer.

type MemoryQueryCache 

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

MemoryQueryCache is an in-memory QueryCache backend for local use and tests.

func NewMemoryQueryCache 

func NewMemoryQueryCache() *MemoryQueryCache

NewMemoryQueryCache creates a new in-memory query cache.

func (*MemoryQueryCache) Get 

func (c *MemoryQueryCache) Get(_ context.Context, key string) ([]byte, bool, error)

func (*MemoryQueryCache) InvalidateTags 

func (c *MemoryQueryCache) InvalidateTags(_ context.Context, tags ...string) error

func (*MemoryQueryCache) Set 

func (c *MemoryQueryCache) Set(_ context.Context, key string, value []byte, ttl time.Duration, tags []string) error

type PreparedArgs 

type PreparedArgs map[string]any

PreparedArgs provides runtime values for a prepared query's named placeholders.

type PreparedSelectQuery 

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

PreparedSelectQuery is a prepared SELECT query with reusable named argument binding.

func (*PreparedSelectQuery) Close 

func (p *PreparedSelectQuery) Close() error

Close closes all prepared statements.

func (*PreparedSelectQuery) Count 

func (p *PreparedSelectQuery) Count(ctx context.Context, args PreparedArgs) (int64, error)

Count executes the prepared COUNT(*) query.

func (*PreparedSelectQuery) Exists 

func (p *PreparedSelectQuery) Exists(ctx context.Context, args PreparedArgs) (bool, error)

Exists executes the prepared SELECT EXISTS query.

func (*PreparedSelectQuery) Scan 

func (p *PreparedSelectQuery) Scan(ctx context.Context, args PreparedArgs, dest any) error

Scan executes the prepared SELECT query and scans results into dest.

type QueryCache 

type QueryCache interface {
	Get(ctx context.Context, key string) ([]byte, bool, error)
	Set(ctx context.Context, key string, value []byte, ttl time.Duration, tags []string) error
	InvalidateTags(ctx context.Context, tags ...string) error
}

QueryCache is the pluggable backend interface for opt-in SELECT query caching.

type QueryCacheOptions 

type QueryCacheOptions struct {
	TTL       time.Duration
	Tags      []string
	Namespace string
	Key       string
	Bypass    bool
}

QueryCacheOptions configures per-query cache behavior for SELECT helpers.

type ReplicaSelector 

type ReplicaSelector func(replicas []*DB) *DB

ReplicaSelector chooses which read replica should serve a SELECT query.

type SelectQuery 

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

SelectQuery builds typed SELECT statements.

func (*SelectQuery) Cache 

func (q *SelectQuery) Cache(options QueryCacheOptions) *SelectQuery

Cache enables opt-in query caching for this SELECT with TTL and optional metadata. Queries that use WithRelations do not read from or write to the query cache.

func (*SelectQuery) Column 

func (q *SelectQuery) Column(cols ...schema.Expression) *SelectQuery

Column sets the selected expressions.

func (*SelectQuery) Count 

func (q *SelectQuery) Count(ctx context.Context) (int64, error)

Count executes SELECT COUNT(*).

func (*SelectQuery) Distinct 

func (q *SelectQuery) Distinct() *SelectQuery

Distinct marks the SELECT query as DISTINCT.

func (*SelectQuery) Exists 

func (q *SelectQuery) Exists(ctx context.Context) (bool, error)

Exists executes a SELECT EXISTS query.

func (*SelectQuery) GroupBy 

func (q *SelectQuery) GroupBy(exprs ...schema.Expression) *SelectQuery

GroupBy appends GROUP BY expressions.

func (*SelectQuery) Having 

func (q *SelectQuery) Having(predicate schema.Predicate) *SelectQuery

Having appends a HAVING predicate joined with AND.

func (*SelectQuery) Join 

func (q *SelectQuery) Join(table schema.TableReference, on schema.Predicate) *SelectQuery

Join appends an INNER JOIN clause.

func (*SelectQuery) JoinSubquery 

func (q *SelectQuery) JoinSubquery(query *SelectQuery, alias string, on schema.Predicate) *SelectQuery

JoinSubquery appends an INNER JOIN against a subquery source.

func (*SelectQuery) LeftJoin 

func (q *SelectQuery) LeftJoin(table schema.TableReference, on schema.Predicate) *SelectQuery

LeftJoin appends a LEFT JOIN clause.

func (*SelectQuery) LeftJoinSubquery 

func (q *SelectQuery) LeftJoinSubquery(query *SelectQuery, alias string, on schema.Predicate) *SelectQuery

LeftJoinSubquery appends a LEFT JOIN against a subquery source.

func (*SelectQuery) Limit 

func (q *SelectQuery) Limit(limit int) *SelectQuery

Limit sets the LIMIT clause.

func (*SelectQuery) Offset 

func (q *SelectQuery) Offset(offset int) *SelectQuery

Offset sets the OFFSET clause.

func (*SelectQuery) OrderBy 

func (q *SelectQuery) OrderBy(order ...schema.OrderExpr) *SelectQuery

OrderBy appends ORDER BY expressions.

func (*SelectQuery) Prepare 

func (q *SelectQuery) Prepare(ctx context.Context) (*PreparedSelectQuery, error)

Prepare compiles and prepares the SELECT query and derived aggregate statements.

func (*SelectQuery) Scan 

func (q *SelectQuery) Scan(ctx context.Context, dest any) error

Scan executes the SELECT query and scans results into dest.

func (*SelectQuery) Table 

func (q *SelectQuery) Table(table schema.TableReference) *SelectQuery

Table sets the table source for the query.

func (*SelectQuery) TableSubquery 

func (q *SelectQuery) TableSubquery(query *SelectQuery, alias string) *SelectQuery

TableSubquery sets a subquery source for the query's FROM clause.

func (*SelectQuery) ToSQL 

func (q *SelectQuery) ToSQL() (string, []any, error)

ToSQL compiles the query into SQL and args.

func (*SelectQuery) Where 

func (q *SelectQuery) Where(predicate schema.Predicate) *SelectQuery

Where appends a WHERE predicate joined with AND.

func (*SelectQuery) With 

func (q *SelectQuery) With(name string, query *SelectQuery) *SelectQuery

With appends a common table expression definition.

func (*SelectQuery) WithRelations 

func (q *SelectQuery) WithRelations(names ...string) *SelectQuery

WithRelations requests one or more named relations to be loaded after scanning base rows.

type Set 

type Set[T any] struct {
	Value T
	Valid bool
}

Set allows value types to opt into omission semantics during writes.

type Tx 

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

Tx represents a database transaction.

func (*Tx) Commit 

func (tx *Tx) Commit() error

Commit commits the transaction.

func (*Tx) Delete 

func (tx *Tx) Delete() *DeleteQuery

Delete starts a typed DELETE query builder in the transaction.

func (*Tx) Insert 

func (tx *Tx) Insert() *InsertQuery

Insert starts a typed INSERT query builder in the transaction.

func (*Tx) InvalidateQueryCache 

func (tx *Tx) InvalidateQueryCache(ctx context.Context, tags ...string) error

InvalidateQueryCache removes cached query entries associated with any provided tag.

func (*Tx) Rollback 

func (tx *Tx) Rollback() error

Rollback rolls the transaction back.

func (*Tx) RunInTx 

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

RunInTx executes fn in a nested transaction using a savepoint.

func (*Tx) Select 

func (tx *Tx) Select() *SelectQuery

Select starts a typed SELECT query builder in the transaction.

func (*Tx) Update 

func (tx *Tx) Update() *UpdateQuery

Update starts a typed UPDATE query builder in the transaction.

type UpdateQuery 

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

UpdateQuery builds typed UPDATE statements.

func (*UpdateQuery) Exec 

func (q *UpdateQuery) Exec(ctx context.Context) (sql.Result, error)

Exec executes the UPDATE query.

func (*UpdateQuery) Returning 

func (q *UpdateQuery) Returning(exprs ...schema.Expression) *UpdateQuery

Returning adds RETURNING expressions when supported by the dialect.

func (*UpdateQuery) Scan 

func (q *UpdateQuery) Scan(ctx context.Context, dest any) error

Scan executes an UPDATE ... RETURNING query and scans results into dest.

func (*UpdateQuery) Set 

func (q *UpdateQuery) Set(column schema.ColumnReference, value any) *UpdateQuery

Set adds an explicit typed assignment.

func (*UpdateQuery) Table 

func (q *UpdateQuery) Table(table schema.TableReference) *UpdateQuery

Table sets the UPDATE target table.

func (*UpdateQuery) ToSQL 

func (q *UpdateQuery) ToSQL() (string, []any, error)

ToSQL compiles the update into SQL and args.

func (*UpdateQuery) Unbounded 

func (q *UpdateQuery) Unbounded() *UpdateQuery

Unbounded allows UPDATE without a WHERE clause.

func (*UpdateQuery) Where 

func (q *UpdateQuery) Where(predicate schema.Predicate) *UpdateQuery

Where appends a WHERE predicate joined with AND.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.