API Reference¶

Complete reference of all public functions in the den package, organized by category.

Module: github.com/oliverandrich/den

Database¶

CRUD¶

Every CRUD function below takes a Scope parameter. Scope is a sealed interface satisfied by both *DB (operating outside a transaction) and *Tx (operating inside RunInTransaction). Pass whichever you have.

Save¶

Read¶

Delete¶

By-condition writes (find-and-update, find-or-create, bulk update, bulk delete, back-links) live on QuerySet — see the Query section below. There is no top-level FindOneAndUpdate / FindOneAndUpsert / FindOrCreate / UpdateMany / DeleteMany / BackLinks anymore: build a chain with NewQuery[T](db, conds...) and call the matching terminal (UpdateOne, UpsertOne, GetOrCreate, Update, Delete, BackLinks).

Query¶

Creating a Query¶

q := den.NewQuery[T](scope, conditions...) // scope is *DB or *Tx

Chainable Methods¶

All chainable methods return QuerySet[T] and can be composed in any order.

Terminal Methods¶

Terminal methods execute the query and return results.

Every terminal takes ctx context.Context as its first argument, so the same QuerySet can be executed against different contexts (different timeouts, different cancellation scopes).

Note: den.LiteralFTS5(term string) string exposes the literal-terms transform Search applies — use it to build a safe FTS5 string by hand for composing with SearchRaw.

Aggregation¶

Aggregation methods are chained onto a QuerySet[T].

Scalar Aggregations¶

Grouped Aggregations¶

// GroupBy example
type Stats struct {
    Category string  `den:"group_key"`
    AvgPrice float64 `den:"avg:price"`
    Count    int64   `den:"count"`
}

err := den.NewQuery[Product](db).GroupBy("category.name").Into(ctx, &results)

Relations¶

Reverse queries live on QuerySet: den.NewQuery[House](db).BackLinks("door", doorID).All(ctx) — see the Terminal Methods table.

Link Rules¶

Change Tracking¶

Requires embedding document.Tracked alongside document.Base.

Transactions¶

RunInTransaction opens a transaction; the closure receives a *Tx. CRUD functions take a Scope (satisfied by *DB and *Tx), so the same Save/Delete/FindByID etc. work both inside and outside a transaction — pass the *Tx instead of the *DB. The APIs listed below are the transaction-only ones: they take *Tx directly because their semantics are tied to transaction lifetime.

Note: Standard CRUD operations (Save, Delete, FindByID, …) accept a Scope parameter; pass *DB outside a transaction and *Tx inside.

Metadata¶

Attachments & Storage¶

Types and functions for embedding file references in documents and swapping the byte-storage backend. See the Attachments & Storage guide for the full walkthrough.

Option and Accessor¶

Storage Interface¶

type Storage interface {
    Store(ctx context.Context, r io.Reader, ext, mime string) (document.Attachment, error)
    Open(ctx context.Context, a document.Attachment) (io.ReadCloser, error)
    Delete(ctx context.Context, a document.Attachment) error
    URL(a document.Attachment) string
}

Implementations must be content-addressed enough that two calls with identical bytes resolve to the same StoragePath. Delete must be idempotent on missing paths.

Storage Registry¶

Located in github.com/oliverandrich/den/storage. The root package holds the interface + a scheme-based opener registry; concrete backends live in sub-packages that self-register on import.

Filesystem Backend (storage/file)¶

Located in github.com/oliverandrich/den/storage/file. Reference backend that stores bytes on the local filesystem. Importing the package for its side effect registers the file:// scheme with storage.OpenURL.

Attachment Document Embed¶

Located in the document sub-package (github.com/oliverandrich/den/document).

type Attachment struct {
    StoragePath string `json:"storage_path"     validate:"required,max=1024"`
    Mime        string `json:"mime"             validate:"required,max=100"`
    Size        int64  `json:"size"             validate:"required,min=1"`
    SHA256      string `json:"sha256,omitempty" validate:"omitempty,len=64"`
}

Embed alongside document.Base for IS-a-file documents, or declare as named fields for HAS-files documents. den.Delete(..., den.HardDelete()) walks the document via reflection and asks the configured Storage to delete every non-zero Attachment it finds.

Index Lifecycle¶

DropStaleResult contains two slices:

• Dropped []StaleIndex — indexes that were (or would be, under DryRun) removed
• Kept []StaleIndex — recorded indexes that are still referenced by a current IndexDefinition

StaleIndex has fields Collection, Name, Fields []string, Unique bool.

Migrations¶

Located in the migrate sub-package (github.com/oliverandrich/den/migrate).

Testing Helpers¶

Located in the dentest sub-package (github.com/oliverandrich/den/dentest).

Key Types¶