Documentation
¶
Overview ¶
Package models provides proto model annotation parsing, code generation, and ORM integration for buffalo.models.
It generates typed model classes / structs for Go, Python, C++, and Rust from protobuf messages annotated with [(buffalo.models.model)] and [(buffalo.models.field)]. The generation output varies depending on the configured ORM plugin (e.g. pydantic, sqlalchemy, gorm, diesel).
Index ¶
- func CheckORMDependencies(lang, ormRaw string) []string
- func GenerateModels(protoFiles []string, lang, ormRaw, outputDir, pkg string, fromProto ...bool) ([]string, error)
- func NewModelsPlugin(log *logger.Logger) plugin.Plugin
- type CheckDef
- type CppNoneGenerator
- func (g *CppNoneGenerator) GenerateBaseModel(_ GenerateOptions) (GeneratedFile, error)
- func (g *CppNoneGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *CppNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *CppNoneGenerator) Language() string
- func (g *CppNoneGenerator) ORMName() string
- type EnumDef
- type EnumValue
- type FieldBehavior
- type FieldDef
- type FieldVisibility
- type GenerateOptions
- type GeneratedFile
- type GoGORMGenerator
- func (g *GoGORMGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
- func (g *GoGORMGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *GoGORMGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *GoGORMGenerator) Language() string
- func (g *GoGORMGenerator) ORMName() string
- type GoNoneGenerator
- func (g *GoNoneGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
- func (g *GoNoneGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *GoNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *GoNoneGenerator) Language() string
- func (g *GoNoneGenerator) ORMName() string
- type GoSQLXGenerator
- func (g *GoSQLXGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
- func (g *GoSQLXGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *GoSQLXGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *GoSQLXGenerator) Language() string
- func (g *GoSQLXGenerator) ORMName() string
- type IndexDef
- type IndexType
- type ModelCodeGenerator
- type ModelDef
- type ModelsPlugin
- func (p *ModelsPlugin) Description() string
- func (p *ModelsPlugin) Execute(ctx context.Context, input *plugin.Input) (*plugin.Output, error)
- func (p *ModelsPlugin) Init(cfg plugin.Config) error
- func (p *ModelsPlugin) Name() string
- func (p *ModelsPlugin) Shutdown() error
- func (p *ModelsPlugin) Type() plugin.PluginType
- func (p *ModelsPlugin) Version() string
- type ORMPlugin
- type OnAction
- type PythonNoneGenerator
- func (g *PythonNoneGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
- func (g *PythonNoneGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *PythonNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *PythonNoneGenerator) Language() string
- func (g *PythonNoneGenerator) ORMName() string
- type PythonPydanticGenerator
- func (g *PythonPydanticGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
- func (g *PythonPydanticGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *PythonPydanticGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *PythonPydanticGenerator) Language() string
- func (g *PythonPydanticGenerator) ORMName() string
- type PythonSQLAlchemyGenerator
- func (g *PythonSQLAlchemyGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
- func (g *PythonSQLAlchemyGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
- func (g *PythonSQLAlchemyGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *PythonSQLAlchemyGenerator) Language() string
- func (g *PythonSQLAlchemyGenerator) ORMName() string
- type RelationDef
- type RelationType
- type RustDieselGenerator
- func (g *RustDieselGenerator) GenerateBaseModel(_ GenerateOptions) (GeneratedFile, error)
- func (g *RustDieselGenerator) GenerateInit(models []ModelDef, _ GenerateOptions) (GeneratedFile, error)
- func (g *RustDieselGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *RustDieselGenerator) Language() string
- func (g *RustDieselGenerator) ORMName() string
- type RustNoneGenerator
- func (g *RustNoneGenerator) GenerateBaseModel(_ GenerateOptions) (GeneratedFile, error)
- func (g *RustNoneGenerator) GenerateInit(models []ModelDef, _ GenerateOptions) (GeneratedFile, error)
- func (g *RustNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
- func (g *RustNoneGenerator) Language() string
- func (g *RustNoneGenerator) ORMName() string
- type UniqueDef
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckORMDependencies ¶
CheckORMDependencies validates that ORM dependencies are available.
func GenerateModels ¶
func GenerateModels(protoFiles []string, lang, ormRaw, outputDir, pkg string, fromProto ...bool) ([]string, error)
GenerateModels is a standalone entry point for the CLI. It reads proto files, parses models, and generates code for the specified language. When fromProto is true, ALL messages are extracted (not just annotated ones).
Types ¶
type CppNoneGenerator ¶
type CppNoneGenerator struct{}
CppNoneGenerator generates plain C++ structs with optional JSON serialization.
func (*CppNoneGenerator) GenerateBaseModel ¶
func (g *CppNoneGenerator) GenerateBaseModel(_ GenerateOptions) (GeneratedFile, error)
func (*CppNoneGenerator) GenerateInit ¶
func (g *CppNoneGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*CppNoneGenerator) GenerateModel ¶
func (g *CppNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*CppNoneGenerator) Language ¶
func (g *CppNoneGenerator) Language() string
func (*CppNoneGenerator) ORMName ¶
func (g *CppNoneGenerator) ORMName() string
type FieldBehavior ¶
type FieldBehavior int
FieldBehavior mirrors the proto enum FieldBehavior.
const ( BehaviorDefault FieldBehavior = 0 BehaviorReadOnly FieldBehavior = 1 BehaviorWriteOnly FieldBehavior = 2 BehaviorImmutable FieldBehavior = 3 BehaviorComputed FieldBehavior = 4 BehaviorVirtual FieldBehavior = 5 BehaviorOutputOnly FieldBehavior = 6 BehaviorInputOnly FieldBehavior = 7 )
func (FieldBehavior) String ¶
func (b FieldBehavior) String() string
type FieldDef ¶
type FieldDef struct {
// Proto source
Name string // proto field name (snake_case)
ProtoType string // proto type (string, int32, etc.)
Number int // proto field number
Repeated bool // repeated field
// Map field support: map<KeyType, ValueType>
IsMap bool // true when the field is a proto map
MapKeyType string // key type for map fields (e.g. "string")
MapValueType string // value type for map fields (e.g. "string")
// Oneof support
OneofGroup string // name of the oneof group this field belongs to
// From [(buffalo.models.field)]
Alias string
Description string
PrimaryKey bool
AutoIncrement bool
Nullable bool
Unique bool
DefaultValue string
MaxLength int32
MinLength int32
Precision int32
Scale int32
CustomType string
DBType string
Visibility FieldVisibility
Behavior FieldBehavior
Sensitive bool
Deprecated bool
DeprecatedMessage string
Index bool
IndexType IndexType
JSONName string
XMLName string
OmitEmpty bool
Relation *RelationDef
Example string
Comment string
AutoGenerate bool
AutoNow bool
AutoNowAdd bool
Sequence string
Collation string
Ignore bool
DBIgnore bool
APIIgnore bool
Tags []string
Metadata map[string]string
}
FieldDef represents a parsed field within a model.
func (*FieldDef) EffectiveJSONName ¶
EffectiveJSONName returns the serialization name for JSON.
func (*FieldDef) IsPersistable ¶
IsPersistable returns true if the field should be included in DB operations.
func (*FieldDef) IsSerializable ¶
IsSerializable returns true if the field should be included in serialization.
type FieldVisibility ¶
type FieldVisibility int
FieldVisibility mirrors the proto enum FieldVisibility.
const ( VisibilityDefault FieldVisibility = 0 VisibilityPublic FieldVisibility = 1 VisibilityInternal FieldVisibility = 2 VisibilityExternal FieldVisibility = 3 VisibilityPrivate FieldVisibility = 4 VisibilityProtected FieldVisibility = 5 )
func (FieldVisibility) String ¶
func (v FieldVisibility) String() string
type GenerateOptions ¶
type GenerateOptions struct {
// Language target (go, python, cpp, rust).
Language string
// ORM plugin to use.
ORM ORMPlugin
// Output directory for generated models.
OutputDir string
// Package / module name.
Package string
// BaseModelFields — extra fields injected into BaseModel.
BaseModelFields []FieldDef
// GenerateBaseModel — whether to emit a BaseModel class/struct.
GenerateBaseModel bool
// GenerateInit — generate __init__.py for Python.
GenerateInit bool
// FixImports — fix relative imports for Python.
FixImports bool
// PreserveProtoStructure — mirror proto directory structure.
PreserveProtoStructure bool
// Verbose — emit extra comments in generated code.
Verbose bool
}
GenerateOptions controls the code generation process.
type GeneratedFile ¶
type GeneratedFile struct {
Path string // Relative output path (e.g. "models/user.py")
Content string // Generated source code
}
GeneratedFile represents a single generated source file.
type GoGORMGenerator ¶
type GoGORMGenerator struct{}
GoGORMGenerator generates GORM-tagged Go structs.
func (*GoGORMGenerator) GenerateBaseModel ¶
func (g *GoGORMGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
func (*GoGORMGenerator) GenerateInit ¶
func (g *GoGORMGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*GoGORMGenerator) GenerateModel ¶
func (g *GoGORMGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*GoGORMGenerator) Language ¶
func (g *GoGORMGenerator) Language() string
func (*GoGORMGenerator) ORMName ¶
func (g *GoGORMGenerator) ORMName() string
type GoNoneGenerator ¶
type GoNoneGenerator struct{}
GoNoneGenerator generates plain Go structs with json tags.
func (*GoNoneGenerator) GenerateBaseModel ¶
func (g *GoNoneGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
func (*GoNoneGenerator) GenerateInit ¶
func (g *GoNoneGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*GoNoneGenerator) GenerateModel ¶
func (g *GoNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*GoNoneGenerator) Language ¶
func (g *GoNoneGenerator) Language() string
func (*GoNoneGenerator) ORMName ¶
func (g *GoNoneGenerator) ORMName() string
type GoSQLXGenerator ¶
type GoSQLXGenerator struct{}
GoSQLXGenerator generates Go structs with db tags for sqlx.
func (*GoSQLXGenerator) GenerateBaseModel ¶
func (g *GoSQLXGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
func (*GoSQLXGenerator) GenerateInit ¶
func (g *GoSQLXGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*GoSQLXGenerator) GenerateModel ¶
func (g *GoSQLXGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*GoSQLXGenerator) Language ¶
func (g *GoSQLXGenerator) Language() string
func (*GoSQLXGenerator) ORMName ¶
func (g *GoSQLXGenerator) ORMName() string
type IndexDef ¶
type IndexDef struct {
Name string
Columns []string
Unique bool
Type IndexType
Where string // partial index condition
Comment string
}
IndexDef describes a composite index.
type ModelCodeGenerator ¶
type ModelCodeGenerator interface {
// Language returns the target language identifier ("go", "python", etc.).
Language() string
// ORMName returns the ORM / framework name ("None", "pydantic", "gorm", etc.).
ORMName() string
// GenerateBaseModel produces the base model class / struct.
GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
// GenerateModel produces a single model file from a ModelDef.
GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
// GenerateInit produces __init__.py or mod.rs or similar index file.
// May return empty file if not applicable for the language.
GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
}
ModelCodeGenerator generates model source code for a target language + ORM.
func NewModelCodeGenerator ¶
func NewModelCodeGenerator(language string, orm ORMPlugin) (ModelCodeGenerator, error)
NewModelCodeGenerator creates a code generator for the given language + ORM.
type ModelDef ¶
type ModelDef struct {
// Proto source
MessageName string // original proto message name
Package string // proto package (e.g. "myservice")
FilePath string // source .proto file path
// Model-level options (from [(buffalo.models.model)])
Name string // class/struct name override
TableName string // optional DB table name
Schema string // optional DB schema
Description string // docstring
Tags []string // arbitrary tags
Abstract bool // abstract model
Extends string // parent model name
Mixins []string // mixin model names
SoftDelete bool // add deleted_at
Timestamps bool // add created_at / updated_at
Deprecated bool // deprecated model
DeprecatedMessage string
Generate []string // what to generate: "model", "repo", "factory"
// Composite constraints
Indexes []IndexDef
Uniques []UniqueDef
Checks []CheckDef
// Nested enums within this message
Enums []EnumDef
// Fields (ordered)
Fields []FieldDef
}
ModelDef represents a parsed model definition from a proto message.
func ExtractAllMessages ¶ added in v1.21.2
ExtractAllMessages scans a full proto file and returns ModelDefs for EVERY message, regardless of whether it has buffalo.models annotations. This is the "generate_models_from_proto" mode: plain proto messages become models with auto-derived settings. Annotated messages get their annotations applied on top.
Service definitions are skipped. Nested enums are extracted into ModelDef.Enums. map<K,V> fields are represented with IsMap=true, MapKeyType, MapValueType.
func ExtractModels ¶
ExtractModels scans a full proto file text and returns ModelDefs for every message that has a [(buffalo.models.model)] annotation.
func ListModelAnnotations ¶
ListModelAnnotations scans proto files and returns parsed ModelDef without generating. When fromProto is true, ALL messages are returned (not just annotated ones).
func (*ModelDef) EffectiveName ¶
EffectiveName returns the model name: Name override or MessageName.
type ModelsPlugin ¶
type ModelsPlugin struct {
// contains filtered or unexported fields
}
ModelsPlugin implements plugin.Plugin and generates typed code models from buffalo.models annotations in proto files.
func (*ModelsPlugin) Description ¶
func (p *ModelsPlugin) Description() string
func (*ModelsPlugin) Execute ¶
Execute parses proto files for buffalo.models annotations and generates model source code for each enabled language.
func (*ModelsPlugin) Name ¶
func (p *ModelsPlugin) Name() string
func (*ModelsPlugin) Shutdown ¶
func (p *ModelsPlugin) Shutdown() error
func (*ModelsPlugin) Type ¶
func (p *ModelsPlugin) Type() plugin.PluginType
func (*ModelsPlugin) Version ¶
func (p *ModelsPlugin) Version() string
type ORMPlugin ¶
type ORMPlugin struct {
Name string // "None", "pydantic", "sqlalchemy", "gorm", "diesel", etc.
Version string // optional required version (e.g. "2.0")
}
ORMPlugin describes which ORM framework to use for generation.
func ParseORMPlugin ¶
ParseORMPlugin parses "plugin_name[@version]" notation.
Examples:
"default" → {Name: "None", Version: ""}
"None" → {Name: "None", Version: ""}
"pydantic" → {Name: "pydantic", Version: ""}
"pydantic@2.0" → {Name: "pydantic", Version: "2.0"}
"" → {Name: "None", Version: ""}
type PythonNoneGenerator ¶
type PythonNoneGenerator struct{}
PythonNoneGenerator generates pure Python dataclasses.
func (*PythonNoneGenerator) GenerateBaseModel ¶
func (g *PythonNoneGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
func (*PythonNoneGenerator) GenerateInit ¶
func (g *PythonNoneGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*PythonNoneGenerator) GenerateModel ¶
func (g *PythonNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*PythonNoneGenerator) Language ¶
func (g *PythonNoneGenerator) Language() string
func (*PythonNoneGenerator) ORMName ¶
func (g *PythonNoneGenerator) ORMName() string
type PythonPydanticGenerator ¶
type PythonPydanticGenerator struct {
// contains filtered or unexported fields
}
PythonPydanticGenerator uses pydantic BaseModel.
func (*PythonPydanticGenerator) GenerateBaseModel ¶
func (g *PythonPydanticGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
func (*PythonPydanticGenerator) GenerateInit ¶
func (g *PythonPydanticGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*PythonPydanticGenerator) GenerateModel ¶
func (g *PythonPydanticGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*PythonPydanticGenerator) Language ¶
func (g *PythonPydanticGenerator) Language() string
func (*PythonPydanticGenerator) ORMName ¶
func (g *PythonPydanticGenerator) ORMName() string
type PythonSQLAlchemyGenerator ¶
type PythonSQLAlchemyGenerator struct {
// contains filtered or unexported fields
}
PythonSQLAlchemyGenerator generates SQLAlchemy ORM models.
func (*PythonSQLAlchemyGenerator) GenerateBaseModel ¶
func (g *PythonSQLAlchemyGenerator) GenerateBaseModel(opts GenerateOptions) (GeneratedFile, error)
func (*PythonSQLAlchemyGenerator) GenerateInit ¶
func (g *PythonSQLAlchemyGenerator) GenerateInit(models []ModelDef, opts GenerateOptions) (GeneratedFile, error)
func (*PythonSQLAlchemyGenerator) GenerateModel ¶
func (g *PythonSQLAlchemyGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*PythonSQLAlchemyGenerator) Language ¶
func (g *PythonSQLAlchemyGenerator) Language() string
func (*PythonSQLAlchemyGenerator) ORMName ¶
func (g *PythonSQLAlchemyGenerator) ORMName() string
type RelationDef ¶
type RelationDef struct {
Type RelationType
Model string // target model name
ForeignKey string
References string // default "id"
JoinTable string // for many_to_many
OnDelete OnAction
OnUpdate OnAction
Eager bool
Through string // intermediate model
InverseOf string // inverse relation field
}
RelationDef describes a relationship between models.
type RelationType ¶
type RelationType int
RelationType mirrors the proto enum RelationType.
const ( RelationUnspecified RelationType = 0 RelationBelongsTo RelationType = 1 RelationHasOne RelationType = 2 RelationHasMany RelationType = 3 RelationManyToMany RelationType = 4 )
func (RelationType) String ¶
func (r RelationType) String() string
type RustDieselGenerator ¶
type RustDieselGenerator struct {
// contains filtered or unexported fields
}
RustDieselGenerator generates Diesel-annotated Rust structs.
func (*RustDieselGenerator) GenerateBaseModel ¶
func (g *RustDieselGenerator) GenerateBaseModel(_ GenerateOptions) (GeneratedFile, error)
func (*RustDieselGenerator) GenerateInit ¶
func (g *RustDieselGenerator) GenerateInit(models []ModelDef, _ GenerateOptions) (GeneratedFile, error)
func (*RustDieselGenerator) GenerateModel ¶
func (g *RustDieselGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*RustDieselGenerator) Language ¶
func (g *RustDieselGenerator) Language() string
func (*RustDieselGenerator) ORMName ¶
func (g *RustDieselGenerator) ORMName() string
type RustNoneGenerator ¶
type RustNoneGenerator struct{}
RustNoneGenerator generates plain Rust structs with serde derives.
func (*RustNoneGenerator) GenerateBaseModel ¶
func (g *RustNoneGenerator) GenerateBaseModel(_ GenerateOptions) (GeneratedFile, error)
func (*RustNoneGenerator) GenerateInit ¶
func (g *RustNoneGenerator) GenerateInit(models []ModelDef, _ GenerateOptions) (GeneratedFile, error)
func (*RustNoneGenerator) GenerateModel ¶
func (g *RustNoneGenerator) GenerateModel(model ModelDef, opts GenerateOptions) ([]GeneratedFile, error)
func (*RustNoneGenerator) Language ¶
func (g *RustNoneGenerator) Language() string
func (*RustNoneGenerator) ORMName ¶
func (g *RustNoneGenerator) ORMName() string