execution

Documentation

Overview

Package execution provides abstractions for executing database operations.

Package execution provides abstractions for executing database operations.

Index

• Variables
• type BackendKind
• type Executor
  • func NewExecutor(opts ...ExecutorOption) Executor
  • func NewPureGenericExecutor() Executor
• type ExecutorOption
  • func WithGeneric(gen GenericExecutor) ExecutorOption
  • func WithGorm(gorm GormExecutor) ExecutorOption
  • func WithKind(kind BackendKind) ExecutorOption
  • func WithPG(pg PGExecutor) ExecutorOption
• type GenericExecutor
  • func NewGenericExecutor() GenericExecutor
• type GormExecutor
  • func NewGormExecutor(db *gorm.DB) GormExecutor
• type PGExecutor
  • func NewPGExecutor(pool *pgxpool.Pool) PGExecutor
• type QueryModel
• type SessionConfig

Variables

var (
	// ErrUnsupported é o erro padrão para operações não implementadas
	// pelo GenericExecutor default.
	ErrUnsupported = fmt.Errorf("execution: unsupported generic operation")
)

Types

type BackendKind

type BackendKind string

BackendKind representa o tipo lógico de backend por trás do executor. Isso não precisa necessariamente refletir o driver físico; é uma classificação de "flavor" para consumo de camada superior.

const (
	BackendUnknown  BackendKind = "unknown"
	BackendPostgres BackendKind = "postgres"
	BackendMongo    BackendKind = "mongo"
	BackendRedis    BackendKind = "redis"
	BackendHTTP     BackendKind = "http"
)

type Executor

type Executor interface {
	// Kind retorna o "flavor" principal do backend.
	Kind() BackendKind

	// PG retorna o executor específico de Postgres (se disponível).
	PG() PGExecutor

	// Gorm retorna o executor baseado em GORM (se disponível).
	Gorm() GormExecutor

	// Generic retorna o executor genérico que trabalha com QueryModel.
	Generic() GenericExecutor
}

Executor é a interface unificada que um Store ou Service deve receber.

A ideia do "Dual Mode" é:

• Quando existir um executor nativo (ex: PGExecutor), você usa ele;
• Quando não existir / não fizer sentido, cai para o GenericExecutor.

Isso permite:

• Stores com SQL explícito, forte, rápido (PG);
• Stores polimórficos / experimentais usando QueryModel (Generic);
• Stores ORM-based usando GORM (Gorm).

func NewExecutor

func NewExecutor(opts ...ExecutorOption) Executor

NewExecutor cria um Executor dual-mode.

Exemplo de uso:

ex := NewExecutor(
    WithKind(BackendPostgres),
    WithPG(pgExec),
    WithGorm(gormExec),
    WithGeneric(NewGenericExecutor()),
)

func NewPureGenericExecutor

func NewPureGenericExecutor() Executor

type ExecutorOption

type ExecutorOption func(*executorImpl)

ExecutorOption permite configurar a implementação do Executor sem precisar criar múltiplos construtores.

func WithGeneric

func WithGeneric(gen GenericExecutor) ExecutorOption

WithGeneric define o executor genérico.

func WithGorm

func WithGorm(gorm GormExecutor) ExecutorOption

WithGorm define o executor baseado em GORM.

func WithKind

func WithKind(kind BackendKind) ExecutorOption

WithKind define o tipo principal do backend.

func WithPG

func WithPG(pg PGExecutor) ExecutorOption

WithPG define o executor específico de Postgres.

type GenericExecutor

type GenericExecutor interface {
	Execute(ctx context.Context, qm QueryModel) (any, error)
}

GenericExecutor define o caminho genérico para executar operações baseadas em QueryModel.

Por padrão, a implementação mínima apenas retorna ErrUnsupported. A ideia é você expandir isso conforme for introduzindo backends genéricos (ex: DS remoto via HTTP, ou um router interno).

func NewGenericExecutor

func NewGenericExecutor() GenericExecutor

NewGenericExecutor cria o GenericExecutor padrão.

type GormExecutor

