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}