What Are Components?

Components are a higher-level data system built on top of ModelsHandler that allow you to define, persist, and synchronize structured table data across disk and database.

Unlike models and fields, which define structure, components represent actual data that is:

• Associated with a specific model (table)
• Stored in both JSON files and the database
• Kept in sync through a controlled synchronization process

Components are ideal for configuration tables, lookup data, seed data, or any dataset that must remain consistent across environments.

Component Structure

Internally, a component is a map of field names to values. A collection of components is keyed by the model’s primary key.

// Single component
map[string]any

// Component collection
map[string]map[string]any
                    

Each component entry represents one row in the associated table. The key of the component map corresponds to the table’s primary key.

Disk Representation

Components are stored on disk as JSON files, one per model.

components/
└── users.component.json
                    

Example structure:

{
  "1": {
    "name": "Admin",
    "role": "admin"
  },
  "2": {
    "name": "Guest",
    "role": "guest"
  }
}
                    

These files act as the local editable representation of component data.

Component Synchronization

Component synchronization ensures that local JSON components and database rows remain consistent.

The synchronization process follows strict rules:

1. If no local components exist, no sync occurs
2. If the database is empty, local components are inserted
3. Missing database rows are added
4. Stale database rows are removed
5. The database becomes the final source of truth
6. The local JSON file is rewritten from the database

This guarantees deterministic state after synchronization.

Refreshing from Database

Components can also be refreshed directly from the database. This rewrites the local JSON file using the current database state.

If the database is empty but local components exist, the system will prompt for confirmation before pushing local data into the database.

This safeguard prevents accidental data loss.

Accessing Components

Components are accessible through the model instance.

components := Users.GetComponents()

component, ok := Users.GetComponent("1")
                    

Individual field values can be retrieved safely:

value, ok := component.FieldValue("role")
                    

Updating Components

Updating a component updates both the in-memory representation and the corresponding database row.

Updates are executed using the query builder internally, ensuring consistency with all model constraints.

err := Users.UpdateComponent("1", component)
                    

After a successful update, the local JSON file is also updated.

Usage Guidelines

• Components require a primary key
• Each model owns its components entirely
• Use components for authoritative datasets
• Avoid using components for high-churn transactional data
• Review synchronization effects before production use

Component Migration Flags

Component synchronization is triggered explicitly using command-line flags when running your application.

--migrate-component

Synchronizes component JSON files with the database for all models that define components.

go run . --migrate-component
    

-mc

Shorthand alias for --migrate-component.

go run . -mc
    

When these flags are used, ModelsHandler performs a controlled synchronization between local component files and database rows. Without these flags, no component migration is performed.

Component migration is independent from schema migration and does not modify table structures.

Next Steps

• Best Practices