REL

https://go-rel.github.io
Admin
REL is a modern, testable, and extendable ORM for Golang, featuring an elegant query builder with...
Tokens:120,702
Snippets:509
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Go-REL

Source: https://go-rel.github.io/introduction

This snippet shows the command to install the Go-REL ORM library using the go get command. It is the standard way to add Go packages to your project.

```go
go get github.com/go-rel/rel

```

--------------------------------

### Install REL CLI

Source: https://go-rel.github.io/migration

Instructions for installing the REL command-line interface using Homebrew or Go.

```shell
brew tap go-rel/tap
brew install rel
```

```shell
go get github.com/go-rel/cmd/rel
```

```shell
go install github.com/go-rel/cmd/rel@latest
```

--------------------------------

### Go: Limit and Offset with REL

Source: https://go-rel.github.io/queries

Shows how to apply `rel.Limit` and `rel.Offset` to control the number of records returned and the starting point of the result set. `Offset` is ignored if `Limit` is not specified. Examples include direct usage and chaining.

```go
var books []Book
err := repo.FindAll(ctx, &books, rel.Limit(10), rel.Offset(20))
```

```go
books := []Book{
    {ID: 1, Title: "REL for dummies"},
}
repo.ExpectFindAll(rel.Limit(10), rel.Offset(20)).Result(books)
```

```go
var books []Book
err := repo.FindAll(ctx, &books, rel.Select().Limit(10).Offset(20))
```

```go
books := []Book{
    {ID: 1, Title: "REL for dummies"},
}
repo.ExpectFindAll(rel.Select().Limit(10).Offset(20)).Result(books)
```

--------------------------------

### REL Migration API

Source: https://go-rel.github.io/migration

Go code example demonstrating how to use the REL Migration API to manually register and run migrations.

```go
package main

import (
    "context"

    "github.com/go-rel/doc/examples/db/migrations"
    "github.com/go-rel/migration"
    "github.com/go-rel/mysql"
    "github.com/go-rel/rel"
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    var (
        ctx  = context.TODO()
        repo = rel.New(mysql.MustOpen("root@(source:3306)/rel_test?charset=utf8&parseTime=True&loc=Local"))
        m    = migration.New(repo)
    )

    // Register migrations
    m.Register(20202806225100, migrations.MigrateCreateTodos, migrations.RollbackCreateTodos)

    // Run migrations
    m.Migrate(ctx)
    // OR:
    // m.Rollback(ctx)
}
```

--------------------------------

### Postgres Adapter Methods

Source: https://go-rel.github.io/reference/adapter-postgres

Defines core methods for the Postgres adapter, including starting transactions, inserting records, and retrieving the adapter's name.

```APIDOC
type Postgres

  - Represents the PostgreSQL adapter for REL.

  Methods:
    func (Postgres) Begin() rel.Transaction
      - Starts a new database transaction.
      - Returns:
        - rel.Transaction: The transaction object.

    func (Postgres) Insert(query rel.Query, value interface{}) error
      - Inserts a single record into the database.
      - Parameters:
        - query: The REL query object.
        - value: The record to insert.
      - Returns:
        - error: An error if the insertion fails.

    func (Postgres) InsertAll(query rel.Query, values []interface{}) error
      - Inserts multiple records into the database.
      - Parameters:
        - query: The REL query object.
        - values: A slice of records to insert.
      - Returns:
        - error: An error if the insertion fails.

    func (Postgres) Name() string
      - Returns the name of the adapter.
      - Returns:
        - string: The adapter name ("postgres").
```

--------------------------------

### Preload Belongs To Association in Go

Source: https://go-rel.github.io/association

Demonstrates how to preload a 'belongs to' association for a struct using the `Preload` method. It shows both the execution example and the corresponding mock setup for testing.

```Go
err := repo.Preload(ctx, &transaction, "buyer")
```

```Go
user := User{ID: 1, Name: "Nabe"}
repo.ExpectPreload("buyer").Result(user)
```

--------------------------------

### Verify REL Installation

Source: https://go-rel.github.io/migration

Command to verify that the REL CLI has been installed correctly.

```shell
rel -version
```

--------------------------------

### REL Import Path Migration (0.7.x vs 0.8.x)

Source: https://go-rel.github.io/changelog/upgrading

Details the migration of the REL library's import path from `github.com/Fs02/rel` to `github.com/go-rel/rel` following a change in the GitHub organization.

```go
import github.com/Fs02/rel
```

```go
import github.com/go-rel/rel
```

--------------------------------

### Document.NewDocument() - Go

