Options¶
Options control what protoc-gen-gorm
does. You set them in your .proto
files, as regular
Protocol Buffer Options.
The plugin does nothing by default, you'll have to flag some of your messages to be models first, e.g. set model
to true
.
File Options¶
File options apply to all message types within the .proto
file.
model¶
Sets model
for all messages in the file. See model
below.
Default: false
Example:
validate¶
Sets validate
for all messages in the file. See validate
below.
Default: false
Implies model = true
when set to true
.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
option (gorm.file).validate = true;
crud¶
Sets crud
for all messages in the file. See crud
below.
Default: false
Implies model = true
when set to true
.
Example:
Message Options¶
Message options control generation of model and supporting code for your message types.
model¶
Marks a message as a model so protoc-gen-gorm
generates a Go struct and converter methods for use with GORM v2.
The struct type name is the message's name with "Model" appended.
Default: false
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
}
Generates:
package mypackage
type MyMessageModel struct{ /* ... */ }
func (m *MyMessageModel) ToProto() (*MyMessage, error) { /* ... */ }
func (p *MyMessage) ToModel() (*MyMessageModel, error) { /* ... */ }
validate¶
TODO
Default: false
Implies model = true
when set to true
.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).validate = true;
}
crud¶
Generates supporting types and methods to implement CRUD for your model.
Default: false
Implies model = true
when set to true
.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).crud = true;
}
Generates:
package mypackage
type MyMessageWithDB struct{ /* ... */ }
type CrudGetOption
type CrudListOption
// Attach a GORM DB handle to your message.
func (p *MyMessage) WithDB(db *gorm.DB) MyMessageWithDB
// CRUD support without need to convert to model type and back.
func (c MyMessageWithDB) Create(context.Context) (*MyMessage, error)
func (c MyMessageWithDB) Get(context.Context, opts ...MyMessageGetOption) (*MyMessage, error)
func (c MyMessageWithDB) List(context.Context, opts ...MyMessageListOption) ([]*MyMessage, error)
func (c MyMessageWithDB) Update(context.Context) (*MyMessage, error)
func (c MyMessageWithDB) Patch(context.Context, mask *fieldmaskpb.FieldMask) error
func (c MyMessageWithDB) Delete(context.Context) error
table¶
Set the table name for models of this type.
Default: Unset, uses the GORM default.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message) = {
model: true,
table: "mytable"
};
}
The generated struct now implements GORM's Tabler interface:
package mypackage
type MyMessageModel struct {
// ...
}
func (m *MyMessageModel) TableName() string {
return "mytable"
}
Field Options¶
Field options refine how your generated model works with GORM through struct field tags and supporting code.
column¶
Sets the database column name.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).column = "my_column"
];
}
Equivalent GORM struct field tag:
not_null¶
Specifies the field's column as "NOT NULL". See "not null" under GORM: Field Tags.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).not_null = true
];
}
Equivalent GORM struct field tag:
default¶
Sets the default value for the field's column. See "default" under GORM: Field Tags.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).default = "a default value"
];
}
Equivalent GORM struct field tag:
package mypackage
type MyMessageModel struct {
MyField string `gorm:"default:\"a default value\""`
}
unique¶
Flags the field's column to be indexed with a unique indep. See GORM: Indexes.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).unique = true
];
}
Equivalent GORM struct field tag:
primary_key¶
Makes the field a primary key.
Also see:
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string uuid = 1 [
(gorm.field).primary_key = true
];
}
Equivalent GORM struct field tag:
index¶
Adds an index to a field. Composite and multiple indexes are possible.
default¶
Use defaults for the index, e.g. name, type, etc.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).index = {default: true}
];
}
Equivalent GORM struct field tag:
name¶
Gives the index a custom name.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).index = {name: "my_index_name"}
];
}
Equivalent GORM struct field tag:
unique_index¶
Same as index
above except that the index is unique.
default¶
Use defaults for the unique index, e.g. name, type, etc.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).unique_index = {default: true}
];
}
Equivalent GORM struct field tag:
name¶
Gives the unique index a custom name.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).unique_index = {name: "my_index_name"}
];
}
Equivalent GORM struct field tag:
auto_create_time¶
Instructs GORM to track creation time in the flagged field.
Example:
syntax = "proto3";
import "google/protobuf/timestamp.proto";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
google.protobuf.Timestamp my_time = 1 [
(gorm.field).auto_create_time = true
];
}
Equivalent GORM struct field tag:
package mypackage
import (
"database/sql"
)
type MyMessageModel struct {
MyTime sql.NullTime `gorm:"autoCreateTime"`
}
auto_update_time¶
Instructs GORM to track update time in the flagged field.
Example:
syntax = "proto3";
import "google/protobuf/timestamp.proto";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
google.protobuf.Timestamp my_time = 1 [
(gorm.field).auto_update_time = true
];
}
Equivalent GORM struct field tag:
package mypackage
import (
"database/sql"
)
type MyMessageModel struct {
MyTime sql.NullTime `gorm:"autoUpdateTime"`
}
permissions¶
Sets the field level permissions to turn columns into read-only, write-only, create-only, update-only or to ignore a column entirely.
ignore¶
Ignores the column entirely.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_ignored_field = 1 [
(gorm.field).ignore = true
];
}
Equivalent GORM struct field tag:
deny¶
Restricts access to a field. Multiple "denys" can be combined to the desired effect.
create¶
Prevent creation, still allows reads and updates.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).deny = {create: true}
];
}
Equivalent GORM struct field tag:
update¶
Prevent updates, still allows creation and reads.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).deny = {update: true}
];
}
Equivalent GORM struct field tag:
read¶
Prevent reads, still allows writes.
Example:
syntax = "proto3";
import "gorm/options.proto";
package mypackage;
message MyMessage {
option (gorm.message).model = true;
string my_field = 1 [
(gorm.field).deny = {read: true}
];
}
Equivalent GORM struct field tag:
json¶
Encode and decode the field as JSON strings.
The converter methods, MyMessageModel.ToProto()
and MyMessage.ToModel()
in this case, call json.Unmarshal
and json.Marshal
respectively to decode the field's contents.
Example: