protoc-gen-gorm

README

protoc-gen-gorm

Purpose

A protobuf (https://developers.google.com/protocol-buffers/) compiler plugin designed to simplify the API calls needed to perform simple object persistence tasks. This is currently accomplished by creating a secondary .pb.orm.go file which contains sister objects to those generated in the standard .pb.go file satisfying these criteria:

• These objects are GoLint compatible
• Go field decorators/tags can be defined by option in the .proto file for GORM/SQL
• Converters between pb version and ORM version of the objects are included
• There are options for dropping fields from the pb object, or adding additional fields (not generally recommended, as it reduces clarity of .proto file)

Prerequisites

Dependencies

The protobuf compiler (protoc) is required.

It can be installed from code, with

mkdir tmp
cd tmp
git clone https://github.com/google/protobuf
cd protobuf
./autogen.sh
./configure
make
make check
sudo make install

Though this may require the installation of additional dependencies for the build process.

Then you will need the golang code generator

go get -u github.com/golang/protobuf/protoc-gen-go

Installation

To use this tool, install it from code with make install, go install directly, or go get github.com/infobloxopen/protoc-gen-gorm.

Usage

Once installed, the --gorm_out=. or --gorm_out=${GOPATH}src option can be specified in a protoc command to generate the .pb.gorm.go files.

Any types with the option (orm.opts).ormable = true will have the following autogenerated:

• A struct with GoLinted name, and the "ORM" suffix
• Tags copied from the field options [(orm.field).tags = "..."]
• A Convert*Type*ToORM and Convert*Type*FromORM function.
• Barebones C/R/U/D handlers that accept the protobuf versions (as from an API call), a context (not yet used), and a gorm.DB then perform the basic operation on the DB with the object.

Any services with the option (orm.server).autogen = true will have basic grpc server generated:

• For service methods with names starting with Create|Read|Update|Delete generated implementation will call basic CRUD handlers.
• For other methods return &MethodResponse{}, nil stub is generated.

For CRUD methods to be generated correctly you need to follow specific conventions:

• Ormable Type should be wrapped in Request/Response messages under payload, result or results fields according to the method type.
• Read and Delete methods should have an id field in Request message.
• For Delete method pass (gorm.method).object_type option to indicate which Ormable Type it's related to.

If conventions are not met stubs are generated for CRUD methods. Check out example.

Examples

Example .proto files and generated .pb.gorm.go files are included in the 'example' directory. The contacts/contacts.proto mirrors the example project in github.com/infobloxopen/atlas-contacts-app, while the feature_demo/* files demonstrate most of the currently implemented behaviors of this tool.

Running make example will recompile all these test proto files, if you want to test the effects of changing the options and fields.

Limitations

Currently only proto3 is supported.

This project is currently in pre-alpha, and is expected to undergo "breaking" (and fixing) changes