Source: https://go-rel.github.io/reference/rel

Creates and returns a new Document instance initialized with zero values. This is useful for creating new records or starting a document from scratch.

```go
func (d Document) NewDocument() *Document
```

--------------------------------

### Go: Starting and Using Transactions with database/sql

Source: https://go-rel.github.io/introduction

Demonstrates the standard pattern for initiating and executing operations within a transaction using Go's built-in database/sql package. It highlights the importance of using the transaction object (tx) for all database calls within the transaction scope and committing or rolling back the transaction.

```go
// start transaction
tx := db.Begin()

// do some database operations in the transaction (use 'tx' from this point, not 'db')
tx.Create(...)

// Or commit the transaction
tx.Commit()

```

--------------------------------

### REL ORM Testability Example

Source: https://go-rel.github.io/introduction

This Go code demonstrates how REL's design facilitates testability by using interfaces for database operations, contrasting it with typical chainable ORM APIs that are harder to mock.

```go
// mockable interface.
type UserRepository interface {
    Find(user *User, id int) error
}

// actual implementation
type userRepository struct {
    db *DB
}

func (ur userRepository) Find(user *User, id int) error {
    return db.Where("id = ?", 1).First(&user)
}

```

--------------------------------

### Mock Insert Operations (reltest)

Source: https://go-rel.github.io/crud

Provides examples for mocking the Insert and InsertAll repository methods using the reltest package. These mocks allow for testing without a live database connection, enabling verification of repository calls with specific arguments or types.

```go
// Mock Insert
repo.ExpectInsert()

// Mock Insert by Record
repo.ExpectInsert().For(&Book{
    Title:    "Rel for dummies",
    Category: "education",
    Author: Author{
        Name: "CZ2I28 Delta",
    },
})

// Mock Insert by Type
repo.ExpectInsert().ForType("main.Book")

// Mock Insert Error
repo.ExpectInsert().ForType("main.Book").Error(errors.New("oops"))

// Mock InsertAll
repo.ExpectInsertAll().ForType("[]main.Book")
```

--------------------------------

### MySQL Adapter Import Path Change

Source: https://go-rel.github.io/changelog/upgrading

Shows the evolution of the MySQL adapter's import path in go-rel from version 0.29.x to 0.30.x, corresponding to its move to a dedicated package.

```go
import "github.com/go-rel/rel/adapter/mysql"
```

```go
import "github.com/go-rel/mysql"
```

--------------------------------

### Mock REL Native SQL Query in Go

Source: https://go-rel.github.io/queries

Provides an example of mocking the repo.Find call for a native SQL query in Go tests using REL, specifying the SQL statement and the expected result.

```go
var book Book
sql := rel.SQL("SELECT id, title, price, orders = (SELECT COUNT(t.id) FROM [transactions] t WHERE t.book_id = b.id) FROM books b where b.id=?", 1)
repo.ExpectFind(sql).Result(book)
```

--------------------------------

### SQLite3 Adapter Import Path Change

Source: https://go-rel.github.io/changelog/upgrading

Illustrates the change in the import path for the SQLite3 adapter between go-rel versions 0.29.x and 0.30.x, reflecting its extraction to a separate repository.

```go
import "github.com/go-rel/rel/adapter/sqlite3"
```

```go
import "github.com/go-rel/sqlite3"
```

--------------------------------

### Preload Multiple Associations in Go

Source: https://go-rel.github.io/association

Shows how to preload multiple associations, including nested ones, in a single call. This example demonstrates preloading a buyer's address for transactions.

```Go
err := repo.Preload(ctx, &transaction, "buyer.address")
```

```Go
userID := 1
addresses := []Address{{ID: 1, City: "Nazarick", UserID: &userID}}
repo.ExpectPreload("buyer.address").Result(addresses)
```

--------------------------------

### Initialize MySQL Adapter

Source: https://go-rel.github.io/reference/adapter-mysql

Demonstrates how to open a MySQL connection using a DSN string and initialize the REL repository with the MySQL adapter. It highlights the requirement for `clientFoundRows=true` for correct update and delete operations.

```go
import (
    "database/sql"
    "github.com/go-rel/rel"
    "github.com/go-rel/mysql"
)

// open mysql connection.
// note: `clientFoundRows=true` is required for update and delete to works correctly.
adapter, err := mysql.Open("root@(127.0.0.1:3306)/rel_test?clientFoundRows=true&charset=utf8&parseTime=True&loc=Local")
if err != nil {
    panic(err)
}
defer adapter.Close()

// initialize REL's repo.
repo := rel.New(adapter)

```

