Submit a Community Extension
Communinity Extensions must be public, open-source, and hosted on GitHub. Users of such extensions are encouraged to check the relevant extension repository for giving feedback, to look at the implementation, and to report issues.
To submit a Community Extension, please open a pull request to the Community Extensions Repository with a single description.yml file in the folder extensions/⟨name_of_the_extension⟩.
YAML Descriptor
The structure of the YAML descriptor is as follows:
| Field | Description |
|---|---|
extension.name |
Name of the extension. Extension names are case-insensitive, so only lowercase letters, numbers and - or _ are allowed |
extension.description |
Short description of the extension |
extension.version |
Semantic versioning of the extension |
extension.language |
C++, Rust & C++, C++ & SQL, or whatever combination of languages the extension code relies on |
extension.build |
Build system the extension uses, at the moment only cmake is supported |
extension.licence |
Licence that applies to the extension |
extension.maintainers |
A list of maintainers for the extension |
extension.excluded_platforms |
Optional, allows to specify whether certain platforms are not supported |
extension.requires_toolchains |
Optional, allows to specify whether additional build-time dependecies are required |
repo.github |
Organization name '/' Repository name of the GitHub-hosted public repository |
repo.ref |
Git ref for the extension |
These fields are used to build, test and deploy the extension, and might also be reflected in the documentation.
Extensions maintainers are encouraged to provide two optional fields in the descriptor, to be only used in the autogenerated documentation:
| Field | Description |
|---|---|
docs.hello_world |
A Hello, World! code snippet, i.e., a self contained example of an extension capabilities |
docs.extended_description |
Extra context on the extension, relevant links, or a tour of the extension capabilities |
Hosted Extension Documentation Page
Each Community Extension has a documentation page at https://duckdb.org/community_extensions/extensions/⟨extension_name⟩. For example, this is the page for quack.
Documentation pages are generated from the fields provided in the YAML descriptor file that is part of the Community Extensions Repository and from the auto-detected changes that a given extension introduces in DuckDB.
The process is roughly as follows:
CREATE TABLE functions_pre AS SELECT ... FROM duckdb_functions();
LOAD extension_name;
CREATE TABLE functions_post AS SELECT ... FROM duckdb_functions();
SELECT * FROM functions_pre EXCEPT (FROM functions_post) ORDER BY ...;
This works well for detecting new functions, functions overload, new settings, and new types.
Detection of other changes to the system (e.g., whether an additional parser or optimizer callback has been registered) are viable, but not yet implemented. Those are recommended to be provided as part of the docs.extended_description field.
List of Extensions
All the available community extensions are listed in the “List of Community Extensions” page.