quack_rs/validate/function_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//! SQL function name validation for `DuckDB` extensions.
7//!
8//! A function name that needs quoting in SQL, or that cannot survive the trip
9//! through a C string, will fail at registration or produce a function nobody
10//! can call. This validator rejects those, and nothing else.
11//!
12//! # What it deliberately does not do
13//!
14//! It does not impose a naming *style*. `DuckDB` identifiers are
15//! case-insensitive and `DuckDB` itself ships mixed-case functions
16//! (`formatReadableSize`, `formatReadableDecimalSize`), so `myFunc` registers
17//! fine and is callable as `myfunc`, `MYFUNC` or `myFunc` — verified against
18//! `DuckDB` 1.5.5. `snake_case` is the overwhelming convention in `DuckDB`'s own
19//! catalog and is worth following, but it is a convention, not a rule, and this
20//! validator gates [`ScalarFunctionBuilder::try_new`][crate::scalar::ScalarFunctionBuilder::try_new]
21//! — so enforcing it here would make a legitimate function name
22//! *unregisterable*.
23
24use crate::error::ExtensionError;
25
26/// Maximum length for a function name.
27///
28/// `DuckDB` does not publicly document a hard limit, but names beyond 256
29/// characters are unreasonable and may cause issues with catalog storage.
30const MAX_FUNCTION_NAME_LEN: usize = 256;
31
32/// `DuckDB`'s **reserved** SQL keywords, lowercase and sorted.
33///
34/// A function with one of these names cannot be called without quoting it —
35/// `SELECT order(1)` is a parser error, only `"order"(1)` works — so
36/// [`validate_function_name`] rejects them (case-insensitively). Most of the
37/// other keywords (`unreserved`, `column_name`, `type_function`) are callable
38/// unquoted and stay allowed — `DuckDB` itself ships `left`, `similar` and
39/// `year` — but not all: see [`DUCKDB_UNCALLABLE_KEYWORDS`].
40///
41/// Taken from `SELECT keyword_name FROM duckdb_keywords() WHERE
42/// keyword_category = 'reserved'`, which returns this identical list on
43/// `DuckDB` 1.4.4, 1.5.0, 1.5.5, 1.5.6 and 2.0.0. An end-to-end test compares it against the
44/// linked engine, so a `DuckDB` release that changes the set fails CI.
45pub const DUCKDB_RESERVED_KEYWORDS: [&str; 75] = [
46 "all",
47 "analyse",
48 "analyze",
49 "and",
50 "any",
51 "array",
52 "as",
53 "asc",
54 "asymmetric",
55 "both",
56 "case",
57 "cast",
58 "check",
59 "collate",
60 "column",
61 "constraint",
62 "create",
63 "default",
64 "deferrable",
65 "desc",
66 "describe",
67 "distinct",
68 "do",
69 "else",
70 "end",
71 "except",
72 "false",
73 "fetch",
74 "for",
75 "foreign",
76 "from",
77 "group",
78 "having",
79 "in",
80 "initially",
81 "intersect",
82 "into",
83 "lambda",
84 "lateral",
85 "leading",
86 "limit",
87 "not",
88 "null",
89 "offset",
90 "on",
91 "only",
92 "or",
93 "order",
94 "pivot",
95 "pivot_longer",
96 "pivot_wider",
97 "placing",
98 "primary",
99 "qualify",
100 "references",
101 "returning",
102 "select",
103 "show",
104 "some",
105 "summarize",
106 "symmetric",
107 "table",
108 "then",
109 "to",
110 "trailing",
111 "true",
112 "union",
113 "unique",
114 "unpivot",
115 "using",
116 "variadic",
117 "when",
118 "where",
119 "window",
120 "with",
121];
122
123/// Non-reserved keywords that still cannot be a function's name, lowercase
124/// and sorted.
125///
126/// `SELECT between(1)`, `SELECT values(1)` and `SELECT time(1)` are parser
127/// errors whatever function is registered under the name, and some calls are
128/// taken by the grammar before any function lookup: `coalesce(x)` is the
129/// `COALESCE` operator, so a function called `coalesce` is never called.
130///
131/// Measured, not taken from a keyword category: for each keyword `kw` in
132/// `duckdb_keywords()` and each argument count from 0 to 3, a macro `"kw"`
133/// taking that many arguments is created and called as `kw(41, …)`. These
134/// are the non-reserved keywords for which no such call reaches the macro —
135/// the same 53 on `DuckDB` 1.4.4, 1.5.0 and 1.5.5 (`duckdb_keywords()` lists
136/// 489 keywords on each). `nullif` is the one keyword that fails with one
137/// argument but works with two, so it is not refused. `position` is listed
138/// although `DuckDB` ships a function of that name: it is reachable only
139/// through the `position(a IN b)` syntax, never as `position(a, b)`. The
140/// sweep calls the name as a scalar; a table function of the same name is
141/// refused too. An end-to-end test repeats the sweep against the linked
142/// engine.
143///
144/// # On `DuckDB` 2.0
145///
146/// 2.0.0 lists 508 keyword rows (16 new keywords, all callable, and the same 75
147/// reserved) and its parser takes more of these names than 1.x does: `anti`,
148/// `by`, `columns`, `if`, `operator`, `overlay`, `semi` and `try_cast` are
149/// callable there, and none is callable on 1.x but not on 2.0. The list is not
150/// narrowed for 2.0: an extension built with quack-rs can be loaded into
151/// either engine, and a name only one of them can call is a broken
152/// function on the other, so the list is the union of what each supported
153/// engine refuses (here, the 1.x set). The end-to-end sweep checks on 2.0
154/// that exactly those eight are refused although 2.0 would take them.
155pub const DUCKDB_UNCALLABLE_KEYWORDS: [&str; 53] = [
156 "anti",
157 "between",
158 "bigint",
159 "bit",
160 "boolean",
161 "by",
162 "char",
163 "character",
164 "coalesce",
165 "columns",
166 "dec",
167 "decimal",
168 "exists",
169 "extract",
170 "float",
171 "grouping",
172 "grouping_id",
173 "if",
174 "inout",
175 "int",
176 "integer",
177 "interval",
178 "national",
179 "nchar",
180 "none",
181 "numeric",
182 "operator",
183 "out",
184 "overlay",
185 "position",
186 "precision",
187 "real",
188 "semi",
189 "setof",
190 "smallint",
191 "time",
192 "timestamp",
193 "treat",
194 "try_cast",
195 "unpack",
196 "values",
197 "varchar",
198 "xmlattributes",
199 "xmlconcat",
200 "xmlelement",
201 "xmlexists",
202 "xmlforest",
203 "xmlnamespaces",
204 "xmlparse",
205 "xmlpi",
206 "xmlroot",
207 "xmlserialize",
208 "xmltable",
209];
210
211/// Non-reserved keywords that cannot be a macro parameter's name, lowercase
212/// and sorted.
213///
214/// A parameter is referred to by name in the macro's body, and
215/// `CREATE MACRO m(left) AS left + 1` fails to parse, as do `join`, `like`,
216/// `row` and the rest of this list. Measured the same way as
217/// [`DUCKDB_UNCALLABLE_KEYWORDS`] — `CREATE MACRO m(kw) AS kw + 1` then
218/// `SELECT m(41)` — and the same 79 on `DuckDB` 1.4.4, 1.5.0 and 1.5.5.
219/// `DuckDB` 2.0.0 can refer to 49 of them (`row`, `values`, `integer`, …)
220/// and to every keyword it added; they stay refused for the reason given
221/// under [`DUCKDB_UNCALLABLE_KEYWORDS`] — the list is the union over the
222/// supported engines, and the end-to-end sweep pins the 49 on 2.0.
223pub const DUCKDB_UNREFERENCEABLE_PARAMETER_KEYWORDS: [&str; 79] = [
224 "anti",
225 "asof",
226 "at",
227 "authorization",
228 "between",
229 "bigint",
230 "binary",
231 "bit",
232 "boolean",
233 "by",
234 "char",
235 "character",
236 "coalesce",
237 "collation",
238 "concurrently",
239 "cross",
240 "dec",
241 "decimal",
242 "exists",
243 "extract",
244 "float",
245 "freeze",
246 "full",
247 "glob",
248 "grouping",
249 "grouping_id",
250 "ilike",
251 "inner",
252 "inout",
253 "int",
254 "integer",
255 "interval",
256 "is",
257 "isnull",
258 "join",
259 "left",
260 "like",
261 "national",
262 "natural",
263 "nchar",
264 "none",
265 "notnull",
266 "nullif",
267 "numeric",
268 "out",
269 "outer",
270 "overlaps",
271 "overlay",
272 "position",
273 "positional",
274 "precision",
275 "real",
276 "right",
277 "row",
278 "semi",
279 "setof",
280 "similar",
281 "smallint",
282 "substring",
283 "tablesample",
284 "time",
285 "timestamp",
286 "treat",
287 "trim",
288 "unpack",
289 "values",
290 "varchar",
291 "verbose",
292 "xmlattributes",
293 "xmlconcat",
294 "xmlelement",
295 "xmlexists",
296 "xmlforest",
297 "xmlnamespaces",
298 "xmlparse",
299 "xmlpi",
300 "xmlroot",
301 "xmlserialize",
302 "xmltable",
303];
304
305/// Validates a `DuckDB` function name.
306///
307/// # Rules
308///
309/// - Must not be empty
310/// - Must not exceed 256 characters
311/// - Must start with an ASCII letter or underscore
312/// - Must contain only ASCII letters, digits, or underscores
313/// - Must not contain interior null bytes
314/// - Must not be one of [`DUCKDB_RESERVED_KEYWORDS`] or
315/// [`DUCKDB_UNCALLABLE_KEYWORDS`] (compared case-insensitively)
316///
317/// Every one of these is something that would actually break: a name needing
318/// quotes in SQL (including a reserved keyword such as `order`), a name
319/// starting with a digit that the parser reads as a number, or a name a C
320/// string truncates. Casing is **not** checked — see the
321/// [module docs][crate::validate::function_name] for why enforcing `snake_case`
322/// here would make a name `DuckDB` accepts unregisterable.
323///
324/// # Errors
325///
326/// Returns `ExtensionError` describing the first rule violation found.
327///
328/// # Example
329///
330/// ```rust
331/// use quack_rs::validate::validate_function_name;
332///
333/// assert!(validate_function_name("word_count").is_ok());
334/// assert!(validate_function_name("my_func_v2").is_ok());
335/// assert!(validate_function_name("_internal").is_ok());
336/// // DuckDB ships `formatReadableSize`; mixed case is legal.
337/// assert!(validate_function_name("formatReadableSize").is_ok());
338///
339/// assert!(validate_function_name("").is_err()); // empty
340/// assert!(validate_function_name("my-func").is_err()); // needs quoting in SQL
341/// assert!(validate_function_name("1func").is_err()); // parsed as a number
342/// assert!(validate_function_name("my func").is_err()); // needs quoting in SQL
343/// assert!(validate_function_name("order").is_err()); // reserved keyword
344/// assert!(validate_function_name("coalesce").is_err()); // the COALESCE operator takes the call
345/// assert!(validate_function_name("left").is_ok()); // keyword, but callable
346/// ```
347pub fn validate_function_name(name: &str) -> Result<(), ExtensionError> {
348 if name.is_empty() {
349 return Err(ExtensionError::new("function name must not be empty"));
350 }
351
352 if name.len() > MAX_FUNCTION_NAME_LEN {
353 return Err(ExtensionError::new(format!(
354 "function name must not exceed {MAX_FUNCTION_NAME_LEN} characters, got {}",
355 name.len()
356 )));
357 }
358
359 // Check for interior null bytes (would truncate the CString)
360 if name.bytes().any(|b| b == 0) {
361 return Err(ExtensionError::new(
362 "function name must not contain null bytes",
363 ));
364 }
365
366 let first = name.as_bytes()[0];
367 if !first.is_ascii_alphabetic() && first != b'_' {
368 return Err(ExtensionError::new(format!(
369 "function name must start with a letter or underscore, got '{}'",
370 name.chars().next().unwrap_or('?')
371 )));
372 }
373
374 for (i, ch) in name.chars().enumerate() {
375 if !ch.is_ascii_alphanumeric() && ch != '_' {
376 return Err(ExtensionError::new(format!(
377 "function name contains invalid character '{ch}' at position {i}; \
378 only letters, digits, and underscores are allowed (a name needing \
379 quotes in SQL is not worth the trouble it causes callers)"
380 )));
381 }
382 }
383
384 // Only reached for an all-ASCII name, so ASCII case folding is exact.
385 let lower = name.to_ascii_lowercase();
386 if DUCKDB_RESERVED_KEYWORDS
387 .binary_search(&lower.as_str())
388 .is_ok()
389 {
390 return Err(ExtensionError::new(format!(
391 "function name '{name}' is a reserved keyword in DuckDB's SQL: `SELECT {lower}(...)` \
392 is a parser error, so callers would have to write `\"{lower}\"(...)`; \
393 choose another name"
394 )));
395 }
396 if DUCKDB_UNCALLABLE_KEYWORDS
397 .binary_search(&lower.as_str())
398 .is_ok()
399 {
400 return Err(ExtensionError::new(format!(
401 "function name '{name}' is a DuckDB keyword that cannot be called as a function: \
402 `SELECT {lower}(...)` either fails to parse or is taken by the grammar before any \
403 function is looked up; choose another name"
404 )));
405 }
406
407 Ok(())
408}
409
410/// Validates a macro parameter name.
411///
412/// The rules of [`validate_function_name`], except that the keywords refused
413/// are [`DUCKDB_RESERVED_KEYWORDS`] and
414/// [`DUCKDB_UNREFERENCEABLE_PARAMETER_KEYWORDS`] — the names a macro body
415/// cannot refer to unquoted — rather than [`DUCKDB_UNCALLABLE_KEYWORDS`]. A
416/// parameter named `columns` or `if` is fine; one named `left` is not.
417///
418/// # Errors
419///
420/// Returns `ExtensionError` describing the first rule violation found.
421///
422/// # Example
423///
424/// ```rust
425/// use quack_rs::validate::validate_parameter_name;
426///
427/// assert!(validate_parameter_name("threshold").is_ok());
428/// assert!(validate_parameter_name("columns").is_ok());
429/// assert!(validate_parameter_name("left").is_err());
430/// assert!(validate_parameter_name("order").is_err());
431/// ```
432pub fn validate_parameter_name(name: &str) -> Result<(), ExtensionError> {
433 match validate_function_name(name) {
434 Ok(()) => {}
435 Err(e) => {
436 let lower = name.to_ascii_lowercase();
437 // Only the name-specific keyword rule is lifted for a parameter.
438 if DUCKDB_UNCALLABLE_KEYWORDS
439 .binary_search(&lower.as_str())
440 .is_err()
441 {
442 return Err(e);
443 }
444 }
445 }
446 let lower = name.to_ascii_lowercase();
447 if DUCKDB_UNREFERENCEABLE_PARAMETER_KEYWORDS
448 .binary_search(&lower.as_str())
449 .is_ok()
450 {
451 return Err(ExtensionError::new(format!(
452 "parameter name '{name}' is a DuckDB keyword a macro body cannot refer to unquoted \
453 (`CREATE MACRO m({lower}) AS {lower} + 1` fails to parse); choose another name"
454 )));
455 }
456 Ok(())
457}
458
459#[cfg(test)]
460mod tests {
461 use super::*;
462
463 #[test]
464 fn valid_simple() {
465 assert!(validate_function_name("word_count").is_ok());
466 }
467
468 #[test]
469 fn valid_with_digits() {
470 assert!(validate_function_name("my_func_v2").is_ok());
471 }
472
473 #[test]
474 fn valid_underscore_prefix() {
475 assert!(validate_function_name("_internal").is_ok());
476 }
477
478 #[test]
479 fn valid_single_char() {
480 assert!(validate_function_name("f").is_ok());
481 }
482
483 #[test]
484 fn mixed_case_is_accepted_because_duckdb_accepts_it() {
485 // DuckDB ships these two, and registering a camelCase name through the
486 // C API succeeds — verified against DuckDB 1.5.5 in
487 // tests/ffi_roundtrip.rs. Since this validator gates
488 // `ScalarFunctionBuilder::try_new`, rejecting them made a name DuckDB
489 // accepts impossible to register at all.
490 assert!(validate_function_name("formatReadableSize").is_ok());
491 assert!(validate_function_name("formatReadableDecimalSize").is_ok());
492 assert!(validate_function_name("MyFunc").is_ok());
493 assert!(validate_function_name("_Internal2").is_ok());
494 }
495
496 #[test]
497 fn names_needing_quotes_are_still_rejected() {
498 for name in [
499 "my-func", "my func", "my.func", "my\"func", "my'func", "1func", "+",
500 ] {
501 assert!(
502 validate_function_name(name).is_err(),
503 "{name} should be rejected"
504 );
505 }
506 }
507
508 /// `SELECT order(1)` is a parser error in `DuckDB` 1.4.4–1.5.5; only
509 /// `"order"(1)` works. The module promises names needing quotes are
510 /// rejected, and reserved keywords are exactly such names.
511 #[test]
512 fn reserved_keywords_are_rejected_in_any_case() {
513 for name in [
514 "order",
515 "select",
516 "from",
517 "group",
518 "table",
519 "case",
520 "ORDER",
521 "Select",
522 "window",
523 "pivot_longer",
524 ] {
525 let err = validate_function_name(name)
526 .expect_err(&format!("reserved keyword {name} must be rejected"));
527 assert!(err.as_str().contains("reserved keyword"), "{name}: {err}");
528 }
529 }
530
531 /// Unreserved, column-name and type/function keywords are callable
532 /// unquoted (`SELECT similar(1)`, `SELECT left('ab', 1)` work), so they
533 /// must stay registerable.
534 #[test]
535 fn non_reserved_keywords_are_accepted() {
536 for name in [
537 "left", "similar", "overlaps", "year", "filter", "count", "orders",
538 ] {
539 assert!(validate_function_name(name).is_ok(), "{name}");
540 }
541 }
542
543 #[test]
544 fn uncallable_keywords_are_refused_as_function_names_only() {
545 for name in ["coalesce", "Between", "VALUES", "time", "if", "try_cast"] {
546 let err = validate_function_name(name).expect_err(name);
547 assert!(err.as_str().contains("cannot be called"), "{name}: {err}");
548 }
549 // `if` and `columns` cannot name a function but can name a parameter.
550 assert!(validate_parameter_name("if").is_ok());
551 assert!(validate_parameter_name("columns").is_ok());
552 }
553
554 #[test]
555 fn unreferenceable_keywords_are_refused_as_parameter_names_only() {
556 for name in ["left", "JOIN", "like", "row", "between"] {
557 let err = validate_parameter_name(name).expect_err(name);
558 assert!(err.as_str().contains("cannot refer to"), "{name}: {err}");
559 }
560 // `left` and `like` stay valid function names: both are callable.
561 assert!(validate_function_name("left").is_ok());
562 assert!(validate_function_name("like").is_ok());
563 // A parameter name gets every other rule of a function name.
564 assert!(validate_parameter_name("order").is_err());
565 assert!(validate_parameter_name("my-param").is_err());
566 assert!(validate_parameter_name("").is_err());
567 assert!(validate_parameter_name("threshold").is_ok());
568 }
569
570 #[test]
571 fn keyword_lists_are_sorted_unique_lowercase_and_non_reserved() {
572 for list in [
573 &DUCKDB_UNCALLABLE_KEYWORDS[..],
574 &DUCKDB_UNREFERENCEABLE_PARAMETER_KEYWORDS[..],
575 ] {
576 assert!(list.windows(2).all(|w| w[0] < w[1]));
577 assert!(list
578 .iter()
579 .all(|k| k.bytes().all(|b| b.is_ascii_lowercase() || b == b'_')));
580 assert!(list
581 .iter()
582 .all(|k| DUCKDB_RESERVED_KEYWORDS.binary_search(k).is_err()));
583 }
584 assert_eq!(DUCKDB_UNCALLABLE_KEYWORDS.len(), 53);
585 assert_eq!(DUCKDB_UNREFERENCEABLE_PARAMETER_KEYWORDS.len(), 79);
586 }
587
588 /// Pins the list's shape: sorted, unique, lowercase, and the size `DuckDB`
589 /// 1.4.4, 1.5.0 and 1.5.5 all report. `tests/ffi_roundtrip/tooling.rs`
590 /// compares it against the linked engine's `duckdb_keywords()`.
591 #[test]
592 fn reserved_keyword_list_is_sorted_unique_lowercase() {
593 assert_eq!(DUCKDB_RESERVED_KEYWORDS.len(), 75);
594 assert!(DUCKDB_RESERVED_KEYWORDS.windows(2).all(|w| w[0] < w[1]));
595 assert!(DUCKDB_RESERVED_KEYWORDS
596 .iter()
597 .all(|k| k.bytes().all(|b| b.is_ascii_lowercase() || b == b'_')));
598 }
599
600 #[test]
601 fn empty_rejected() {
602 let err = validate_function_name("").unwrap_err();
603 assert!(err.as_str().contains("empty"));
604 }
605
606 #[test]
607 fn hyphen_rejected() {
608 let err = validate_function_name("my-func").unwrap_err();
609 assert!(err.as_str().contains("invalid character"));
610 }
611
612 #[test]
613 fn starts_with_digit_rejected() {
614 let err = validate_function_name("1func").unwrap_err();
615 assert!(err.as_str().contains("letter or underscore"));
616 }
617
618 #[test]
619 fn space_rejected() {
620 let err = validate_function_name("my func").unwrap_err();
621 assert!(err.as_str().contains("invalid character"));
622 }
623
624 #[test]
625 fn special_char_rejected() {
626 let err = validate_function_name("my@func").unwrap_err();
627 assert!(err.as_str().contains("invalid character"));
628 }
629
630 #[test]
631 fn null_byte_rejected() {
632 let err = validate_function_name("my\0func").unwrap_err();
633 assert!(err.as_str().contains("null bytes"));
634 }
635
636 #[test]
637 fn too_long_rejected() {
638 let long_name: String = "a".repeat(257);
639 let err = validate_function_name(&long_name).unwrap_err();
640 assert!(err.as_str().contains("256 characters"));
641 }
642
643 #[test]
644 fn max_length_accepted() {
645 let max_name: String = "a".repeat(256);
646 assert!(validate_function_name(&max_name).is_ok());
647 }
648
649 #[test]
650 fn semicolon_rejected() {
651 let err = validate_function_name("func;drop").unwrap_err();
652 assert!(err.as_str().contains("invalid character"));
653 }
654
655 #[test]
656 fn quote_rejected() {
657 let err = validate_function_name("func'name").unwrap_err();
658 assert!(err.as_str().contains("invalid character"));
659 }
660}