Skip to main content

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}