From a9a4d8b093c904d3b86fc292b1395fa3a8c8b906 Mon Sep 17 00:00:00 2001 From: Piotr Kowalczuk Date: Tue, 16 Jan 2024 12:33:14 +0100 Subject: [PATCH] additional comments --- column.go | 62 +++++++++++++++++++++++++++++++++++++------------ function.go | 8 ++++--- relationship.go | 51 ++++++++++++++++++++++++++++------------ schema.go | 22 ++++++++++++------ table.go | 20 ++++++++++------ type.go | 44 +++++++++++++++++++++++------------ 6 files changed, 145 insertions(+), 62 deletions(-) diff --git a/column.go b/column.go index 8efe46d..8420f01 100644 --- a/column.go +++ b/column.go @@ -15,24 +15,56 @@ const ( // Event ... type Event string -// Column ... +// Column describes database column. type Column struct { - Name, ShortName, Collate, Check string - Default map[Event]string - NotNull, Unique, PrimaryKey, Index bool - Type Type - Table *Table - Reference *Column - ReferenceOptions []RelationshipOption - Match, OnDelete, OnUpdate int32 - NoInherit, DeferrableInitiallyDeferred, DeferrableInitiallyImmediate bool - // Dynamic + // Name is a column name. + Name string + // ShortName is a column short name. It is used in queries when column name is ambiguous. + ShortName string + // Collate is a collation for column. + // It allows to specify the collation order for character data. + Collate string + // Check is a check constraint. + // It allows to specify a predicate that must be satisfied by each row of the table. + Check string + // Default is a default value for column for given event. + // For example for insert event it will be used when no value is provided. + Default map[Event]string + // NotNull if true means that column cannot be null. + NotNull bool + // Unique if true means that column value must be unique. + Unique bool + // PrimaryKey if true means that column is a primary key. + PrimaryKey bool + // Index if true means that column is indexed. + Index bool + // Type is a column type. + Type Type + // Table is a table that column belongs to. + Table *Table + // Reference is a column that this column references. + Reference *Column + // ReferenceOptions are options for reference. + ReferenceOptions []RelationshipOption + // Match is a match option for foreign key constraint. + Match int32 + // OnDelete is a ON DELETE clause that specifies the action to perform when a referenced row in the referenced table is being deleted. + OnDelete int32 + // OnUpdate is a ON UPDATE clause that specifies the action to perform when a referenced column in the referenced table is being updated to a new value. + OnUpdate int32 + // NoInherit if true means that column is not inherited by child tables. + NoInherit bool + DeferrableInitiallyDeferred bool + DeferrableInitiallyImmediate bool + // IsDynamic if true means that column is not stored in database, but is dynamically created using function. IsDynamic bool - Func *Function - Columns Columns + // Func is a function that is used to create dynamic column. + Func *Function + // Columns are columns that are used by dynamic column function. + Columns Columns } -// NewColumn ... +// NewColumn initializes new instance of Column. func NewColumn(n string, t Type, opts ...ColumnOption) *Column { c := &Column{ Name: n, @@ -46,7 +78,7 @@ func NewColumn(n string, t Type, opts ...ColumnOption) *Column { return c } -// NewDynamicColumn ... +// NewDynamicColumn initializes new instance of Column that is created using function. func NewDynamicColumn(n string, f *Function, cs ...*Column) *Column { return &Column{ IsDynamic: true, diff --git a/function.go b/function.go index 7ce860c..5750f48 100644 --- a/function.go +++ b/function.go @@ -21,9 +21,10 @@ const ( FunctionBehaviourStable ) +// FunctionBehaviour is a function behaviour, it can be volatile, immutable or stable. type FunctionBehaviour int -// Function ... +// Function describes database function. type Function struct { Name string BuiltIn bool @@ -33,13 +34,14 @@ type Function struct { Args []*FunctionArg } -// FunctionArg ... +// FunctionArg is a function argument, it is used to describe function signature. type FunctionArg struct { Name string Type Type } -// FunctionNow ... +// FunctionNow is a helper function that creates now() function. +// Now() returns current timestamp with time zone (abbreviated as timestamptz). func FunctionNow() *Function { return &Function{ Name: "now", diff --git a/relationship.go b/relationship.go index 2487910..5470f34 100644 --- a/relationship.go +++ b/relationship.go @@ -34,14 +34,31 @@ const ( SetDefault ) -// RelationshipType ... +// RelationshipType can be used to describe relationship between tables. +// It can be one to one, one to many, many to one or many to many. type RelationshipType int -// Relationship ... +// Relationship describes database relationship. +// Usually it is used to describe foreign key constraint. type Relationship struct { - Bidirectional bool - Type RelationshipType - OwnerName, InversedName string + // Bidirectional if true means that relationship is bidirectional. + // It is useful when we want to get all related rows from both tables. + // If true, the library will generate additional methods for both tables. + Bidirectional bool + // Type defines relationship type. + Type RelationshipType + // OwnerName is a name of relationship from owner table perspective. + // For example if we have table A and table B and relationship from A to B, + // then owner name is a name of relationship from A perspective. + // It is a good practice to give descriptive names to relationships. + OwnerName string + // InversedName is a name of relationship from inversed table perspective. + // For example if we have table A and table B and relationship from A to B, + // then inversed name is a name of relationship from B perspective. + // If not set, the library will generate it automatically. + // It is useful when we want to have two relationships between two tables or when table self references itself. + // It is a good practice to give descriptive names to relationships. + InversedName string OwnerTable, InversedTable, ThroughTable *Table OwnerForeignKey, InversedForeignKey *Constraint OwnerColumns, InversedColumns Columns @@ -64,22 +81,26 @@ func newRelationship(owner, inversed, through *Table, rt RelationshipType, opts return r } -// OneToOne ... +// OneToOne is a handy constructor that instantiates basic one-to-one relationship. +// It can be adjusted using RelationshipOption. func OneToOne(t *Table, opts ...RelationshipOption) *Relationship { return newRelationship(nil, t, nil, RelationshipTypeOneToOne, opts...) } -// OneToMany ... +// OneToMany is a handy constructor that instantiates basic one-to-many relationship. +// It can be adjusted using RelationshipOption. func OneToMany(t *Table, opts ...RelationshipOption) *Relationship { return newRelationship(t, nil, nil, RelationshipTypeOneToMany, opts...) } -// ManyToOne ... +// ManyToOne is a handy constructor that instantiates basic many-to-one relationship. +// It can be adjusted using RelationshipOption. func ManyToOne(t *Table, opts ...RelationshipOption) *Relationship { return newRelationship(nil, t, nil, RelationshipTypeManyToOne, opts...) } -// ManyToMany ... +// ManyToMany is a handy constructor that instantiates basic many-to-many relationship. +// It can be adjusted using RelationshipOption. func ManyToMany(t1 *Table, t2 *Table, opts ...RelationshipOption) *Relationship { return newRelationship(t1, t2, nil, RelationshipTypeManyToMany, opts...) } @@ -105,7 +126,7 @@ func WithOwnerForeignKey(primaryColumns, referenceColumns Columns, opts ...Const } } -// WithInversedForeignKey ... +// WithInversedForeignKey adjust relationship to have inversed foreign key. func WithInversedForeignKey(primaryColumns, referenceColumns Columns, opts ...ConstraintOption) RelationshipOption { return func(r *Relationship) { if r.Type != RelationshipTypeManyToMany { @@ -122,7 +143,7 @@ func WithInversedForeignKey(primaryColumns, referenceColumns Columns, opts ...Co } } -// WithForeignKey ... +// WithForeignKey adjust relationship to have foreign key. func WithForeignKey(primaryColumns, referenceColumns Columns, opts ...ConstraintOption) RelationshipOption { return func(r *Relationship) { if r.Type == RelationshipTypeManyToMany { @@ -139,28 +160,28 @@ func WithForeignKey(primaryColumns, referenceColumns Columns, opts ...Constraint } } -// WithInversedName ... +// WithInversedName adjust relationship by setting inversed name. func WithInversedName(s string) RelationshipOption { return func(r *Relationship) { r.InversedName = s } } -// WithColumnName ... +// WithColumnName adjust relationship by setting column name. func WithColumnName(n string) RelationshipOption { return func(r *Relationship) { r.ColumnName = n } } -// WithBidirectional ... +// WithBidirectional adjust relationship by setting bidirectional flag. func WithBidirectional() RelationshipOption { return func(r *Relationship) { r.Bidirectional = true } } -// WithOwnerName ... +// WithOwnerName adjust relationship by setting owner name. func WithOwnerName(s string) RelationshipOption { return func(r *Relationship) { r.OwnerName = s diff --git a/schema.go b/schema.go index 90f5379..9340668 100644 --- a/schema.go +++ b/schema.go @@ -1,15 +1,22 @@ package pqt -// Schema ... +// Schema describes database schema. +// It is a collection of tables, functions and types. type Schema struct { - Name string + // Name is a schema name. + Name string + // IfNotExists if true means that schema should be created only if it does not exist. + // If true, creation process will not fail if schema already exists. IfNotExists bool - Tables []*Table - Functions []*Function - Types []Type + // Tables is a collection of tables that schema contains. + Tables []*Table + // Functions is a collection of functions that schema contains. + Functions []*Function + // Types is a collection of types that schema contains. + Types []Type } -// NewSchema ... +// NewSchema initializes new instance of Schema for given name and options. func NewSchema(name string, opts ...SchemaOption) *Schema { s := &Schema{ Name: name, @@ -22,7 +29,7 @@ func NewSchema(name string, opts ...SchemaOption) *Schema { return s } -// AddTable ... +// AddTable adds table to schema. func (s *Schema) AddTable(t *Table) *Schema { if s.Tables == nil { s.Tables = make([]*Table, 0, 1) @@ -33,6 +40,7 @@ func (s *Schema) AddTable(t *Table) *Schema { return s } +// AddFunction adds function to schema. func (s *Schema) AddFunction(f *Function) *Schema { if s.Functions == nil { s.Functions = make([]*Function, 0, 1) diff --git a/table.go b/table.go index 154f7ec..f007018 100644 --- a/table.go +++ b/table.go @@ -10,12 +10,18 @@ type Table struct { self bool Name, ShortName, Collate, TableSpace string IfNotExists, Temporary bool - Schema *Schema - Columns Columns - Constraints Constraints - OwnedRelationships []*Relationship - InversedRelationships []*Relationship - ManyToManyRelationships []*Relationship + // Schema references parent schema. + Schema *Schema + // Columns is a collection of columns that table contains. + Columns Columns + // Constraints is a collection of constraints that table contains. + Constraints Constraints + // OwnedRelationships is a collection of relationships that table owns. + OwnedRelationships []*Relationship + // InversedRelationships is a collection of relationships that table is inversed in. + InversedRelationships []*Relationship + // ManyToManyRelationships is a collection of relationships that table is inversed in. + ManyToManyRelationships []*Relationship } // NewTable allocates new table using given name and options. @@ -297,7 +303,7 @@ func WithTableSpace(s string) TableOption { } } -// WithTableShortName ... +// WithTableShortName pass the short name of the table. func WithTableShortName(s string) TableOption { return func(t *Table) { t.ShortName = s diff --git a/type.go b/type.go index 3d7329b..2ec09ed 100644 --- a/type.go +++ b/type.go @@ -36,22 +36,35 @@ func TypeDecimal(precision, scale int) BaseType { } } -// TypeReal ... +// TypeReal represents single precision floating-point numbers. +// In postgres it is stored as 4-byte single-precision floating point numbers. func TypeReal() BaseType { return BaseType{name: "REAL"} } -// TypeSerial ... +// TypeSerial is an auto-incrementing integer. +// It is generally used to store the primary key of a table. +// To specify that a column is to be used as a serial column, declare it as type SERIAL. +// Note that, even though SERIAL appears to be a column type, +// it is actually shorthand notation that tells PostgreSQL to create a auto-incrementing column behind the scenes. func TypeSerial() BaseType { return BaseType{name: "SERIAL"} } -// TypeSerialSmall ... +// TypeSerialSmall is an auto-incrementing small integer. +// It is generally used to store the primary key of a table. +// To specify that a column is to be used as a serial column, declare it as type SMALLSERIAL. +// Note that, even though SMALLSERIAL appears to be a column type, +// it is actually shorthand notation that tells PostgreSQL to create a auto-incrementing column behind the scenes. func TypeSerialSmall() BaseType { return BaseType{name: "SMALLSERIAL"} } -// TypeSerialBig ... +// TypeSerialBig is an auto-incrementing big integer. +// It is generally used to store the primary key of a table. +// To specify that a column is to be used as a serial column, declare it as type BIGSERIAL. +// Note that, even though BIGSERIAL appears to be a column type, +// it is actually shorthand notation that tells PostgreSQL to create a auto-incrementing column behind the scenes. func TypeSerialBig() BaseType { return BaseType{name: "BIGSERIAL"} } @@ -71,7 +84,7 @@ func TypeIntegerBig() BaseType { return BaseType{name: "BIGINT"} } -// TypeIntegerArray ... +// TypeIntegerArray is an array of integers. func TypeIntegerArray(l int) BaseType { if l == 0 { return BaseType{name: "INTEGER[]"} @@ -79,7 +92,7 @@ func TypeIntegerArray(l int) BaseType { return BaseType{name: fmt.Sprintf("INTEGER[%d]", l)} } -// TypeIntegerBigArray ... +// TypeIntegerBigArray is an array of big integers. func TypeIntegerBigArray(l int) BaseType { if l == 0 { return BaseType{name: "BIGINT[]"} @@ -87,7 +100,7 @@ func TypeIntegerBigArray(l int) BaseType { return BaseType{name: fmt.Sprintf("BIGINT[%d]", l)} } -// TypeIntegerSmallArray ... +// TypeIntegerSmallArray is an array of small integers. func TypeIntegerSmallArray(l int) BaseType { if l == 0 { return BaseType{name: "SMALLINT[]"} @@ -95,7 +108,7 @@ func TypeIntegerSmallArray(l int) BaseType { return BaseType{name: fmt.Sprintf("SMALLINT[%d]", l)} } -// TypeDoubleArray ... +// TypeDoubleArray is an array of double precision floating-point numbers. func TypeDoubleArray(l int) BaseType { if l == 0 { return BaseType{name: "DOUBLE PRECISION[]"} @@ -146,7 +159,7 @@ func TypeText() BaseType { return BaseType{name: "TEXT"} } -// TypeTextArray ... +// TypeTextArray is an array of text. func TypeTextArray(l int) BaseType { if l == 0 { return BaseType{name: "TEXT[]"} @@ -154,7 +167,7 @@ func TypeTextArray(l int) BaseType { return BaseType{name: fmt.Sprintf("TEXT[%d]", l)} } -// TypeVarchar ... +// TypeVarchar is a character varying(n), where n is a positive integer. func TypeVarchar(l int) BaseType { if l == 0 { return BaseType{name: "VARCHAR"} @@ -163,7 +176,7 @@ func TypeVarchar(l int) BaseType { return BaseType{name: fmt.Sprintf("VARCHAR(%d)", l)} } -// TypeBytea ... +// TypeBytea is a binary string. func TypeBytea() BaseType { return BaseType{name: "BYTEA"} } @@ -223,7 +236,7 @@ func TypeComposite(name string, attributes ...*Attribute) CompositeType { } } -// EnumeratedType ... +// EnumeratedType is a data type consisting of a set of named values called elements, members, enumeral, or enumerators of the type. // EXPERIMENTAL type EnumeratedType struct { name string @@ -240,7 +253,7 @@ func (et EnumeratedType) Fingerprint() string { return fmt.Sprintf("enumarated: %v", et) } -// TypeEnumerated ... +// TypeEnumerated initializes EnumeratedType with given name and enums. func TypeEnumerated(name string, enums ...string) EnumeratedType { return EnumeratedType{ name: name, @@ -265,14 +278,15 @@ func (pt PseudoType) Fingerprint() string { return fmt.Sprintf("pseudo: %v", pt) } -// TypePseudo ... +// TypePseudo initializes PseudoType with given name. func TypePseudo(name string) PseudoType { return PseudoType{ name: name, } } -// MappableType ... +// MappableType is a type that can be mapped to other types. +// It allows type MappableType struct { From Type Mapping []Type