Evolving Schemas Safely

Rules for changing messages

Protobuf supports compatible evolution if you follow the rules. Safe: adding new fields with new numbers (old code ignores unknown fields), adding enum values (with care for old clients), adding new RPC methods. Unsafe: changing a field's number or type, reusing a deleted field's number or name, renaming packages or services. When removing a field, mark its number and name reserved so they are never reused. Tools such as buf breaking check changes against the previous version automatically.

Removing a field safely

Reserve the old number and name.

message Order {
  reserved 6;                 // was coupon_code
  reserved "coupon_code";
  string id = 1;
  string customer_id = 2;
  repeated OrderItem items = 3;
  int64 total_cents = 4;
  string currency = 5;
  repeated string promotion_ids = 7;   // new field, new number
}

Version packages for breaking changes

Put breaking redesigns in a new package such as shop.v2 and run both versions during migration.

Quick check: Which protobuf change is safe?

• Changing a field from string to int64
• Changing an existing field's number
• Reusing a deleted field's number
• Adding a new field with a new number