mirror of
https://github.com/DeBrosOfficial/network.git
synced 2026-01-30 14:13:04 +00:00
118 lines
4.4 KiB
Go
118 lines
4.4 KiB
Go
package contracts
|
|
|
|
import (
|
|
"context"
|
|
"database/sql"
|
|
)
|
|
|
|
// DatabaseClient defines the interface for ORM-like database operations.
|
|
// Provides both raw SQL execution and fluent query building capabilities.
|
|
type DatabaseClient interface {
|
|
// Query executes a SELECT query and scans results into dest.
|
|
// dest must be a pointer to a slice of structs or []map[string]any.
|
|
Query(ctx context.Context, dest any, query string, args ...any) error
|
|
|
|
// Exec executes a write statement (INSERT/UPDATE/DELETE) and returns the result.
|
|
Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
|
|
|
|
// FindBy retrieves multiple records matching the criteria.
|
|
// dest must be a pointer to a slice, table is the table name,
|
|
// criteria is a map of column->value filters, and opts customize the query.
|
|
FindBy(ctx context.Context, dest any, table string, criteria map[string]any, opts ...FindOption) error
|
|
|
|
// FindOneBy retrieves a single record matching the criteria.
|
|
// dest must be a pointer to a struct or map.
|
|
FindOneBy(ctx context.Context, dest any, table string, criteria map[string]any, opts ...FindOption) error
|
|
|
|
// Save inserts or updates an entity based on its primary key.
|
|
// If the primary key is zero, performs an INSERT.
|
|
// If the primary key is set, performs an UPDATE.
|
|
Save(ctx context.Context, entity any) error
|
|
|
|
// Remove deletes an entity by its primary key.
|
|
Remove(ctx context.Context, entity any) error
|
|
|
|
// Repository returns a generic repository for a table.
|
|
// Return type is any to avoid exposing generic type parameters in the interface.
|
|
Repository(table string) any
|
|
|
|
// CreateQueryBuilder creates a fluent query builder for advanced queries.
|
|
// Supports joins, where clauses, ordering, grouping, and pagination.
|
|
CreateQueryBuilder(table string) QueryBuilder
|
|
|
|
// Tx executes a function within a database transaction.
|
|
// If fn returns an error, the transaction is rolled back.
|
|
// Otherwise, it is committed.
|
|
Tx(ctx context.Context, fn func(tx DatabaseTransaction) error) error
|
|
}
|
|
|
|
// DatabaseTransaction provides database operations within a transaction context.
|
|
type DatabaseTransaction interface {
|
|
// Query executes a SELECT query within the transaction.
|
|
Query(ctx context.Context, dest any, query string, args ...any) error
|
|
|
|
// Exec executes a write statement within the transaction.
|
|
Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
|
|
|
|
// CreateQueryBuilder creates a query builder that executes within the transaction.
|
|
CreateQueryBuilder(table string) QueryBuilder
|
|
|
|
// Save inserts or updates an entity within the transaction.
|
|
Save(ctx context.Context, entity any) error
|
|
|
|
// Remove deletes an entity within the transaction.
|
|
Remove(ctx context.Context, entity any) error
|
|
}
|
|
|
|
// QueryBuilder provides a fluent interface for building SQL queries.
|
|
type QueryBuilder interface {
|
|
// Select specifies which columns to retrieve (default: *).
|
|
Select(cols ...string) QueryBuilder
|
|
|
|
// Alias sets a table alias for the query.
|
|
Alias(alias string) QueryBuilder
|
|
|
|
// Where adds a WHERE condition (same as AndWhere).
|
|
Where(expr string, args ...any) QueryBuilder
|
|
|
|
// AndWhere adds a WHERE condition with AND conjunction.
|
|
AndWhere(expr string, args ...any) QueryBuilder
|
|
|
|
// OrWhere adds a WHERE condition with OR conjunction.
|
|
OrWhere(expr string, args ...any) QueryBuilder
|
|
|
|
// InnerJoin adds an INNER JOIN clause.
|
|
InnerJoin(table string, on string) QueryBuilder
|
|
|
|
// LeftJoin adds a LEFT JOIN clause.
|
|
LeftJoin(table string, on string) QueryBuilder
|
|
|
|
// Join adds a JOIN clause (default join type).
|
|
Join(table string, on string) QueryBuilder
|
|
|
|
// GroupBy adds a GROUP BY clause.
|
|
GroupBy(cols ...string) QueryBuilder
|
|
|
|
// OrderBy adds an ORDER BY clause.
|
|
// Supports expressions like "name ASC", "created_at DESC".
|
|
OrderBy(exprs ...string) QueryBuilder
|
|
|
|
// Limit sets the maximum number of rows to return.
|
|
Limit(n int) QueryBuilder
|
|
|
|
// Offset sets the number of rows to skip.
|
|
Offset(n int) QueryBuilder
|
|
|
|
// Build constructs the final SQL query and returns it with positional arguments.
|
|
Build() (query string, args []any)
|
|
|
|
// GetMany executes the query and scans results into dest (pointer to slice).
|
|
GetMany(ctx context.Context, dest any) error
|
|
|
|
// GetOne executes the query with LIMIT 1 and scans into dest (pointer to struct/map).
|
|
GetOne(ctx context.Context, dest any) error
|
|
}
|
|
|
|
// FindOption is a function that configures a FindBy/FindOneBy query.
|
|
type FindOption func(q QueryBuilder)
|