--------------------------------

### Open Postgres Connection with REL

Source: https://go-rel.github.io/reference/adapter-postgres

Demonstrates how to open a PostgreSQL connection using the `postgres.Open` function and initialize REL's repository with the adapter. Includes error handling and deferred closing.

```go
import (
    "database/sql"
    "log"

    "github.com/go-rel/rel"
    "github.com/go-rel/rel/adapter/postgres"
)

func main() {
    // open postgres connection.
    adapter, err := postgres.Open("postgres://postgres@localhost/rel_test?sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    defer adapter.Close()

    // initialize REL's repo.
    repo := rel.New(adapter)

    // ... use repo ...
}
```

--------------------------------

### SQLite3 Adapter Initialization and Usage

Source: https://go-rel.github.io/reference/adapter-sqlite3

Demonstrates how to open a SQLite3 database connection using the go-rel/sqlite3 adapter and initialize the go-rel repository. It includes error handling and resource management.

```go
// open sqlite3 connection.
adapter, err := sqlite3.Open("dev.db")
if err != nil {
    panic(err)
}
defer adapter.Close()

// initialize rel's repo.
repo := rel.New(adapter)

```

--------------------------------

### Association Autosave Feature Explicitly Enabled (0.8.x vs 0.9.x)

Source: https://go-rel.github.io/changelog/upgrading

Explains the change in go-rel's association handling, where autosave functionality for associations now requires explicit enabling via a struct tag (`autosave:"true"`) starting from version 0.9.x.

```go
// User schema.
type User struct {
    ID      int
    Name    string
    Address Address
}
```

```go
// User schema.
type User struct {
    ID      int
    Name    string
    Address Address `autosave:"true"`
}
```

--------------------------------

### Query Builder Initialization and Core Methods

Source: https://go-rel.github.io/reference/rel

Provides functions to initialize and build queries. Includes methods for setting the base table, applying joins, selecting fields, and defining filter conditions.

```APIDOC
func Build(table string, queriers ...Querier) Query
  - Builds a query for a given table using provided queriers.

func From(table string) Query
  - Creates a query starting with a FROM clause for the specified table.

func Join(table string, filter ...FilterQuery) Query
  - Creates a query starting with a JOIN clause for the specified table, optionally with filter conditions.

func JoinAssoc(assoc string, filter ...FilterQuery) Query
  - Creates a query starting with a JOIN clause based on an association field, optionally with filter conditions.

func JoinAssocWith(mode string, assoc string, filter ...FilterQuery) Query
  - Creates a query starting with a JOIN clause using a custom mode and association field, optionally with filter conditions.

func JoinOn(table string, from string, to string, filter ...FilterQuery) Query
  - Creates a query starting with a JOIN clause on specified 'from' and 'to' fields, optionally with filter conditions.

func JoinWith(mode string, table string, from string, to string, filter ...FilterQuery) Query
  - Creates a query starting with a JOIN clause using a custom mode and specified 'from' and 'to' fields, optionally with filter conditions.

func Joinf(expr string, args ...any) Query
  - Creates a query starting with a JOIN clause using a raw SQL expression.

func Select(fields ...string) Query
  - Creates a query starting with a SELECT clause, specifying the fields to retrieve.

func UsePrimary() Query
  - Sets the query to use the primary database.

func Where(filters ...FilterQuery) Query
  - Creates a query starting with a WHERE clause, applying the specified filter conditions.
```

--------------------------------

### Collection Get Method

Source: https://go-rel.github.io/reference/rel

The Get method retrieves a document from the collection at a specified index. It returns a pointer to the Document.

```go
func (c Collection) Get(index int) *Document
```

--------------------------------

### Repository Mock Initialization and Core Methods

Source: https://go-rel.github.io/reference/reltest

Details the initialization of a mock Repository and its fundamental methods for interacting with data. This includes creating new repositories, accessing the underlying adapter, and performing common database operations like aggregation, counting, and deletion.

```go
type Repository struct {
    // contains filtered or unexported fields
}

func New() *Repository {

}

```

```go
func (r *Repository) Adapter(ctx context.Context) rel.Adapter {

}

```

```go
func (r *Repository) Aggregate(ctx context.Context, query rel.Query, aggregate string, field string) (int, error) {

}

```

```go
func (r *Repository) Count(ctx context.Context, collection string, queriers ...rel.Querier) (int, error) {

}

```

```go
func (r *Repository) Delete(ctx context.Context, entity any, options ...rel.Mutator) error {

}

```

```go
func (r *Repository) DeleteAll(ctx context.Context, entities any) error {

}

```

