Adding a New Data Type to MariaDB with Type_handler – Part 1

This is the first part of the series about how to add a new data type to MariaDB using the Type_handler framework. A preliminary article has already been published to start the series; it covers how to set up your development environment and compile MariaDB Server: Adding a New Data Type to MariaDB with Type_handler – Part 0.

Understand Type_handler Before Writing Code

When you add a new type to MariaDB, you are not only adding a new SQL keyword. Historically, that kind of work required invasive changes across the parser, optimizer, protocol, replication, and type-conversion mechanisms.

The point of the pluggable type framework is to replace that scattered surgery with one uniform abstraction: Type_handler.

This design goal deserves to be clearly stated: MariaDB does not wish to make a conceptual distinction between “native” and “plug-in” types. Just as storage engines are all plug-ins within a common framework, data types are also expected to adhere to a uniform interface.

From there, you need to teach the server a small set of related behaviors:

• how a column of that type is represented,
• how values are stored and read,
• how values are exposed to clients,
• how the type interacts with other types in expressions.

Thanks to this new type of architecture, it is much easier to understand these responsibilities. Instead of treating a type as a single, giant, opaque object, MariaDB divides the work across a few components.

That is why Type_handler is such a good place to start.

The short mental model

For this series, keep this model in mind:

• Type_handler_ gives the type its identity and acts as the factory.
• Field_ implements runtime storage and behavior for a column value.
• Type_collection_ decides how the type combines with other types.
• the plugin declaration registers the type so the server can load it.

If you need to remember one sentence, it should be this:

A custom MariaDB type needs to answer three questions: how to build the field, how to store and read values, and how to behave in expressions.

Why this architecture matters

The deep value of the framework lies not only in extensibility but also in coverage.

In the old world, adding a new data type required modifying numerous independent code paths, while hoping not to overlook any. In the new world, the server is structured such that, if the Type_handler interface is complete, the main type-specific behavior is taken into account from the design phase.

The four components in our plugin

To add our new MONEY data type, we will need to prepare 4 major components.

1. Type_handler_money

This class defines the type’s identity.

In our minimal version, Type_handler_money inherits from Type_handler_newdecimal to focus on the plugin architecture rather than implementing every numeric behavior from scratch.

The single most important method is:

Field *Type_handler_money::make_table_field_from_def(TABLE_SHARE *share,
                                 MEM_ROOT *root,
                                 const LEX_CSTRING *name,
                                 const Record_addr &rec,
                                 const Bit_addr &bit,
                                 const Column_definition_attributes *attr,
                                 uint32 flags) const override;

This is the bridge between SQL and runtime behavior.

When MariaDB parses a column definition like:

amount MONEY(12,2)

This method is where the server turns that definition into a real Field_money object.

2. Field_money

This is where the runtime behavior lives.

If Type_handler_money answers “what type is this?”, then Field_money answers “what does this type do?”.

In our minimal version, Field_money is responsible for:

• accepting text or numeric input,
• rounding to the declared scale,
• checking range,
• storing the value internally,
• returning the value in numeric or string form,
• comparing two values,
• generating a sort key,
• describing how the value is sent to clients.

3. Type_collection_money

This is the piece many people overlook.

It controls coercion and aggregation rules in expressions such as:

SELECT amount + 1;
SELECT amount + 1.5;
SELECT amount = 10;

The server needs to know what common type to use when MONEY meets INT, DOUBLE, or DECIMAL. Those rules belong in Type_collection_money.

4. Plugin registration

Finally, the plugin declaration exposes the type to the server:

static struct st_mariadb_data_type plugin_descriptor_type_money=
{
  MariaDB_DATA_TYPE_INTERFACE_VERSION,
  &type_handler_money
};

maria_declare_plugin(type_money)
{
  MariaDB_DATA_TYPE_PLUGIN,
  &plugin_descriptor_type_money,
  "money",
  "lefred",
  "Data type MONEY",
  PLUGIN_LICENSE_GPL,
  0,
  0,
  0x0001,
  NULL,
  NULL,
  "0.1",
  MariaDB_PLUGIN_MATURITY_EXPERIMENTAL
}
maria_declare_plugin_end;

This is an illustration of a simplified Type_handler architecture:

Conclusion

Now that we are more familiar with the Type_hander architecture, the next article will be dedicated to building a small working new MONEY data type.