BeamFoundry Rays ORM on BeamFoundryi Rays Orm

1. Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction & Architecture

In standard Go applications, managing database transactions across multiple service layers usually requires polluting your function signatures by passing a tx *gorm.DB parameter down the entire call stack. Furthermore, writing basic CRUD operations for every model leads to massive code duplication.

Rays ORM solves both of these enterprise problems natively.

🧹 Simplifying with Dot Imports

Just like the core Rays framework, it is highly recommended to use Go’s dot import feature for the ORM package (import . "github.com/BeamFoundry/rays-orm"). This allows you to use types like OrmRepository, OrmQueryFunc, and GormTxManager directly without package prefixes, keeping your domain code exceptionally clean and readable.

2. Quickstart & Setup

Mon, 01 Jan 0001 00:00:00 +0000

Quickstart & Setup

To use Rays ORM, you must define a Configuration Beam that provides a raw *gorm.DB instance, and optionally a Migrator service to initialize your schema.

1. Defining the Database Beam

Use a standard Rays Configuration struct to open your database connection and provide it to the container.

package config

import (
 "gorm.io/driver/sqlite"
 "gorm.io/gorm"
 . "github.com/BeamFoundry/rays/pkg/core"
 . "github.com/BeamFoundry/rays/pkg/lang"
)

type DBConfig struct {
 Configuration
}

// Provides the raw *gorm.DB Beam to the container
func (*DBConfig) DB() (*gorm.DB, Error) {
 if db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{}); err == nil {
 return db, nil
 } else {
 return nil, NewErrorFrom(err)
 }
}

2. Auto-Migrations

Because the database is a standard Beam, you can inject it into a Service to handle auto-migrations during the PostConstruct lifecycle phase. You can utilize the Rays Try / RaiseErr pattern for clean error handling.

3. Auto-Generated Repositories

Mon, 01 Jan 0001 00:00:00 +0000

Auto-Generated Repositories

Rays ORM eliminates CRUD boilerplate by automatically implementing interface methods based on their function signatures.

1. The Base Repository

Rays provides OrmRepository[T, ID], which automatically provides implementations for the standard operations defined by the OrmRepositoryInterface:

Query(queries ...OrmQueryFunc) *gorm.DB: Lets you execute queries on <T>, calling gorm Model() *gorm.DB first.
FindById(id ID) Optional[*T]: Lets you find an optional model pointer by its Id of type <ID>.
Delete(object *T) Error: Lets you delete a model <T> pointer, previously returned.
DeleteById(id ID) Error: Lets you delete a model using its id of type <ID>.
Save(object *T) (*T, Error): Saves a model <T> pointer, returning the pointer and/or an Error.
SaveAll(object []*T) ([]*T, Error): Saves a slice of <T> pointers, returning it and/or an Error.

2. The Query Builder Syntax

To add custom queries, you define an unexported func field on your struct. During container wiring, Rays ORM parses the name of the function field and automatically generates the GORM query code to fulfill it.

4. ThreadLocal Transactions

Mon, 01 Jan 0001 00:00:00 +0000

ThreadLocal Transactions

A common pain point in Go is passing database transaction objects (*gorm.DB) explicitly as arguments to every repository function.

Rays ORM utilizes github.com/timandy/routine to establish ThreadLocal state for your goroutines. When you start a transaction via the GormTxManager, the transaction is stored in the local thread context.

When your auto-generated repositories execute queries, they transparently check the ThreadLocal context. If a transaction exists, they use it. If not, they use the global *gorm.DB.

5. Logging Integration

Mon, 01 Jan 0001 00:00:00 +0000

Logging Integration

The core Rays framework uses a centralized, slog-based logging mechanism to ensure structured JSON output and trace contexts. GORM, however, has its own internal logging interface.

To maintain observability across your enterprise application, you should bridge GORM’s output directly into the Rays Logging system. This prevents raw database queries from leaking into standard output as unformatted text.

Bridging GORM to `slog`

To unify your logging, we highly recommend using the slog-gorm adapter package.

6. Testing & Environments

Mon, 01 Jan 0001 00:00:00 +0000

Testing & Environments

Enterprise applications need to seamlessly switch databases based on the environment: a robust PostgreSQL instance for Production, and a fast, ephemeral SQLite instance for local testing.

By combining Rays ORM with the core framework’s ConditionalOnProfile and ConfigurationProperties, you can create a highly scalable environment strategy.

1. The Configuration Files

Define your connection strings in your standard YAML configuration files.

# config/application.yaml (Default / Testing)
app:
 database:
 dsn: "file::memory:"

# config/application-prod.yaml (Loaded only when 'prod' profile is active)
app:
 database:
 dsn: "host=localhost user=gorm password=gorm dbname=gorm port=9920 sslmode=disable"

2. The Dialector Strategy

Create an interface to abstract the GORM Dialector opening logic, and implement it for both SQLite and Postgres.

7. Advanced Querying

Mon, 01 Jan 0001 00:00:00 +0000

Advanced Querying

The auto-generated repository methods (findBy...) are excellent for standard CRUD operations. However, enterprise applications frequently require eager loading (preloads), pagination, and complex joins.

Rays ORM handles this complexity using the OrmQueryFunc escape hatch, keeping your repository interfaces clean and putting data hydration logic squarely in the hands of the business service layer.

1. Relationships & Preloading

Instead of embedding eager-loading logic into the method name string, Rays ORM provides helper functions (WithPreload and WithJoins) that return an OrmQueryFunc.

8. Hooks & Soft Deletes

Mon, 01 Jan 0001 00:00:00 +0000

Lifecycle Hooks & Soft Deletes

Understanding how GORM interacts with the Rays IoC container is crucial for structuring your enterprise business logic securely.

1. Model Hooks vs. Service Logic (The IoC Boundary)

GORM provides native model hooks (e.g., BeforeCreate, AfterSave). It is tempting to place all your pre-save logic in these hooks, but you must respect the IoC Boundary.

Models (like User{}) are instantiated by the database driver, not by the Rays IoC container. Therefore, you cannot use the @:"Inject" tag inside a GORM model.

BeamFoundry Rays ORM on BeamFoundryi Rays Orm

1. Introduction

Introduction & Architecture

🧹 Simplifying with Dot Imports

2. Quickstart & Setup

Quickstart & Setup

1. Defining the Database Beam

2. Auto-Migrations

3. Auto-Generated Repositories

Auto-Generated Repositories

1. The Base Repository

2. The Query Builder Syntax

4. ThreadLocal Transactions

ThreadLocal Transactions

5. Logging Integration

Logging Integration

Bridging GORM to slog

6. Testing & Environments

Testing & Environments

1. The Configuration Files

2. The Dialector Strategy

7. Advanced Querying

Advanced Querying

1. Relationships & Preloading

8. Hooks & Soft Deletes

Lifecycle Hooks & Soft Deletes

1. Model Hooks vs. Service Logic (The IoC Boundary)

Bridging GORM to `slog`