v2models

README

Why are references always pointers?

Gorm lets us use structs to represent associations--and we can do so with pointer or value types (link).

So why do we always use pointers, causing us to have to do nil checks in a bunch of places?

The reason why has to do with returning data to the client. When we load something from the database, we load associations too, but only one layer deep.

If we used values for associations, associations at the second/third/fourth layer etc would all appear to be loaded, as zero values. Up at the controller layer, we'd end up returning a bunch of nonsense data to clients.

As a concrete example, suppose you requested a ChartRelease, and the model and controllers all represented associations with value types:

{
  // Fields at this level would be present because this is the top level
  "environmentInfo": {
    // Fields at this level would be present because this is the first layer of associations
    "defaultClusterInfo": {
      // Fields at this level would be EMPTY because this is the second layer of associations, and it doesn't get loaded
    },
    "templateEnvironmentInfo": {
      // Fields at this level would be EMPTY because this is the second layer of associations, and it doesn't get loaded
      "defaultClusterInfo": {
        // Fields at this level would be EMPTY because this is the third layer of associations, and it doesn't get loaded
      }
    }
  }
}

The above is true even if we use omitempty, because structs in Go don't themselves have an empty value.

The solution is to use pointer types for associations at the controller layer, so omitempty works. That gives us this:

{
  // Fields at this level would be present because this is the top level
  "environmentInfo": {
    // Fields at this level would be present because this is the first layer of associations
    // `defaultClusterInfo` and `templateEnvironmentInfo` were nil and so weren't included here
  }
}

If we want to use pointer types for associations at the controller, it is very helpful to use them at the model too. This means that a lot of functions inside the model need to handle pointer types.

Internal stores

There's a concept here of an "internal" store versus a normal store that gets exported. Here's the differences:

internalModelStore	ModelStore
Singleton (kept in package-level vars)	Instanced
Stateless	Stateful (keeps a database reference as state)
Methods require a database reference	Methods use database reference from state
Methods accept full model type as queries	Methods accept selector strings as queries

(This table references model stores but event stores follow the same principle)

The basic idea is that internal stores can all call each other, even passing transaction references when necessary, while the exported stores are encapsulated things suitable for a controller to carry around.

Documentation

Index

• func KeepMetricsUpdated(ctx context.Context, db *gorm.DB, interval time.Duration)
• func UpdateMetrics(ctx context.Context, db *gorm.DB) error
• type AppVersion
  • func (c AppVersion) TableName() string
• type Changeset
  • func (c Changeset) TableName() string
• type ChangesetEventStore
  • func (s *ChangesetEventStore) Apply(selectors []string, user *auth.User) ([]Changeset, error)
  • func (s *ChangesetEventStore) Plan(changesets []Changeset, user *auth.User) ([]Changeset, error)
  • func (s *ChangesetEventStore) PlanAndApply(changesets []Changeset, user *auth.User) ([]Changeset, error)
  • func (s *ChangesetEventStore) QueryApplied(chartReleaseSelector string, offset int, limit int) ([]Changeset, error)
• type Chart
  • func (c Chart) TableName() string
• type ChartRelease
  • func (c ChartRelease) TableName() string
• type ChartReleaseVersion
• type ChartVersion
  • func (c ChartVersion) TableName() string
• type Cluster
  • func (c Cluster) TableName() string
• type DatabaseInstance
  • func (d DatabaseInstance) TableName() string
• type Environment
  • func (e Environment) TableName() string
• type Model
• type ModelStore
  • func (s ModelStore[M]) Create(model M, user *auth.User) (M, bool, error)
  • func (s ModelStore[M]) Delete(selector string, user *auth.User) (M, error)
  • func (s ModelStore[M]) Edit(selector string, editsToMake M, user *auth.User) (M, error)
  • func (s ModelStore[M]) Get(selector string) (M, error)
  • func (s ModelStore[M]) GetOtherValidSelectors(selector string) ([]string, error)
  • func (s ModelStore[M]) ListAllMatchingByCreated(filter M, limit int) ([]M, error)
  • func (s ModelStore[M]) ListAllMatchingByUpdated(filter M, limit int) ([]M, error)
• type PagerdutyIntegration
  • func (p PagerdutyIntegration) TableName() string
• type StoreSet
  • func NewStoreSet(db *gorm.DB) *StoreSet

Functions

func KeepMetricsUpdated

func KeepMetricsUpdated(ctx context.Context, db *gorm.DB, interval time.Duration)

func UpdateMetrics

func UpdateMetrics(ctx context.Context, db *gorm.DB) error

Types

type AppVersion

