Skip to main content

quack_rs/validate/
extension_name.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Extension name validation per `DuckDB` community extension rules.
7//!
8//! An extension name must match `^[a-z][a-z0-9_]*$` — a lowercase letter
9//! followed by lowercase letters, digits and underscores.
10//!
11//! # Why no hyphens
12//!
13//! The name is not just a label. The community build names the binary
14//! `<name>.duckdb_extension`, and `DuckDB`'s loader (`TryInitialLoad` and
15//! `LoadExternalExtension` in `src/main/extension/extension_load.cpp`, v1.5.5)
16//! takes the file's base name, lowercases it, and looks up the entry point
17//! `<base name>_init_c_api` in the library. A hyphen would have to appear in
18//! that C symbol, which neither C nor Rust can define — so a hyphenated
19//! extension can never load, and the scaffold would generate
20//! `entry_point!(my-ext_init_c_api, …)`, which does not even compile. None of
21//! the 395 published community extensions uses a hyphen.
22//!
23//! # Names that are taken
24//!
25//! A well-formed name may still be unusable for a community extension.
26//! [`validate_community_extension_name`] also refuses:
27//!
28//! - [`DUCKDB_EXTENSION_ALIASES`]: `DuckDB` rewrites these to another
29//!   extension's name before `INSTALL` and `LOAD`
30//!   (`ExtensionHelper::ApplyExtensionAlias`), so `INSTALL s3 FROM community`
31//!   downloads `httpfs` — an extension named `s3` can never be installed or
32//!   loaded by its name;
33//! - [`DUCKDB_CORE_EXTENSION_NAMES`]: the community-extensions FAQ says "if a
34//!   core `DuckDB` extension of the same name exists or is created, the
35//!   community extension of the same name has to be renamed".
36//!
37//! Sources, read 2026-10-30: `src/main/extension/extension_alias.cpp`,
38//! `internal_extensions[]` in `src/main/extension/extension_helper.cpp` and
39//! `AUTOLOADABLE_EXTENSIONS` in `src/include/duckdb/main/extension_entries.hpp`
40//! at `DuckDB` v1.4.4, v1.5.6 and v2.0.0 (`main` had the same aliases), and the
41//! core-extension table of `docs/2.0/core_extensions/overview.md` in
42//! `duckdb/duckdb-web`. `scripts/check-extension-names.py` fetches them again
43//! in CI and fails when they and these lists disagree. None of the 395
44//! community extensions in `duckdb/community-extensions` (`845779e`) has a name
45//! listed here.
46//!
47//! Uniqueness among community extensions is not checked: that is the
48//! author's to look up (`extensions/` in `duckdb/community-extensions`).
49//!
50//! # Reference
51//!
52//! <https://duckdb.org/community_extensions/development>,
53//! <https://duckdb.org/community_extensions/faq>
54
55use crate::error::ExtensionError;
56
57/// `DuckDB`'s built-in extension aliases, as `(alias, extension)`.
58///
59/// `INSTALL` and `LOAD` replace the alias with the extension's name, so a
60/// community extension called by an alias can never be installed or loaded.
61///
62/// `src/main/extension/extension_alias.cpp` (`internal_aliases`) at `DuckDB`
63/// v2.0.0 and `main`; v1.4.4 has the same list without `odbc`.
64pub const DUCKDB_EXTENSION_ALIASES: &[(&str, &str)] = &[
65    ("http", "httpfs"),
66    ("https", "httpfs"),
67    ("md", "motherduck"),
68    ("mysql", "mysql_scanner"),
69    ("odbc", "odbc_scanner"),
70    ("postgres", "postgres_scanner"),
71    ("s3", "httpfs"),
72    ("sqlite", "sqlite_scanner"),
73    ("sqlite3", "sqlite_scanner"),
74    ("uc_catalog", "unity_catalog"),
75];
76
77/// The names of `DuckDB`'s core extensions, current and since `DuckDB` v1.4.4,
78/// which a community extension may not take (the community-extensions FAQ: it
79/// "has to be renamed").
80///
81/// The union of `internal_extensions[]` (`extension_helper.cpp`) and
82/// `AUTOLOADABLE_EXTENSIONS` (`extension_entries.hpp`) at v1.4.4, v1.5.6 and
83/// v2.0.0, and the core-extension table of the `DuckDB` 2.0 documentation,
84/// without the [aliases][DUCKDB_EXTENSION_ALIASES] (`mysql` is the alias, the
85/// extension is `mysql_scanner`). `jemalloc` was a core extension until
86/// v1.4.x; `sqlsmith` is autoloadable; `sirius` is documented as "coming
87/// soon". Sorted.
88pub const DUCKDB_CORE_EXTENSION_NAMES: &[&str] = &[
89    "autocomplete",
90    "avro",
91    "aws",
92    "azure",
93    "core_functions",
94    "delta",
95    "ducklake",
96    "encodings",
97    "excel",
98    "fts",
99    "httpfs",
100    "iceberg",
101    "icu",
102    "inet",
103    "jemalloc",
104    "json",
105    "lance",
106    "legacy_parser",
107    "motherduck",
108    "mysql_scanner",
109    "odbc_scanner",
110    "parquet",
111    "postgres_scanner",
112    "quack",
113    "sirius",
114    "spatial",
115    "sqlite_scanner",
116    "sqlsmith",
117    "tpcds",
118    "tpch",
119    "ui",
120    "unity_catalog",
121    "vortex",
122    "vss",
123];
124
125/// Every name a community extension may not take: the
126/// [aliases][DUCKDB_EXTENSION_ALIASES] and the
127/// [core extensions][DUCKDB_CORE_EXTENSION_NAMES]. Sorted.
128pub const DUCKDB_RESERVED_EXTENSION_NAMES: &[&str] = &[
129    "autocomplete",
130    "avro",
131    "aws",
132    "azure",
133    "core_functions",
134    "delta",
135    "ducklake",
136    "encodings",
137    "excel",
138    "fts",
139    "http",
140    "httpfs",
141    "https",
142    "iceberg",
143    "icu",
144    "inet",
145    "jemalloc",
146    "json",
147    "lance",
148    "legacy_parser",
149    "md",
150    "motherduck",
151    "mysql",
152    "mysql_scanner",
153    "odbc",
154    "odbc_scanner",
155    "parquet",
156    "postgres",
157    "postgres_scanner",
158    "quack",
159    "s3",
160    "sirius",
161    "spatial",
162    "sqlite",
163    "sqlite3",
164    "sqlite_scanner",
165    "sqlsmith",
166    "tpcds",
167    "tpch",
168    "uc_catalog",
169    "ui",
170    "unity_catalog",
171    "vortex",
172    "vss",
173];
174
175/// Validates a name for a **community** extension.
176///
177/// The name must be well formed ([`validate_extension_name`]) and not taken by
178/// `DuckDB` itself: neither one of its [aliases][DUCKDB_EXTENSION_ALIASES] nor
179/// a [core extension's name][DUCKDB_CORE_EXTENSION_NAMES]. The scaffold and
180/// `parse_description_yml` use this.
181///
182/// # Errors
183///
184/// Returns `ExtensionError` for a malformed name, or one `DuckDB` reserves,
185/// saying why.
186///
187/// # Example
188///
189/// ```rust
190/// use quack_rs::validate::extension_name::validate_community_extension_name;
191///
192/// assert!(validate_community_extension_name("my_s3_tools").is_ok());
193/// assert!(validate_community_extension_name("s3").is_err()); // DuckDB means httpfs
194/// assert!(validate_community_extension_name("json").is_err()); // a core extension
195/// ```
196pub fn validate_community_extension_name(name: &str) -> Result<(), ExtensionError> {
197    validate_extension_name(name)?;
198    if let Some(&(alias, target)) = DUCKDB_EXTENSION_ALIASES.iter().find(|(a, _)| *a == name) {
199        return Err(ExtensionError::new(format!(
200            "extension name '{alias}' is a DuckDB alias for the core extension '{target}': \
201             DuckDB replaces it with '{target}' before INSTALL and LOAD, so an extension of \
202             this name could never be installed or loaded; choose another name, for example \
203             with your vendor as a prefix ('myorg_{alias}')"
204        )));
205    }
206    if DUCKDB_CORE_EXTENSION_NAMES.contains(&name) {
207        return Err(ExtensionError::new(format!(
208            "extension name '{name}' is the name of a DuckDB core extension, and the \
209             community-extensions FAQ says a community extension with the name of a core \
210             extension \"has to be renamed to avoid confusion\"; choose another name, for \
211             example with your vendor as a prefix ('myorg_{name}')"
212        )));
213    }
214    Ok(())
215}
216
217/// Validates the form of a `DuckDB` extension name.
218///
219/// This is whether `DuckDB` can load a file of this name. Whether a community
220/// extension may *take* the name is [`validate_community_extension_name`],
221/// which also refuses the names `DuckDB` itself uses.
222///
223/// # Rules
224///
225/// - Must not be empty
226/// - Must contain only lowercase ASCII letters (`a-z`), digits (`0-9`), or
227///   underscores (`_`) — **no hyphens**: `DuckDB` derives the entry-point
228///   symbol `<name>_init_c_api` from the name (see the [module
229///   docs][crate::validate::extension_name])
230/// - Must start with a letter
231/// - Must not exceed 64 characters
232///
233/// # Errors
234///
235/// Returns `ExtensionError` describing the first rule violation found.
236///
237/// # Example
238///
239/// ```rust
240/// use quack_rs::validate::validate_extension_name;
241///
242/// assert!(validate_extension_name("my_extension").is_ok());
243/// assert!(validate_extension_name("my_ext_2").is_ok());
244/// assert!(validate_extension_name("my-ext").is_err()); // no C symbol can hold '-'
245/// assert!(validate_extension_name("").is_err());
246/// assert!(validate_extension_name("MyExtension").is_err());
247/// assert!(validate_extension_name("my extension").is_err());
248/// assert!(validate_extension_name("123start").is_err());
249/// ```
250pub fn validate_extension_name(name: &str) -> Result<(), ExtensionError> {
251    if name.is_empty() {
252        return Err(ExtensionError::new("extension name must not be empty"));
253    }
254
255    if name.len() > 64 {
256        return Err(ExtensionError::new(format!(
257            "extension name must not exceed 64 characters, got {}",
258            name.len()
259        )));
260    }
261
262    if !name.as_bytes()[0].is_ascii_lowercase() {
263        return Err(ExtensionError::new(format!(
264            "extension name must start with a lowercase letter, got '{}'",
265            name.chars().next().unwrap_or('?')
266        )));
267    }
268
269    for (i, ch) in name.chars().enumerate() {
270        if ch == '-' {
271            return Err(ExtensionError::new(format!(
272                "extension name must not contain '-' (position {i}): DuckDB loads the \
273                 extension by calling `<name>_init_c_api`, and no C or Rust symbol can \
274                 contain a hyphen; use '_' instead ('{}')",
275                name.replace('-', "_")
276            )));
277        }
278        if !matches!(ch, 'a'..='z' | '0'..='9' | '_') {
279            return Err(ExtensionError::new(format!(
280                "extension name contains invalid character '{ch}' at position {i}; \
281                 only lowercase letters, digits, and underscores are allowed"
282            )));
283        }
284    }
285
286    Ok(())
287}
288
289#[cfg(test)]
290mod tests {
291    use super::*;
292
293    #[test]
294    fn valid_simple_name() {
295        assert!(validate_extension_name("myext").is_ok());
296    }
297
298    #[test]
299    fn valid_with_underscore() {
300        assert!(validate_extension_name("my_extension").is_ok());
301    }
302
303    /// `DuckDB` looks up the entry point as `<file base name>_init_c_api`, and
304    /// the community build names the file after `extension.name`, so a hyphen
305    /// would require a symbol no C or Rust compiler can emit.
306    #[test]
307    fn hyphen_rejected() {
308        for name in ["my-extension", "my-ext_v2", "a-"] {
309            let err = validate_extension_name(name).unwrap_err();
310            assert!(err.as_str().contains("'-'"), "{name}: {err}");
311            assert!(err.as_str().contains("_init_c_api"), "{name}: {err}");
312        }
313    }
314
315    #[test]
316    fn valid_with_digits() {
317        assert!(validate_extension_name("ext2go").is_ok());
318    }
319
320    #[test]
321    fn valid_mixed() {
322        assert!(validate_extension_name("my_ext_v2").is_ok());
323    }
324
325    #[test]
326    fn empty_name_rejected() {
327        let err = validate_extension_name("").unwrap_err();
328        assert!(err.as_str().contains("empty"));
329    }
330
331    #[test]
332    fn uppercase_start_rejected() {
333        let err = validate_extension_name("MyExtension").unwrap_err();
334        assert!(err.as_str().contains("start with a lowercase letter"));
335    }
336
337    #[test]
338    fn uppercase_mid_rejected() {
339        let err = validate_extension_name("myExtension").unwrap_err();
340        assert!(err.as_str().contains("invalid character"));
341    }
342
343    #[test]
344    fn space_rejected() {
345        let err = validate_extension_name("my extension").unwrap_err();
346        assert!(err.as_str().contains("invalid character"));
347    }
348
349    #[test]
350    fn starts_with_digit_rejected() {
351        let err = validate_extension_name("123ext").unwrap_err();
352        assert!(err.as_str().contains("start with a lowercase letter"));
353    }
354
355    #[test]
356    fn starts_with_hyphen_rejected() {
357        let err = validate_extension_name("-ext").unwrap_err();
358        assert!(err.as_str().contains("start with a lowercase letter"));
359    }
360
361    #[test]
362    fn special_chars_rejected() {
363        let err = validate_extension_name("my@ext").unwrap_err();
364        assert!(err.as_str().contains("invalid character"));
365    }
366
367    #[test]
368    fn too_long_rejected() {
369        let long_name: String = "a".repeat(65);
370        let err = validate_extension_name(&long_name).unwrap_err();
371        assert!(err.as_str().contains("64 characters"));
372    }
373
374    #[test]
375    fn max_length_accepted() {
376        let max_name: String = "a".repeat(64);
377        assert!(validate_extension_name(&max_name).is_ok());
378    }
379
380    /// `INSTALL s3 FROM community` on `DuckDB` 2.0.0 fails with `Failed to
381    /// download extension "httpfs" ... (HTTP 404)`: the
382    /// alias is applied before the repository is asked.
383    #[test]
384    fn an_alias_is_refused_and_names_the_extension_it_stands_for() {
385        for (alias, target) in [
386            ("s3", "httpfs"),
387            ("http", "httpfs"),
388            ("https", "httpfs"),
389            ("md", "motherduck"),
390            ("mysql", "mysql_scanner"),
391            ("odbc", "odbc_scanner"),
392            ("postgres", "postgres_scanner"),
393            ("sqlite", "sqlite_scanner"),
394            ("sqlite3", "sqlite_scanner"),
395            ("uc_catalog", "unity_catalog"),
396        ] {
397            let err = validate_community_extension_name(alias).expect_err(alias);
398            assert!(err.as_str().contains("alias"), "{alias}: {err}");
399            assert!(
400                err.as_str().contains(&format!("'{target}'")),
401                "{alias}: {err}"
402            );
403            // The name itself is well formed: DuckDB could load a file of it.
404            assert!(validate_extension_name(alias).is_ok());
405        }
406    }
407
408    #[test]
409    fn a_core_extension_name_is_refused_with_the_faqs_reason() {
410        for name in [
411            "json",
412            "parquet",
413            "httpfs",
414            "icu",
415            "quack",
416            "spatial",
417            "core_functions",
418            "jemalloc",
419            "mysql_scanner",
420            "sqlsmith",
421            "legacy_parser",
422        ] {
423            let err = validate_community_extension_name(name).expect_err(name);
424            assert!(err.as_str().contains("has to be renamed"), "{name}: {err}");
425            assert!(validate_extension_name(name).is_ok());
426        }
427    }
428
429    /// Only the exact name is taken: 18 of the 395 published community
430    /// extensions build on a core name (`cache_httpfs`, `rusty_quack`,
431    /// `json_schema`, `ducklake_cdc`, `http_client`, ...).
432    #[test]
433    fn a_name_built_on_a_reserved_one_is_fine() {
434        for name in [
435            "cache_httpfs",
436            "rusty_quack",
437            "json_schema",
438            "ducklake_cdc",
439            "http_client",
440            "my_s3_tools",
441            "s3x",
442        ] {
443            assert!(validate_community_extension_name(name).is_ok(), "{name}");
444        }
445        assert!(validate_community_extension_name("Bad-Name").is_err());
446    }
447
448    #[test]
449    fn the_reserved_list_is_exactly_the_aliases_and_core_names_sorted() {
450        let mut union: Vec<&str> = DUCKDB_CORE_EXTENSION_NAMES
451            .iter()
452            .copied()
453            .chain(DUCKDB_EXTENSION_ALIASES.iter().map(|(alias, _)| *alias))
454            .collect();
455        union.sort_unstable();
456        union.dedup();
457        assert_eq!(union, DUCKDB_RESERVED_EXTENSION_NAMES);
458        for list in [DUCKDB_CORE_EXTENSION_NAMES, DUCKDB_RESERVED_EXTENSION_NAMES] {
459            let mut sorted = list.to_vec();
460            sorted.sort_unstable();
461            sorted.dedup();
462            assert_eq!(sorted, list, "keep the list sorted and unique");
463        }
464        // Every alias points at a core extension, and none is one itself.
465        for (alias, target) in DUCKDB_EXTENSION_ALIASES {
466            assert!(DUCKDB_CORE_EXTENSION_NAMES.contains(target), "{target}");
467            assert!(!DUCKDB_CORE_EXTENSION_NAMES.contains(alias), "{alias}");
468        }
469        for name in DUCKDB_RESERVED_EXTENSION_NAMES {
470            assert!(validate_extension_name(name).is_ok(), "{name}");
471        }
472    }
473}