Getting Started

Tools

Tool	Version	Use
Rust	stable, 1.85 or later	Builds the native library. The crate uses edition 2024.
Python	3.11 or later	Runs scripts/package-plugin.py. The script uses tomllib.
Git	any	Gets the SDK from the Beacon repository.

A SQL-only plugin needs no Rust.

Make a repository

1. Open maris-development/beacon-plugin-template.
2. Click Use this template. Make a new repository.
3. Clone the new repository.

The wiki is not part of the copy. Keep a link to this wiki.

Files

Path	Contents
beacon-plugin.toml	The plugin manifest.
native/Cargo.toml	The Rust crate. It is a cdylib on beacon-plugin-sdk.
native/Cargo.lock	The lock file. It fixes the SDK commit. The pack script reads the DataFusion version from it.
native/src/lib.rs	The native functions, their unit tests and the export macro.
native/src/tsv.rs	The file format example_tsv and its unit tests.
native/testdata/stations.tsv	A sample file for example_tsv.
native/src/memory.rs	The table type example_memory and its unit tests.
sql/functions.sql	The SQL functions.
scripts/package-plugin.py	Packs the plugin into an archive and writes SHA256SUMS.
.github/workflows/release.yml	Builds and packs the plugin for a tag. Attaches the archives to the GitHub release.

The manifest

[plugin]
name = "example"
version = "0.1.0"
beacon = ">=2.1, <3"

[native]
crate = "native"
library = "example_native"

[sql]
files = ["sql/functions.sql"]

Key	Meaning
plugin.name	The plugin name. Lowercase letters, digits and _. The first character is a letter.
plugin.version	A semantic version. The release tag is v<version>.
plugin.beacon	The Beacon versions that the plugin supports, as a semantic version range.
native.crate	The folder of the Rust crate.
native.library	The base name of the library. It equals lib.name in Cargo.toml.
sql.files	The SQL files, in load order.

A plugin needs [native], [sql] or both. Beacon ignores the pre-release part of its own version. So Beacon 2.1.0-rc.1 matches >=2.1.

Rename the plugin

Change these names. Use the same plugin name in each file.

File	Change
beacon-plugin.toml	plugin.name, plugin.version and native.library.
native/Cargo.toml	package.name and lib.name. lib.name must equal native.library.
native/src/lib.rs	The function names.
native/src/tsv.rs	The format name and the extensions.
native/src/memory.rs	The table type name.
sql/functions.sql	The function names.

Start each function name, format name and table type name with the plugin name. Two plugins cannot have the same function name, format name or table type name. The prefix prevents a collision.

Remove the parts that you do not need

export_plugin! takes the keys scalar, formats and tables, in any order. Give only the keys that the plugin uses.

Plugin has	Change
No file format	Remove native/src/tsv.rs, native/testdata/, mod tsv; and the formats key.
No table type	Remove native/src/memory.rs, mod memory; and the tables key.
No native function	Remove the functions from lib.rs and the scalar key.
No SQL function	Remove [sql] from the manifest and remove sql/.
SQL functions only	Remove [native] from the manifest and remove native/.

async-trait is for the format and table traits. futures is for the format streams. Remove them when no code uses them.

A SQL function can call a native function of the same plugin. Remove both, or keep both.

Choose the Beacon version

native/Cargo.toml gets the SDK from the Beacon Git repository:

beacon-plugin-sdk = { git = "https://github.com/maris-development/beacon", branch = "main" }

The Beacon commit fixes two values in the plugin:

• The SDK ABI. Beacon refuses a plugin with a different SDK ABI.
• The DataFusion version. Beacon refuses a plugin with a different DataFusion FFI major version.

So build the plugin with the SDK of the Beacon version that runs the plugin.

The template uses the branch main, because no Beacon release holds the SDK yet. Cargo.lock fixes the commit. To get a newer commit, run this command in native/:

cargo update -p beacon-plugin-sdk

When a Beacon release holds the SDK, use its tag:

beacon-plugin-sdk = { git = "https://github.com/maris-development/beacon", tag = "v2.1.0" }

Then make plugin.beacon match the Beacon versions with the same SDK ABI and DataFusion version.

Rules for the crate

• Use the crates that the SDK re-exports: beacon_plugin_sdk::datafusion, datafusion_ffi, stabby and object_store::store. Do not add them as dependencies. Then the versions match Beacon.
• Keep panic = "unwind". This is the default. The SDK refuses panic = "abort" at compile time.
• Keep crate-type = ["cdylib"].

Next: Scalar functions or File formats.