```go
func (r *Repository) DeleteAny(ctx context.Context, query rel.Query) (int, error) {

}

```

```go
func (r *Repository) Exec(ctx context.Context, statement string, args ...any) (int, int, error) {

}

```

--------------------------------

### Collection Truncate Function

Source: https://go-rel.github.io/reference/rel

Truncates a collection by specifying start and end indices. This function is part of the Collection type.

```go
func (c Collection) Truncate(i, j int)
```

--------------------------------

### MySQL Adapter API Reference

Source: https://go-rel.github.io/reference/adapter-mysql

Provides API documentation for the MySQL adapter in go-rel. It includes details on constants, functions for opening connections, and type definitions for the adapter itself and its quoting mechanisms.

```APIDOC
Package mysql

`import "github.com/go-rel/mysql"`

Overview:
Package mysql wraps mysql driver as an adapter for REL.

Constants:
Name string = "mysql"
  Name of database type this adapter implements.

Functions:
func MustOpen(dsn string) rel.Adapter
  MustOpen mysql connection using dsn.

func New(database *db.DB) rel.Adapter
  New mysql adapter using existing connection. Existing connection needs to be created with `clientFoundRows=true` options for update and delete to works correctly.

func Open(dsn string) (rel.Adapter, error)
  Open mysql connection using dsn.

Types:
type MySQL struct {
    sql.SQL
}
  MySQL adapter.
  Methods:
  func (MySQL) Name() string
    Name of database adapter.

type Quote struct{}
  Quote MySQL identifiers and literals.
  Methods:
  func (Quote) ID(name string) string
    Quote MySQL identifiers.
  func (Quote) Value(value string) string
    Quote MySQL literals.

type ValueConvert struct{}
  ValueConvert converts values for MySQL.
  Methods:
  func (ValueConvert) ConvertValue(value interface{}) interface{}
    ConvertValue converts value for MySQL.

```

--------------------------------

### Repository Constructor

Source: https://go-rel.github.io/reference/rel

Function to create a new repository instance. It requires an Adapter to be provided, which defines the underlying database connection or driver.

```go
func New(adapter Adapter) Repository {
    // Implementation details omitted
    return nil // Placeholder
}
```

--------------------------------

### Collection Slice Method

Source: https://go-rel.github.io/reference/rel

The Slice method returns a new Collection that represents a sub-slice of the original collection, defined by the start (i) and end (j) indices.

```go
func (c Collection) Slice(i, j int) *Collection
```

--------------------------------

### ConstraintType Enum and String Method

Source: https://go-rel.github.io/reference/rel

Defines an enumeration for constraint error types (CheckConstraint, NotNullConstraint, UniqueConstraint, PrimaryKeyConstraint, ForeignKeyConstraint) and a method to get their string representation.

```go
type ConstraintType int8

const (
    // CheckConstraint error type.
    CheckConstraint ConstraintType = iota
    // NotNullConstraint error type.1
    NotNullConstraint
    // UniqueConstraint error type.1
    UniqueConstraint
    // PrimaryKeyConstraint error type.1
    PrimaryKeyConstraint
    // ForeignKeyConstraint error type.1
    ForeignKeyConstraint
)

func (ct ConstraintType) String() string
```

--------------------------------

### SQLite3 Adapter API Reference

Source: https://go-rel.github.io/reference/adapter-sqlite3

Provides API documentation for the sqlite3 package, including functions for opening connections and the definition of the SQLite3 adapter type and its methods.

```APIDOC
Package sqlite3

`import "github.com/go-rel/sqlite3"`

Overview:
Package sqlite3 wraps go-sqlite3 driver as an adapter for rel.

Constants:
const Name string = "sqlite3"
  Name of database type this adapter implements.

Functions:

func MustOpen(dsn string) rel.Adapter
  MustOpen sqlite3 connection using dsn.

func New(database *db.DB) rel.Adapter
  New sqlite3 adapter using existing connection.

func Open(dsn string) (rel.Adapter, error)
  Open sqlite3 connection using dsn.

Type: SQLite3

type SQLite3 struct {
    sql.SQL
}
  SQLite3 adapter

Methods:

func (SQLite3) Name() string
  Name of database adapter.

```

--------------------------------

### Join Association with Select in Go

Source: https://go-rel.github.io/association

Demonstrates joining an association and selecting fields from the joined table to load data into the result. This example joins a transaction with its buyer.

```Go
// Select "buyer.*" field tells REL to load the joined table to result as well.
err := repo.FindAll(ctx, &transactions, rel.Select("*", "buyer.*").JoinAssoc("buyer"))
```

