Expand description
A wrapper crate to make writing SQL user-defined functions (UDFs) easy
This crate provides bindings for easy creation of SQL user-defined functions in Rust. See the readme for more background information on how UDFs work in general.
Usage
Using this crate is fairly simple: create a struct that will be used to
share data among UDF function calls (which can be zero-sized), then
implement needed traits for it. BasicUdf
provides function signatures
for standard UDFs, and AggregateUdf
provides signatures for aggregate
(and window) UDFs. See the documentation there for a step-by-step guide.
use udf::prelude::*;
// Our struct that will produce a UDF of name `my_udf`
// If there is no data to store between calls, it can be zero sized
struct MyUdf;
#[register]
impl BasicUdf for MyUdf {
// Specify return type of this UDF to be a nullable integer
type Returns<'a> = Option<i64>;
// Perform initialization steps here
fn init(cfg: &UdfCfg<Init>, args: &ArgList<Init>) -> Result<Self, String> {
todo!();
}
// Create a result here
fn process<'a>(
&'a mut self,
cfg: &UdfCfg<Process>,
args: &ArgList<Process>,
error: Option<NonZeroU8>,
) -> Result<Self::Returns<'a>, ProcessError> {
todo!();
}
}
Building & Usage
The above example will create three C-callable functions: my_udf
,
my_udf_init
, and my_udf_deinit
, which is what MariaDB
and MySql
expect for UDFs. To create a C dynamic library (as is required for usage),
add the following to your Cargo.toml
[lib]
crate-type = ["cdylib"]
The next time you run cargo build --release
, in target/release
there
will be a shared library .so
file. Copy this to your plugin_dir
location
(usually /usr/lib/mysql/plugin/
), and load the function with the
following:
CREATE FUNCTION my_udf RETURNS integer SONAME 'libudf_test.so';
Replace my_udf
with the function name, integer
with the return type, and
libudf_test.so
with the correct file name.
More details on building are discussed in the project
readme. See the
MariaDB
documentation for
more detailed information on how to load the created libraries.
Crate Features
This crate includes some optional features. They can be enabled in your
Cargo.toml
.
mock
: enable this feature to add the mock module for easier unit testing. (note: this feature will become unneeded in the future andmock
will be available by default. It is currently feature-gated because it is considered unstable.)logging-debug
: enable this feature to turn on debug level logging for this crate. This uses theudf_log!
macro and includes information about memory management and function calls. These will show up with your SQL server logs.logging-debug-calls
full debugging printing of the structs passed between this library and the SQL server. Implieslogging-debug
.
Version Note
Because of reliance on a feature called GATs, this library requires Rust version >= 1.65. This only became stable on 2022-11-03; if you encounter issues compiling, be sure to update your toolchain.
Modules
mock
use udf::prelude::*;
to quickly get the
most often used imports.Macros
MockArgList
stderr
to display in server logsStructs
Enums
max_length
parameter