type AppVersion struct {
	gorm.Model
	Chart              *Chart
	ChartID            uint   `gorm:"not null: default:null"`
	AppVersion         string `gorm:"not null: default:null"`
	GitCommit          string
	GitBranch          string
	Description        string
	ParentAppVersion   *AppVersion
	ParentAppVersionID *uint
}

func (AppVersion) TableName

func (c AppVersion) TableName() string

type Changeset

type Changeset struct {
	gorm.Model
	ChartRelease   *ChartRelease
	ChartReleaseID uint

	From             ChartReleaseVersion `gorm:"embedded;embeddedPrefix:from_"`
	To               ChartReleaseVersion `gorm:"embedded;embeddedPrefix:to_"`
	AppliedAt        *time.Time
	SupersededAt     *time.Time
	NewAppVersions   []*AppVersion   `gorm:"many2many:v2_changeset_new_app_versions;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;"`
	NewChartVersions []*ChartVersion `gorm:"many2many:v2_changeset_new_chart_versions;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;"`
}

func (Changeset) TableName

func (c Changeset) TableName() string

type ChangesetEventStore

type ChangesetEventStore struct {
	*ModelStore[Changeset]
	// contains filtered or unexported fields
}

func (*ChangesetEventStore) Apply

func (s *ChangesetEventStore) Apply(selectors []string, user *auth.User) ([]Changeset, error)

func (*ChangesetEventStore) Plan

func (s *ChangesetEventStore) Plan(changesets []Changeset, user *auth.User) ([]Changeset, error)

func (*ChangesetEventStore) PlanAndApply

func (s *ChangesetEventStore) PlanAndApply(changesets []Changeset, user *auth.User) ([]Changeset, error)

func (*ChangesetEventStore) QueryApplied

func (s *ChangesetEventStore) QueryApplied(chartReleaseSelector string, offset int, limit int) ([]Changeset, error)

type Chart

type Chart struct {
	gorm.Model
	Name string `gorm:"not null; default:null; unique"`
	// Mutable
	ChartRepo             *string `gorm:"not null; default:null"`
	AppImageGitRepo       *string
	AppImageGitMainBranch *string
	ChartExposesEndpoint  *bool
	DefaultSubdomain      *string
	DefaultProtocol       *string
	DefaultPort           *uint
	LegacyConfigsEnabled  *bool
}

func (Chart) TableName

func (c Chart) TableName() string

type ChartRelease

type ChartRelease struct {
	gorm.Model
	Chart           *Chart
	ChartID         uint
	Cluster         *Cluster
	ClusterID       *uint
	DestinationType string
	Environment     *Environment
	EnvironmentID   *uint
	Name            string `gorm:"not null; default:null"`
	Namespace       string
	ChartReleaseVersion
	Subdomain              *string
	Protocol               *string
	Port                   *uint
	PagerdutyIntegration   *PagerdutyIntegration
	PagerdutyIntegrationID *uint
}

func (ChartRelease) TableName

func (c ChartRelease) TableName() string

type ChartReleaseVersion

type ChartReleaseVersion struct {
	ResolvedAt *time.Time

	AppVersionResolver             *string
	AppVersionExact                *string
	AppVersionBranch               *string
	AppVersionCommit               *string
	AppVersionFollowChartRelease   *ChartRelease
	AppVersionFollowChartReleaseID *uint
	AppVersion                     *AppVersion
	AppVersionID                   *uint

	ChartVersionResolver             *string
	ChartVersionExact                *string
	ChartVersionFollowChartRelease   *ChartRelease
	ChartVersionFollowChartReleaseID *uint
	ChartVersion                     *ChartVersion
	ChartVersionID                   *uint

	HelmfileRef         *string
	FirecloudDevelopRef *string
}

ChartReleaseVersion isn't stored in the database on its own, it is included as a part of a ChartRelease or Changeset. It has especially strict validation that requires it being fully loaded from the database. The resolve method will help "load" it fully from the database so it can survive validation.

type ChartVersion

type ChartVersion struct {
	gorm.Model
	Chart                *Chart
	ChartID              uint   `gorm:"not null: default:null"`
	ChartVersion         string `gorm:"not null: default:null"`
	Description          string
	ParentChartVersion   *ChartVersion
	ParentChartVersionID *uint
}

func (ChartVersion) TableName

func (c ChartVersion) TableName() string

type Cluster

type Cluster struct {
	gorm.Model
	Name              string `gorm:"not null; default:null; unique"`
	Provider          string `gorm:"not null; default:null"`
	GoogleProject     string
	AzureSubscription string
	Location          string `gorm:"not null; default:null"`
	// Mutable
	Base                *string `gorm:"not null; default:null"`
	Address             *string `gorm:"not null; default:null"`
	RequiresSuitability *bool   `gorm:"not null; default:null"`
	HelmfileRef         *string `gorm:"not null; default:null"`
}

