rel

REL is a modern, ORM-ish database access layer designed for layered architectures in Golang. Key features include:

• Testability: Built-in reltest package for testing repositories.
• Transactions: Supports seamless nested transactions.
• Query Building: An elegant, extendable query builder that supports both builder syntax and plain SQL.
• Data Management: Supports Eager loading, Composite Primary Keys, Soft Deletion, and Pagination.
• Infrastructure: Multi-adapter support and Schema Migration capabilities.

To use REL in your Go project, install it using go get:

go get github.com/go-rel/rel

A Structset is a mutator used for repository insert or update operations. It saves every field in a struct and its associations, provided they are loaded. This is the default mutator used by the repository.

When applying a Structset via Apply(doc, mut):

• It automatically handles timestamp fields like created_at, inserted_at, and updated_at if the document has the corresponding flags (HasCreatedAt, HasUpdatedAt).
• It supports cascading mutations to associations if mut.Cascade is set to true.
• It can be configured to skip zero values for non-primary fields.

// Example conceptual usage
ss := rel.NewStructset(myEntity, true)
ss.Apply(targetDoc, mutation)

REL uses the db struct tag to map Go fields to database columns.

• Custom Name: Use db:"column_name" to specify a custom name.
• Ignore Field: Use db:"-" to exclude a field from metadata.
• Embedded Structs: Use db:",embedded" to treat a struct as an embedded part of the parent document, merging its fields into the parent's namespace.
• Primary Key: Use db:",primary" to explicitly mark a field as a primary key.

If no db tag is provided, the field name is converted from CamelCase to snake_case.

type User struct {
    ID        int       `db:"id,primary"` 
    FirstName string    `db:"first_name"` 
    Password  string    `db:"-"` // Ignored
    Metadata  Meta      `db:",embedded"` 
}

type Meta struct {
    LoginCount int `db:"login_count"` 
}

You can combine multiple FilterQuery objects into a single logical group using the And and Or functions, or by using the method-chaining style on an existing FilterQuery.

Functional Style:

filter := rel.And(rel.Eq("a", 1), rel.Eq("b", 2))
filter := rel.Or(rel.Eq("a", 1), rel.Eq("b", 2))

Chaining Style:

filter := rel.Eq("a", 1).And(rel.Eq("b", 2))
filter := rel.Eq("a", 1).Or(rel.Eq("b", 2))

// Using And/Or functions
f1 := rel.And(rel.Eq("field1", "val1"), rel.Eq("field2", "val2"))

// Using method chaining
f2 := rel.Eq("field1", "val1").And(rel.Eq("field2", "val2"))

REL uses a composition model for queries. The Build method on a Query object allows merging one query into another.

When merging:

1. If the target query is empty, it is replaced by the new query.
2. If the target query already has data, fields are merged:
   • Table and SelectQuery are overwritten if provided.
   • JoinQuery and SortQuery are appended.
   • WhereQuery is combined using And logic.
   • GroupQuery is overwritten.
   • OffsetQuery and LimitQuery are overwritten.
   • LockQuery is overwritten.
   • ReloadQuery, CascadeQuery, and UsePrimaryDb use boolean OR logic.

A SubQuery wraps an existing Query with a prefix, typically used to create nested expressions like Prefix(sub-query). This is useful for constructing complex logical expressions that some databases represent using keywords like ALL or ANY.

// Example of the conceptual structure
sub := rel.SubQuery{
    Prefix: "PREFIX",
    Query:  someQuery,
}

To start using REL, create a new Repository instance by passing an Adapter to the New function. The repository handles high-level data access, instrumentation, and transaction management.

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

// Assuming 'adapter' is an already initialized rel.Adapter
repo := rel.New(adapter)

You can combine multiple filters within a GroupQuery using Having or OrHaving. OrHaving specifically wraps the provided filters in an AND before applying an OR to the existing filter chain, allowing for complex logical grouping in the HAVING clause.

// Example: GROUP BY department HAVING (salary > 50000 AND age < 30) OR (bonus > 1000)
// Note: Exact syntax depends on your FilterQuery implementation

group := rel.NewGroup("department").
    OrHaving(
        rel.And(
            rel.Gt("salary", 50000),
            rel.Lt("age", 30),
        ),
        rel.Gt("bonus", 1000),
    )

query := &rel.Query{}
group.Build(query)