#How-to: migrating from the built-in require('protobuf')

Tarantool ships an in-tree protobuf module. It's small, encode-only, and predates this project. If you're already using it, this is the side-by-side guide to switching.

The relevant differences:

Both can run in the same process — pb is named differently specifically so they don't collide.

#Translating schemas

The built-in describes messages as Lua tables. Translate them to .proto files for the codegen path, or to inline pb.parse(...) calls for the runtime path.

#Built-in

local p = require('protobuf')
local proto = p.protocol{
    p.message('User', {
        name   = {'string', 1},
        age    = {'int32',  2},
        emails = {'string', 3, 'repeated'},
    }),
    p.enum('Role', {
        USER  = 0,
        ADMIN = 1,
    }),
}

local bytes = proto:encode('User', {name = 'Alice', age = 30, emails = {'a@x'}})

#pb (codegen path)

user.proto:

syntax = "proto3";
package app;

enum Role {
    USER  = 0;
    ADMIN = 1;
}

message User {
    string name = 1;
    int32  age  = 2;
    repeated string emails = 3;
}

protoc --tarantool_out=./gen user.proto then:

local user = require('app.user_pb')
local bytes = user.User_encode({name = 'Alice', age = 30, emails = {'a@x'}})
local back  = user.User_decode(bytes)  -- new capability!

#pb (no-codegen path)

If you want to keep schemas inline in Lua (matches the built-in's ergonomics), use pb.parse:

local pb = require('pb')
local user = pb.parse([[
syntax = "proto3";
package app;
message User {
    string name = 1;
    int32  age  = 2;
    repeated string emails = 3;
}
]])

local bytes = user.User_encode({name = 'Alice', age = 30})
local back  = user.User_decode(bytes)

See how-to: dynamic schemas for the runtime- parse approach.

#API call-site changes

The data shape is the same — translating happens at the schema declaration, not at the encode call sites. A direct find-replace from proto:encode('User', t) to user.User_encode(t) covers most of the migration.

#Behavioral differences

#Defaults

Proto3 elides default values on encode (age = 0 is omitted from the wire, unless the field is explicit-optional). The built-in followed the same proto3 convention — no change.

#Packed repeated

Both encode repeated int32 etc. as packed by default. No change.

#Unknown fields

The built-in didn't decode, so this didn't come up. pb preserves unknown fields by default — they decode into t._unknown_fields (raw bytes) and re-emit on encode. If your producer was encoding extra fields the consumer didn't know about, those now round-trip cleanly through pb.

#Errors

Built-in raised on encode of unknown fields (typo in the table key silently encoded as nothing? or raised? — version-dependent). pb ignores unknown table keys on encode but raises on shape mismatches (wrong Lua type for the declared proto type, etc.).

If you relied on encode-side strictness for typo detection, route field-name accesses through the strict M.User_fields table (only emitted for the lazy view today; eager encoders trust the input shape).

#Things you can do now that you couldn't before

• Decode. User_decode(bytes) round-trips any input the built-in produced (and any input mainline protoc produced).
• Maps and oneofs. Both round-trip.
• WKT. google.protobuf.Timestamp ↔ Tarantool datetime; Duration, wrappers, Struct, Any, FieldMask, Empty.
• Services. Generated *_client / *_server factories with a pluggable transport contract.
• JSON. pb.json.encode / pb.json.decode against the same descriptor.
• Text format. User_text(t) for debug printing.
• Lazy view. User_decode_lazy(b) for proxy/router shapes that touch a few fields and re-encode.
• Runtime schemas. pb.parse / pb.from_pb for descriptors built at runtime.

#What's next

• How-to: first message — the green-field path if you'd rather start fresh.
• Reference: generated API — what User_pb.lua exposes.
• How-to: dynamic schemas — for the inline-schema style the built-in encouraged.