```Go
transactions := []Transaction{{ID: 1, BuyerID: 2, Buyer: User{ID: 2, Name: "Nabe"}}}
repo.ExpectFindAll(rel.Select("*", "buyer.*").JoinAssoc("buyer")).Result(transactions)
```

--------------------------------

### Constraint Types and Methods

Source: https://go-rel.github.io/reference/changeset

Defines the Constraint and Constraints types for managing validation rules and error messages. Includes a method to get specific errors based on defined constraints.

```APIDOC
type Constraint struct
    Field string
    Message string
    Code int
    Name string
    Exact bool
    Type rel.ConstraintType

Constraint defines information to infer constraint error, including the field, message, error code, name, exactness, and type of constraint.

type Constraints []Constraint

Constraints is a slice of Constraint.

Methods:
  GetError(err error) error
    Converts an error based on the defined constraints. If the original error is a constraint error and is defined in the constraint list, its message is updated. If it's a constraint error not in the list, it's converted to an unexpected error. Otherwise, the error remains unmodified.
```

```go
type Constraint struct {
    Field   string
    Message string
    Code    int
    Name    string
    Exact   bool
    Type    rel.ConstraintType
}

type Constraints []Constraint

func (constraints Constraints) GetError(err error) error
```

--------------------------------

### Go Migration API Documentation

Source: https://go-rel.github.io/reference/migration

API reference for the go-rel/migration package, detailing the Migration type and its core methods for managing database schema migrations. Includes function signatures, parameter descriptions, and usage context.

```APIDOC
Package migration

import "github.com/go-rel/migration"

// Migration utility that handles migration logic.
type Migration struct {
    // contains filtered or unexported fields
}

// New creates a new migration manager.
// repo: The database repository to use for migration operations.
func New(repo rel.Repository) Migration

// Instrumentation sets an instrumentation function for the migration process.
// instrumenter: The rel.Instrumenter to use for tracking migration events.
func (m *Migration) Instrumentation(instrumenter rel.Instrumenter)

// Migrate applies all registered migrations to the latest schema version.
// ctx: The context for the migration operation.
func (m *Migration) Migrate(ctx context.Context)

// Register registers a new migration step.
// v: The version number of the migration.
// up: A function that applies the schema changes for this migration.
// down: A function that reverts the schema changes for this migration.
func (m *Migration) Register(v int, up func(schema *rel.Schema), down func(schema *rel.Schema))

// Rollback reverts the last applied migration step.
// ctx: The context for the rollback operation.
func (m *Migration) Rollback(ctx context.Context)
```

--------------------------------

### New PrimaryReplica Adapter Constructor

Source: https://go-rel.github.io/reference/adapter-primaryreplica

Constructs a new PrimaryReplica adapter, which manages a primary database connection and optional replica connections. It takes the primary adapter and a variadic list of replica adapters as arguments.

```go
func New(primary rel.Adapter, replicas ...rel.Adapter) rel.Adapter
```

--------------------------------

### Postgres Adapter Import Path Change

Source: https://go-rel.github.io/changelog/upgrading

Details the change in the import path for the Postgres adapter in go-rel between versions 0.29.x and 0.30.x, indicating its relocation to a separate module.

```go
import "github.com/go-rel/rel/adapter/postgres"
```

```go
import "github.com/go-rel/postgres"
```

--------------------------------

### JoinQuery Constructors and Methods

Source: https://go-rel.github.io/reference/rel

Provides constructors for various types of SQL JOIN clauses (INNER, LEFT, RIGHT, FULL) and methods to build and populate the join query.

