Skip to main content
When the server calls a function in an extension, it passes the arguments and reads back the result through a fixed set of C structures. Custom types work the same way: the extension describes each type in a structure that the server reads when you install the extension and each time the server starts. A protocol is a numbered version of those structures and of the rules for filling them in. Each new protocol adds to the structures without moving the fields that an older extension reads, and the server keeps the code that reads each older stable protocol. That is why the server can still load an extension that was built for an older protocol. You do not set the protocol number yourself. The SDK that you build the extension with sets it: each SDK release builds extensions for one stable protocol, and its development headers (-DVSQL_USE_DEV_ABI=ON) build for the development protocol. To move an extension to a newer protocol, rebuild it with a newer SDK.

How the server picks a protocol

When you install an extension, the server offers its newest protocol and the extension declares the protocol that it was built for. The server and the extension then use the lower of the two numbers. For example, a server that offers protocol 4 talks to an extension built for protocol 3 at protocol 3, and it does not give that extension any feature that protocol 4 adds. To see the protocol for each installed extension, query INFORMATION_SCHEMA.EXTENSION_REGISTRATION:
The NEGOTIATED_PROTOCOL column holds the protocol that the server and the extension agreed on.

Stable and development protocols

Odd-numbered protocols are stable. Today the server accepts every stable protocol, back to protocol 1, so an extension that you built for a stable protocol keeps installing on newer servers without a rebuild. Even-numbered protocols are development versions. The server accepts only its own development protocol, and the structures of that protocol can change between two server builds. An extension built with the development headers (-DVSQL_USE_DEV_ABI=ON) can stop working after you update the server. If it does, rebuild it against the new server. When a release promotes the development protocol to the next stable number, the server stops accepting the old development number. INSTALL EXTENSION then fails with extension uses obsolete unstable protocol version, followed by the old and current numbers. The same check runs when the server starts, so a server does not start while it has such an extension installed. Before you upgrade the server, rebuild each extension that you built with the development headers against the new release.
Changed in 0.0.8-dev. Protocol 4 becomes stable protocol 5, which SDK 0.0.8 builds. The development headers of 0.0.8 build protocol 6. The server rejects protocol 4, which is unsupported. Protocols 1 and 3 are deprecated: the server still accepts them, but new extensions should use protocol 5.

Protocol 3

SDK 0.0.4 through 0.0.7 build protocol 3 extensions.
Changed in 0.0.8-dev. An extension that you built with one of those SDKs keeps working on newer servers, with the same behavior, and you do not need to rebuild it.If you rebuild it with the 0.0.8 SDK, it moves to protocol 5 and can use these features:
  • .max_result_length(), which sizes the result column of a STRING or BINARY function so that a materialized result isn’t cut off at the width of the argument.
  • Load and unload hooks, .on_init() and .on_deinit().
  • Variable-length custom types, .variable_length_type().
  • The BINARY parameter and result type, for raw bytes.
  • The binary form of a custom type, .from_binary() and .to_binary(), which SQL calls as TYPE::from_binary and TYPE::to_binary.
  • A prerun that sees the values of constant arguments.
  • Type checks at resolution time, .bind_and_check_types().
  • An out.set() that returns a STRING value larger than the buffer in full, where protocol 3 cuts the value off.
  • An exception that leaves a function fails the statement with an error.
One behavior changes when you rebuild: protocol 3 and protocol 5 pass a STRING argument differently. A protocol 3 function gets the bytes of the argument unchanged, in the argument’s own character set. A protocol 5 function gets the argument as utf8mb4 text, which the server converts from the caller’s character set. For example, the latin1 string _latin1 X'E9' (é) reaches a protocol 3 function as the single byte E9, and reaches a protocol 5 function as the two bytes C3 A9. If the argument is a binary string that is not valid utf8mb4, the statement fails:
Before you rebuild, find each function that reads raw bytes from a STRING argument, such as a hash or an encryption function, and declare that parameter as BINARY. The same applies to an extension written in the protocol 1 style.

Protocol 1

Protocol 1 has been stable since 0.0.1. The server still accepts it, but it is likely to be deprecated in a future release. Write new extensions with the typed API in the Creating Extensions in C++ and C++ Development guides. This section is a reference for existing extensions written in the protocol 1 style. A newer SDK still compiles that style, and it builds the extension for its own stable protocol.
Changed in 0.0.8-dev. Protocol 1 is deprecated. The server still accepts it, but new extensions should use protocol 5.

Function-Pointer Type API

Protocol 1 custom types are registered using explicit function pointers instead of the vsql::make_type<> template. The function signatures differ from the typed equivalents. They take raw pointers and lengths, and do not take Arg and Result objects.

Function Signatures

Registration

This form requires #include <villagesql/extension.h> (not <villagesql/vsql.h>) and using namespace villagesql;.
vsql::make_type<kMyTypeName>() (with a compile-time string NTTP) is the preferred form. make_type(MYTYPE) (no template parameter) is the Protocol 1 form — it remains supported but is likely to be deprecated in a future release.

Raw ABI Style (Functions)

Protocol 1 VDF implementations can pass the raw C structs directly instead of using typed wrappers. This style remains supported but is likely to be deprecated in a future release — use the typed argument/result API for all new code.
This per-argument raw signature — void(vef_context_t*, vef_invalue_t* arg0, ..., vef_vdf_result_t*) — is only detected by make_func<>() from <villagesql/extension.h>. The make_func<>() from <villagesql/vsql.h> rejects any raw vef_context_t*/vef_invalue_t*/vef_vdf_result_t* signature at compile time.

Result Constants

The raw ABI communicates result state via vef_return_value_type_t set on result->type: With the typed API, out.set(), out.set_null(), out.warning(), and out.error() handle this automatically.

Aggregate Registration in Protocol 1

The make_func<>() builder from <villagesql/extension.h> has no .clear<>() or .accumulate<>() member. Those methods exist only on the separate make_aggregate_func<State, &result_fn>() builder from <villagesql/vsql.h>, which uses State&-based typed signatures rather than raw vef_context_t*/vef_vdf_args_t* pointers. Use the typed aggregate approach for all new code. A raw registration at VEF_PROTOCOL_3 or higher can also set the clear and accumulate callbacks in vef_func_desc_t by hand.