Entities

As might be discussed in other documents, entities are tables in database, similar to Entity Framework and other ORMs concept of 'entity', which is a table mapped to a class or struct in the programming language.

The major difference between Fireback entities is, it provides functionality by default on top of the entity, which could be used directly as http api or cli, without creating much controller. Every entity supposed to be able to be created easily, updated, deleted, obey permission role requirements.

Entities are one of the major features in Fireback, which would save a lot of time and effort to storing content from front-end technologies into database and all the way back querying them.

Defining entity

You can simply define a entity by adding it into entities array in a Module3.Yaml file. Important: Entity name needs to be singular form in English, lowerCase, and camelCase

entities:
    - name: creditCard

By adding this, you'll generate CreditCard.dyno.go and CreditCard.go files. Fireback always creates entities go files in pair, the *.dyno.go file is a generated feature based on configuration, and the other file is for your code changes related to entity, and won't be recreated or modified by Fireback.

You need to understand that Dyno files are being regenerated by changing the definition, so you should not touch it's content if you want to regeneration work. Technically, if you need to modify this file manually, you can remove it from Module3 yaml definition, and merge 2 files content into one. But then, you won't be able to update the functionality by Fireback version change or using YAML.

Using entities in project

After defining the entity, the code is generated, but not injected to the Fireback app tree. You need to add the *EntityBundle into the module. Open your module go file, and look for the ModuleProvider definition, which might be similar to:

func PaymentModuleSetup(cfg *PaymentModuleConfig) *workspaces.ModuleProvider {
	module := &workspaces.ModuleProvider{
		Name:          "payment",
		Definitions:   &Module3Definitions,
		ActionsBundle: GetPaymentActionsBundle(),
		EntityBundles: []workspaces.EntityBundle{
			PaymentParameterEntityBundle,
			TransactionEntityBundle,

            CreditCardEntityBundle,

			// Insert the NameEntityBundle here.
			// each entity, has multiple features, such as permissions, events, translations
			// *EntityBundle objects are a list of them which are auto generated,
			// and by adding them here it will be automatically added.
			// we cannot add them automatically upon saving yaml for you,
			// when you add a new entity in yaml, add it manually here.
		},
	}

	return module
}

This would import permissions, cli actions, http requests into the module, and when module is being injected into the tree, it would become available.

Entity Migration to database

When you add a new entity or modify it, you need to migrate it into database. Fireback is using gorm underneath, and 1t 1.2.0 does not provide any migration other than auto migration feature of gorm.

By running fireback migration apply, fireback tries to migrate all entities across project. To me myself, migration of new constraints are not that good in gorm, and many times in projects I had to modify the database manually or extra native sql query.

Defining fields for Entity

Entities have a field called fields as an array, and you can define the columns of the data it would keep. They will become database definitions, as well as golang code. You can read about fields fields page - Fields struct is same for entity and action, and other places that fields keyword is used.