```APIDOC
JoinQuery:
  NewFullJoin(table string) JoinQuery
    Description: Creates a new FULL OUTER JOIN clause.
    Parameters:
      table: The name of the table to join.
    Returns: A JoinQuery instance.

  NewFullJoinOn(table string, condition string, args ...interface{}) JoinQuery
    Description: Creates a new FULL OUTER JOIN clause with an ON condition.
    Parameters:
      table: The name of the table to join.
      condition: The ON condition string.
      args: Arguments for the ON condition.
    Returns: A JoinQuery instance.

  NewInnerJoin(table string) JoinQuery
    Description: Creates a new INNER JOIN clause.
    Parameters:
      table: The name of the table to join.
    Returns: A JoinQuery instance.

  NewInnerJoinOn(table string, condition string, args ...interface{}) JoinQuery
    Description: Creates a new INNER JOIN clause with an ON condition.
    Parameters:
      table: The name of the table to join.
      condition: The ON condition string.
      args: Arguments for the ON condition.
    Returns: A JoinQuery instance.

  NewJoin(table string) JoinQuery
    Description: Creates a new JOIN clause (defaults to INNER JOIN).
    Parameters:
      table: The name of the table to join.
    Returns: A JoinQuery instance.

  NewJoinAssoc(assoc string) JoinQuery
    Description: Creates a JOIN clause based on an association name.
    Parameters:
      assoc: The name of the association.
    Returns: A JoinQuery instance.

  NewJoinAssocWith(assoc string, alias string) JoinQuery
    Description: Creates a JOIN clause based on an association name with an alias.
    Parameters:
      assoc: The name of the association.
      alias: The alias for the joined table.
    Returns: A JoinQuery instance.

  NewJoinFragment(fragment string) JoinQuery
    Description: Creates a JOIN clause from a raw SQL fragment.
    Parameters:
      fragment: The raw SQL JOIN fragment.
    Returns: A JoinQuery instance.

  NewJoinOn(table string, condition string, args ...interface{}) JoinQuery
    Description: Creates a JOIN clause with an ON condition.
    Parameters:
      table: The name of the table to join.
      condition: The ON condition string.
      args: Arguments for the ON condition.
    Returns: A JoinQuery instance.

  NewJoinWith(table string, alias string) JoinQuery
    Description: Creates a JOIN clause with an alias.
    Parameters:
      table: The name of the table to join.
      alias: The alias for the joined table.
    Returns: A JoinQuery instance.

  NewLeftJoin(table string) JoinQuery
    Description: Creates a new LEFT OUTER JOIN clause.
    Parameters:
      table: The name of the table to join.
    Returns: A JoinQuery instance.

  NewLeftJoinOn(table string, condition string, args ...interface{}) JoinQuery
    Description: Creates a new LEFT OUTER JOIN clause with an ON condition.
    Parameters:
      table: The name of the table to join.
      condition: The ON condition string.
      args: Arguments for the ON condition.
    Returns: A JoinQuery instance.

  NewRightJoin(table string) JoinQuery
    Description: Creates a new RIGHT OUTER JOIN clause.
    Parameters:
      table: The name of the table to join.
    Returns: A JoinQuery instance.

  NewRightJoinOn(table string, condition string, args ...interface{}) JoinQuery
    Description: Creates a new RIGHT OUTER JOIN clause with an ON condition.
    Parameters:
      table: The name of the table to join.
      condition: The ON condition string.
      args: Arguments for the ON condition.
    Returns: A JoinQuery instance.

  (JoinQuery) Build() string
    Description: Builds the SQL JOIN clause string.
    Returns: The SQL JOIN clause.

  (*JoinQuery) Populate(data map[string]interface{}) error
    Description: Populates the JoinQuery with data, likely for mapping results.
    Parameters:
      data: A map containing data to populate the query with.
    Returns: An error if population fails.
```

--------------------------------

### Preload Has Many Association with Condition in Go

Source: https://go-rel.github.io/association

Demonstrates preloading a 'has many' association with a specific condition applied using `where.Eq`. Includes both the query and mock setup.

```Go
err := repo.Preload(ctx, &user, "transactions", where.Eq("status", "paid"))
```

```Go
transactions := []Transaction{
    {ID: 1, Item: "Avarice and Generosity", Status: "paid"},
}
repo.ExpectPreload("transactions", where.Eq("status", "paid")).Result(transactions)
```

--------------------------------

### Go-REL: Basic Database Operations with PostgreSQL

Source: https://go-rel.github.io/basics

Demonstrates core database operations using the go-rel ORM with the PostgreSQL adapter. Includes finding records, preloading associations, and performing updates within transactions. Requires the 'go-rel/postgres' and 'go-rel' packages.