type GormExecutor interface {
	// WithContext retorna um novo executor com o contexto aplicado.
	WithContext(ctx context.Context) GormExecutor

	// Create insere um novo registro.
	Create(value any) GormExecutor

	// Save salva (insert ou update) um registro.
	Save(value any) GormExecutor

	// First retorna o primeiro registro que corresponde às condições.
	First(dest any, conds ...any) GormExecutor

	// Take retorna um registro que corresponde às condições (sem ordenação).
	Take(dest any, conds ...any) GormExecutor

	// Last retorna o último registro que corresponde às condições.
	Last(dest any, conds ...any) GormExecutor

	// Find retorna todos os registros que correspondem às condições.
	Find(dest any, conds ...any) GormExecutor

	// Delete remove registros que correspondem às condições.
	Delete(value any, conds ...any) GormExecutor

	// Model especifica o modelo para operações.
	Model(value any) GormExecutor

	// Table especifica a tabela para operações.
	Table(name string, args ...any) GormExecutor

	// Select especifica campos para consulta.
	Select(query any, args ...any) GormExecutor

	// Where adiciona condições de filtro.
	Where(query any, args ...any) GormExecutor

	// Or adiciona condição OR.
	Or(query any, args ...any) GormExecutor

	// Not adiciona condição NOT.
	Not(query any, args ...any) GormExecutor

	// Order especifica ordenação.
	Order(value any) GormExecutor

	// Limit define limite de registros.
	Limit(limit int) GormExecutor

	// Offset define offset para paginação.
	Offset(offset int) GormExecutor

	// Group especifica GROUP BY.
	Group(name string) GormExecutor

	// Having especifica HAVING.
	Having(query any, args ...any) GormExecutor

	// Joins adiciona JOIN.
	Joins(query string, args ...any) GormExecutor

	// Preload carrega associações.
	Preload(query string, args ...any) GormExecutor

	// Update atualiza uma coluna específica.
	Update(column string, value any) GormExecutor

	// Updates atualiza múltiplas colunas.
	Updates(values any) GormExecutor

	// UpdateColumn atualiza uma coluna sem hooks.
	UpdateColumn(column string, value any) GormExecutor

	// UpdateColumns atualiza múltiplas colunas sem hooks.
	UpdateColumns(values any) GormExecutor

	// Raw executa SQL raw.
	Raw(sql string, values ...any) GormExecutor

	// Exec executa SQL de modificação.
	Exec(sql string, values ...any) GormExecutor

	// Scan escaneia resultado para destino.
	Scan(dest any) GormExecutor

	// Count retorna contagem de registros.
	Count(count *int64) GormExecutor

	// Pluck extrai uma coluna para slice.
	Pluck(column string, dest any) GormExecutor

	// Begin inicia uma transação.
	Begin() GormExecutor

	// Commit confirma a transação.
	Commit() GormExecutor

	// Rollback reverte a transação.
	Rollback() GormExecutor

	// Transaction executa função em transação com commit/rollback automático.
	Transaction(fc func(tx GormExecutor) error) error

	// Session cria nova sessão com configurações.
	Session(config *SessionConfig) GormExecutor

	// Debug ativa modo debug.
	Debug() GormExecutor

	// Unscoped desativa soft delete.
	Unscoped() GormExecutor

	// Error retorna erro da última operação.
	Error() error

	// RowsAffected retorna número de linhas afetadas.
	RowsAffected() int64

	// IsNotFound verifica se o erro é "record not found".
	IsNotFound() bool

	// AutoMigrate executa migração automática.
	AutoMigrate(dst ...any) error
}

GormExecutor encapsula *gorm.DB sem vazar o tipo para consumidores externos. Esta interface expõe apenas operações necessárias de forma controlada.

IMPORTANTE: Esta interface NÃO deve vazar gorm.DB, gorm.Error ou qualquer tipo do pacote gorm para fora do domus.

func NewGormExecutor

func NewGormExecutor(db *gorm.DB) GormExecutor

NewGormExecutor cria um GormExecutor a partir de um *gorm.DB. Esta é a ÚNICA forma de criar um GormExecutor, e deve ser usada apenas dentro do pacote domus (drivers, etc).

type PGExecutor

type PGExecutor interface {
	Exec(ctx context.Context, query string, args ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, query string, args ...any) pgx.Row

	BeginTx(ctx context.Context) (pgx.Tx, error)

	// Pool expõe o *pgxpool.Pool em último caso (ex: uso avançado).
	Pool() *pgxpool.Pool
}

PGExecutor define a interface "de verdade" para trabalhar com Postgres via pgx/pgxpool, no modo nativo.

Essa interface é o que os Stores vão usar para escrever SQL explícito sem conhecer pool/driver interno do DS.

func NewPGExecutor

func NewPGExecutor(pool *pgxpool.Pool) PGExecutor

NewPGExecutor cria um PGExecutor a partir de um *pgxpool.Pool.

type QueryModel

type QueryModel struct {
	// Command identifica a operação e o backend lógico.
	Command string

	// Query carrega o "payload" da operação:
	//   - pode ser string (SQL, JSON, etc.)
	//   - pode ser struct (filtros, projeções, etc.)
	Query any

	// Params são parâmetros posicionais ou extras contextuais.
	Params []any
}

QueryModel é o "modo genérico" de descrever uma operação de dados.

Ele existe para:

• suportar backends não-SQL (mongo, redis, http, etc);
• permitir que agentes/IA gerem operações abstratas;
• habilitar pipelines metaprogramados (ex: Analyzer, Grompt, etc).

Exemplos de Command:

• "pg:exec"
• "pg:query"
• "mongo:find"
• "redis:get"
• "http:post"
• "ds:invoke"

type SessionConfig

type SessionConfig struct {
	DryRun                   bool
	PrepareStmt              bool
	NewDB                    bool
	Initialized              bool
	SkipHooks                bool
	SkipDefaultTransaction   bool
	DisableNestedTransaction bool
	AllowGlobalUpdate        bool
	FullSaveAssociations     bool
	QueryFields              bool
	CreateBatchSize          int
}

SessionConfig contém configurações para Session(). Evita expor gorm.Session diretamente.