Downloads 945this week

GitHub stars 4

Extension descriptor (YAML)

Compile C from SQL into scalar, aggregate, and table functions in-process with an embedded TinyCC; no compiler or runtime files needed

Installing and Loading

INSTALL ducktinycc FROM community;
LOAD ducktinycc;

Example

LOAD ducktinycc;

-- Compile a C function and register it as collatz_steps(BIGINT) -> BIGINT
SELECT ok, code
FROM tcc_module(
  mode := 'quick_compile',
  source := 'int64_t collatz_steps(int64_t n) {
    int64_t steps = 0;
    if (n < 1) return -1;
    while (n != 1) { n = (n & 1) ? 3 * n + 1 : n / 2; steps++; }
    return steps;
  }',
  symbol := 'collatz_steps',
  sql_name := 'collatz_steps',
  return_type := 'i64',
  arg_types := ['i64']
);

-- Longest Collatz chain below one million: 837799, 524 steps
SELECT arg_max(range, collatz_steps(range)) AS n, max(collatz_steps(range)) AS steps
FROM range(1, 1000000);

-- Every DuckTinyCC function, mode, type token, and C helper
SELECT kind, name, description FROM tcc_help();

About ducktinycc

DuckTinyCC compiles C from SQL using TinyCC (libtcc), in-process, and registers it as a scalar, aggregate (kind := 'aggregate'), or table function (kind := 'table'). SELECT * FROM tcc_help() lists every function, tcc_module mode, type token, and C helper with an example. Worked examples: https://sounkou-bioinfo.github.io/DuckTinyCC/cookbook.html

Main SQL entrypoints:

Compile/codegen and C-type helper modes (via tcc_module):

Generated helper naming:

Type signature support (return_type / arg_types):

SQL <-> C bridge correspondences:

Function result schemas:

Codegen/runtime model:

• wrappers are generated from return_type/arg_types and registered through ducktinycc_register_signature(…)
• wrapper_mode is row (default) or chunk_scalar_loop, a generated C loop over each data chunk
• returned strings, blobs, and list/struct payloads should be allocated with ducktinycc_result_alloc(size); the memory belongs to the executing chunk and is freed after DuckDB copies the results
• code is compiled + relocated in-memory (no separate shared-library artifact)
• registering the same sql_name twice in a session returns false/E_INIT_FAILED (consistent across platforms); use tcc_new_state to reset before re-registering

Aggregate and table functions:

• kind := 'aggregate' uses _state, _step, _combine, _final(state, R *out) returning 0 for NULL, and optional _init / _destroy
• kind := 'table' uses _state, _init(state, args...), _next(state, C1 *, ..., Cm *) returning 0 at the end, and optional _destroy; columns are the fields of a struct<...> return_type
• ducktinycc_malloc / ducktinycc_realloc / ducktinycc_free give heap memory for states without linking libc
• DuckDB crashes C-API aggregates under agg(x ORDER BY y) and OVER () frames (duckdb/duckdb#26109); avoid those forms

Scalar UDF stability:

• compile, quick_compile, and codegen_preview accept stability := 'consistent'

  'volatile'

• tinycc_bind can stage stability for a later compile; an explicit compile/quick_compile/codegen_preview stability value overrides the staged value
• use volatile for RNGs, counters, clocks, allocation, I/O, callbacks, or reads from mutable external memory so DuckDB re-runs the function and avoids constant-folding side effects
• generated helper modes set explicit helper stability internally: pure metadata/enum helpers are consistent, while allocation/free/setter/mutable-memory getter helpers are volatile

Embedded runtime (self-contained):

• libtcc1.a and all TinyCC include headers (stdarg.h, stddef.h, tccdefs.h, etc.) are baked into the extension binary at build time
• on the first compile or quick_compile call, tcc_ensure_embedded_runtime() extracts them to a content-hash-keyed temp directory (e.g. /tmp/ducktinycc_/)
• subsequent calls in the same process reuse that directory without re-extracting
• no separate TinyCC installation or runtime path configuration is needed after deployment
• tcc_system_paths() shows the active runtime path and whether it resolved from the embedded extraction

Project details and examples: https://github.com/sounkou-bioinfo/DuckTinyCC

Community package excludes WASM targets.

Additional Notes: Generated and helper functions are SQL scalar UDFs unless compiled with kind := 'aggregate' or 'table'; the extension's own table functions are tcc_module(…), tcc_system_paths(…), tcc_library_probe(…), and tcc_help(). For library linking, we can pass short names (m, z, c), explicit filenames (libfoo.so, foo.dll, .a, .lib), or path-like values. Because DuckTinyCC uses -nostdlib by default, use library := 'c' when generated code needs libc symbols that are not otherwise injected. TinyCC's libtcc1.a (compiler support: 64-bit float conversion, va_arg, stdatomic) is always linked. Pointer helpers are low-level interop tools; for most workflows, handle-based access is safer than raw tcc_dataptr

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings

This extension does not add any settings.