```go
package main

import (
    "context"
    "time"

    "github.com/go-rel/postgres"
    "github.com/go-rel/rel"
    "github.com/go-rel/rel/where"
    _ "github.com/lib/pq"
)

// Author is a model that maps to authors table.
type Author struct {
    ID   int
    Name string
}

// Book is a model that maps to books table.
type Book struct {
    ID        int
    Title     string
    Category  string
    Price     int
    Discount  bool
    Stock     int
    AuthorID  int
    Author    Author
    Publisher string
    CreatedAt time.Time
    UpdatedAt time.Time
}

var dsn = "postgres://postgres@localhost/rel_test?sslmode=disable"

func main() {
    // initialize postgres adapter.
    adapter, _ := postgres.Open(dsn)
    defer adapter.Close()

    // initialize rel's repo.
    repo := rel.New(adapter)

    // run
    Example(context.Background(), repo)
}

// Example is an actual service function that run a complex business package.
// beware: it's actually doing nonsense here.
func Example(ctx context.Context, repo rel.Repository) error {
    var book Book

    // Quickly find a book with id 1 using short alias.
    if err := repo.Find(ctx, &book, where.Eq("id", 1)); err != nil {
        return err
    }

    // Or use chainable query builder.
    query := rel.Select().Where(where.Eq("id", 1)).Limit(1)
    if err := repo.Find(ctx, &book, query); err != nil {
        return err
    }

    // Convenient method to preload Book's Author.
    if err := repo.Preload(ctx, &book, "author"); err != nil {
        return err
    }

    // Performs updates inside a transaction.
    return repo.Transaction(ctx, func(ctx context.Context) error {
        // basic update using struct.
        book.Title = "REL for dummies"
        repo.MustUpdate(ctx, &book)

        // update only specific fields.
        repo.MustUpdate(ctx, &book, rel.Set("discount", false))

        // it even supports atomic inc/dec mutation.
        return repo.Update(ctx, &book, rel.Dec("stock"))
    })
}

```

--------------------------------

### Run REL Migrations

Source: https://go-rel.github.io/migration

Commands to execute database migrations using the REL CLI.

```shell
rel migrate
```

```shell
rel rollback
```

--------------------------------

### Preload Has Many Association in Go

Source: https://go-rel.github.io/association

Shows how to preload a 'has many' association for a struct. Covers the `Preload` call for data retrieval and the mock setup for unit tests.

```Go
err := repo.Preload(ctx, &user, "transactions")
```

```Go
transactions := []Transaction{
    {ID: 1, Item: "Avarice and Generosity", Status: "paid"},
}
repo.ExpectPreload("transactions").Result(transactions)
```

--------------------------------

### Update Association with Autosave in Go

Source: https://go-rel.github.io/association

Illustrates how REL updates associated records when the parent is updated, assuming the association was preloaded and has a non-zero ID. This example updates a user and their address.

```Go
userID := 1
user := User{
    ID:   1,
    Name: "rel",
    // association is loaded when the primary key (id) is not zero.
    Address: Address{
        ID:     1,
        UserID: &userID,
        City:   "Bandung",
    },
}

// Update user record with id 1.
// Update address record with id 1.
err := repo.Update(ctx, &user)
```

```Go
repo.ExpectUpdate().ForType("main.User")
```

--------------------------------

### Postgres New Adapter Function

Source: https://go-rel.github.io/reference/adapter-postgres

Creates a new Postgres adapter instance using an existing `database/sql.DB` connection.

```APIDOC
func New(database *db.DB) rel.Adapter
  - Creates a new postgres adapter using an existing connection.
  - Parameters:
    - database: A pointer to an initialized `database/sql.DB` connection.
  - Returns:
    - rel.Adapter: The initialized Postgres adapter.
```

--------------------------------

### UpdateAll/DeleteAll Return Value Change (0.13.x vs 0.14.x)

Source: https://go-rel.github.io/changelog/upgrading

Documents the modification in go-rel where `UpdateAll` and `DeleteAll` functions began returning the count of affected rows in addition to an error.

```go
// UpdateAll
err := repo.UpdateAll(ctx, query, Set("notes", "notes"))

// DeleteAll
err := repo.DeleteAll(ctx, query)
```

```go
// UpdateAll
updatedCount, err := repo.UpdateAll(ctx, query, Set("notes", "notes"))

// DeleteAll
deletedCount, err := repo.DeleteAll(ctx, query)
```

--------------------------------

### PrimaryReplica Adapter Methods

Source: https://go-rel.github.io/reference/adapter-primaryreplica

This block details the methods available on the PrimaryReplica adapter, enabling database operations such as aggregation, applying migrations, transaction management, data manipulation (delete, insert, update), query execution, and connection management.

