frantic-amphora

frantic-amphora

frantic-amphora is a comprehensive Data Access Object (DAO) framework for Go applications, providing type-safe database operations, code generation, and enterprise features built on top of Storm (BoltDB). It is designed to reduce boilerplate while maintaining flexibility through extensible hooks and validators.

What is frantic-amphora?

frantic-amphora provides:

• Type-safe database operations with strongly-typed field queries and generic helpers
• Automatic code generation (dao-gen) to scaffold complete DAO packages
• Built-in auditing tracking all CRUD operations with user context
• Cache integration with automatic synchronization and hydration
• Background job scheduling using cron expressions
• Import/Export capabilities for JSON and CSV formats
• Validation framework with customizable hooks
• Extensible entity types including typed numbers, money, decimals, and more

Core Components

DAO Framework (dao/)

The foundation of the framework with several key packages:

• database - Storm-backed database layer with typed generic helpers
• cache - Cache management and synchronization
• entities - Typed entity definitions (Bool, Int, Money, Decimal, etc.)
• audit - Audit trail integration for tracking changes
• lookup - Lookup table support
• maintenance - Database backup and pruning utilities

Code Generation (cmd/dao-gen)

The dao-gen tool generates complete DAO packages with:

• Type-safe CRUD operations
• Field definitions for query building
• Cache hydration and synchronization
• Background worker support
• Import/Export functionality
• Validation hooks and custom logic registration

See CODE-GEN.md for complete usage instructions and command-line options.

Supporting Packages

• importExportHelper - CSV and JSON import/export utilities
• jobs - Background job scheduling with cron support
• data/config - Sample configuration files

Quick Start

Using the Code Generator

Generate a new DAO package:

go run ./cmd/dao-gen -pkg user -type User -table users -out ./dao/user -force

Custom Field Definitions

Create a User.definition file to define domain-specific fields:

// Domain specific fields, starts.

// User's full name
Name string `storm:"index"`

// User's email address
Email string `storm:"index,unique"`

// User's age
Age entities.Int

// Account balance
Balance entities.Money

See the dao-gen README for details on field types and customization.

Example Implementation

The templateStoreV3 and tripStore packages provide complete reference implementations demonstrating:

• All available entity types (Bool, Int variants, Float variants, Decimal, Money, Currency, etc.)
• Function registration pattern for custom logic
• Cache integration
• Worker implementation
• Import/Export usage
• Validation patterns

Architecture Pattern

Generated DAO packages follow a consistent structure:

1. Model (*Model.go) - Entity definition with typed fields
2. DAO (*.go) - CRUD operations (Count, Get, Create, Update, Delete)
3. Database (*DB.go) - Database lifecycle management
4. Cache (*Cache.go) - Cache hydration and synchronization
5. Helpers (*Helpers.go) - Function registration for custom hooks
6. Internals (*Internals.go) - Internal validation and processing
7. Worker (*Worker.go) - Background job processing (optional)
8. Import/Export (*Impex.go) - Data import/export (optional)
9. Debug (*Debug.go) - Debug utilities (optional)

Custom business logic is implemented in separate *Logic.go files and registered via the Helpers functions.

Key Features

Type-Safe Queries

// Query using typed fields
user, err := userStore.GetBy(ctx, userStore.Fields.Email, "user@example.com")

Audit Trail

All operations automatically track:

• Who performed the action
• When it occurred
• What changed

Extensibility via Registration

// Register custom validation
userStore.RegisterValidator(func(ctx context.Context, user *User) error {
    if user.Age.Int() < 18 {
        return errors.New("must be 18 or older")
    }
    return nil
})

Generic Helpers

import "github.com/mt1976/frantic-amphora/dao/database"

// Type-safe retrieval
user, err := database.GetTyped[User](db, userStore.Fields.ID, 123)
users, err := database.GetAllTyped[User](db)

Documentation

Documentation Index

• Root overview

• Code generation guide

• DAO generator tool

• DAO generator test output

• Database helpers

• TemplateStoreV3 example

• TripStore example

• Import/Export helper

• Jobs scheduler

• Sample config

• Code Generation Guide - Complete guide to using dao-gen

• dao-gen Tool Reference - Tool-specific documentation

• Database Package - Database layer and generic helpers

• TemplateStoreV3 Example - Reference implementation

• TripStore Example - Reference implementation

• Import/Export Helper - Data import/export utilities

• Jobs Package - Background job scheduling

Dependencies

Built on:

• Storm v3 - Embedded key/value database (BoltDB wrapper)
• frantic-core - Core utilities (logging, timing, paths, etc.)
• go-playground/validator - Struct validation
• robfig/cron - Cron job scheduling (via jobs package)

License

See LICENSE for details.