func (Cluster) TableName

func (c Cluster) TableName() string

type DatabaseInstance

type DatabaseInstance struct {
	gorm.Model
	ChartRelease   *ChartRelease
	ChartReleaseID uint

	Platform                  *string
	GoogleProject             *string
	GoogleLocation            *string
	AzureSubscription         *string
	AzureManagedResourceGroup *string
	InstanceName              *string

	DefaultDatabase *string
}

func (DatabaseInstance) TableName

func (d DatabaseInstance) TableName() string

type Environment

type Environment struct {
	gorm.Model
	Base                      string
	Lifecycle                 string `gorm:"not null; default:null"`
	Name                      string `gorm:"not null; default:null"`
	NamePrefix                string
	TemplateEnvironment       *Environment
	TemplateEnvironmentID     *uint
	ValuesName                string
	AutoPopulateChartReleases *bool
	UniqueResourcePrefix      string `gorm:"not null; default:null"`
	DefaultNamespace          string
	// Mutable
	DefaultCluster              *Cluster
	DefaultClusterID            *uint
	DefaultFirecloudDevelopRef  *string
	Owner                       *string `gorm:"not null; default:null"`
	RequiresSuitability         *bool
	BaseDomain                  *string
	NamePrefixesDomain          *bool
	HelmfileRef                 *string `gorm:"not null; default:null"`
	PreventDeletion             *bool
	AutoDelete                  *environment.AutoDelete `gorm:"column:delete_after; -:migration"`
	Description                 *string
	PagerdutyIntegration        *PagerdutyIntegration
	PagerdutyIntegrationID      *uint
	Offline                     *bool
	OfflineScheduleBeginEnabled *bool
	OfflineScheduleBeginTime    *string
	OfflineScheduleEndEnabled   *bool
	OfflineScheduleEndTime      *string
	OfflineScheduleEndWeekends  *bool
}

func (Environment) TableName

func (e Environment) TableName() string

type Model

type Model interface {
	TableName() string
}

type ModelStore

type ModelStore[M Model] struct {
	// contains filtered or unexported fields
}

func (ModelStore[M]) Create

func (s ModelStore[M]) Create(model M, user *auth.User) (M, bool, error)

func (ModelStore[M]) Delete

func (s ModelStore[M]) Delete(selector string, user *auth.User) (M, error)

func (ModelStore[M]) Edit

func (s ModelStore[M]) Edit(selector string, editsToMake M, user *auth.User) (M, error)

func (ModelStore[M]) Get

func (s ModelStore[M]) Get(selector string) (M, error)

func (ModelStore[M]) GetOtherValidSelectors

func (s ModelStore[M]) GetOtherValidSelectors(selector string) ([]string, error)

GetOtherValidSelectors is basically just a human debug method. Different model types have different selectors to try to make it easier to refer to them than by having to directly query them and use their numeric ID primary key. Under the hood, models are already required to be able to generate selectors from an entry for uniqueness-validation purposes, so this is a simple method that uses that existing code to translate one selector for an existing entry into all possible selectors that would match.

func (ModelStore[M]) ListAllMatchingByCreated

func (s ModelStore[M]) ListAllMatchingByCreated(filter M, limit int) ([]M, error)

func (ModelStore[M]) ListAllMatchingByUpdated

func (s ModelStore[M]) ListAllMatchingByUpdated(filter M, limit int) ([]M, error)

type PagerdutyIntegration

type PagerdutyIntegration struct {
	gorm.Model
	PagerdutyID string
	Name        *string
	Key         *string
	Type        *string
}

func (PagerdutyIntegration) TableName

func (p PagerdutyIntegration) TableName() string

type StoreSet

type StoreSet struct {
	ClusterStore          *ModelStore[Cluster]
	EnvironmentStore      *ModelStore[Environment]
	ChartStore            *ModelStore[Chart]
	ChartVersionStore     *ModelStore[ChartVersion]
	AppVersionStore       *ModelStore[AppVersion]
	ChartReleaseStore     *ModelStore[ChartRelease]
	PagerdutyIntegration  *ModelStore[PagerdutyIntegration]
	DatabaseInstanceStore *ModelStore[DatabaseInstance]

	ChangesetEventStore *ChangesetEventStore
	// contains filtered or unexported fields
}

func NewStoreSet

func NewStoreSet(db *gorm.DB) *StoreSet