```APIDOC
type PrimaryReplica struct {
    // contains filtered or unexported fields
}

// Aggregate performs an aggregation query on the database.
// Parameters:
//   ctx: The context for the query.
//   query: The rel.Query object specifying the aggregation.
//   mode: The aggregation mode (e.g., "count", "sum").
//   field: The field to aggregate on.
// Returns:
//   The aggregated integer value and an error if the operation fails.
func (pr *PrimaryReplica) Aggregate(ctx context.Context, query rel.Query, mode string, field string) (int, error)

// Apply applies a database migration.
// Parameters:
//   ctx: The context for the migration.
//   migration: The rel.Migration object to apply.
// Returns:
//   An error if the migration fails to apply.
func (pr *PrimaryReplica) Apply(ctx context.Context, migration rel.Migration) error

// Begin starts a new database transaction.
// Returns:
//   A new rel.Adapter instance representing the transaction and an error if it fails.
func (pr *PrimaryReplica) Begin(ctx context.Context) (rel.Adapter, error)

// Close closes the adapter's connections.
// Returns:
//   An error if closing connections fails.
func (pr *PrimaryReplica) Close() error

// Commit commits the current database transaction.
// Parameters:
//   ctx: The context for the commit operation.
// Returns:
//   An error if the commit fails.
func (pr *PrimaryReplica) Commit(ctx context.Context) error

// Delete removes records from the database based on the provided query.
// Parameters:
//   ctx: The context for the delete operation.
//   query: The rel.Query object specifying which records to delete.
// Returns:
//   The number of records deleted and an error if the operation fails.
func (pr *PrimaryReplica) Delete(ctx context.Context, query rel.Query) (int, error)

// Exec executes a raw SQL statement.
// Parameters:
//   ctx: The context for the execution.
//   stmt: The SQL statement string.
//   args: A slice of interface{} representing the arguments for the statement.
// Returns:
//   The number of rows affected, the number of rows returned, and an error if execution fails.
func (pr *PrimaryReplica) Exec(ctx context.Context, stmt string, args []interface{}) (int64, int64, error)

// Insert inserts new records into the database.
// Parameters:
//   ctx: The context for the insert operation.
//   query: The rel.Query object specifying the table and fields.
//   primaryField: The name of the primary key field.
//   mutates: A map of field names to their mutation values.
//   onConflict: Specifies behavior on conflict (e.g., ignore, update).
// Returns:
//   The ID of the inserted record and an error if the operation fails.
func (pr *PrimaryReplica) Insert(ctx context.Context, query rel.Query, primaryField string, mutates map[string]rel.Mutate, onConflict rel.OnConflict) (interface{}, error)

// InsertAll inserts multiple records into the database in a single operation.
// Parameters:
//   ctx: The context for the insert operation.
//   query: The rel.Query object specifying the table and fields.
//   primaryField: The name of the primary key field.
//   fields: A slice of strings representing the fields to insert.
//   bulkMutates: A slice of maps, where each map represents mutations for a record.
//   onConflict: Specifies behavior on conflict.
// Returns:
//   A slice of IDs for the inserted records and an error if the operation fails.
func (pr *PrimaryReplica) InsertAll(ctx context.Context, query rel.Query, primaryField string, fields []string, bulkMutates []map[string]rel.Mutate, onConflict rel.OnConflict) ([]interface{}, error)

// Instrumentation sets an instrumenter for the adapter.
// Parameters:
//   instrumenter: The rel.Instrumenter to use for instrumentation.
func (pr *PrimaryReplica) Instrumentation(instrumenter rel.Instrumenter)

// Name returns the name of the adapter.
// Returns:
//   The adapter's name as a string.
func (pr *PrimaryReplica) Name() string

// Ping checks the health of the database connection.
// Parameters:
//   ctx: The context for the ping operation.
// Returns:
//   An error if the connection is not healthy.
func (pr *PrimaryReplica) Ping(ctx context.Context) error

// Query executes a query against the database.
// Parameters:
//   ctx: The context for the query.
//   query: The rel.Query object specifying the query details.
// Returns:
//   A rel.Cursor for iterating over results and an error if the query fails.
func (pr *PrimaryReplica) Query(ctx context.Context, query rel.Query) (rel.Cursor, error)

// Rollback discards the current database transaction.
// Parameters:
//   ctx: The context for the rollback operation.
// Returns:
//   An error if the rollback fails.
func (pr *PrimaryReplica) Rollback(ctx context.Context) error

// Update modifies existing records in the database.
// Parameters:
//   ctx: The context for the update operation.
//   query: The rel.Query object specifying which records to update and the fields to change.
//   primaryField: The name of the primary key field.
//   mutates: A map of field names to their new values.
// Returns:
//   The number of records updated and an error if the operation fails.
func (pr *PrimaryReplica) Update(ctx context.Context, query rel.Query, primaryField string, mutates map[string]rel.Mutate) (int, error)

// WriteAdapter returns the underlying write adapter, typically the primary connection.
// Returns:
//   The rel.Adapter instance used for writing.
func (pr *PrimaryReplica) WriteAdapter() rel.Adapter
```
Tokens:
Raw