|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +DuckDB QuickJS Extension - embeds the QuickJS-NG JavaScript engine into DuckDB, allowing JavaScript execution within SQL queries. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```sh |
| 12 | +# Build release (default) |
| 13 | +GEN=ninja make |
| 14 | + |
| 15 | +# Build debug |
| 16 | +GEN=ninja make debug |
| 17 | + |
| 18 | +# Run tests |
| 19 | +make test |
| 20 | + |
| 21 | +# Format code |
| 22 | +make format |
| 23 | + |
| 24 | +# Run clang-tidy |
| 25 | +make tidy-check |
| 26 | +``` |
| 27 | + |
| 28 | +It is best to test with a debug build since it tests more assertions. |
| 29 | + |
| 30 | +All extension functions should be documented inside of DuckDB with CreateScalarFunctionInfo or CreateAggregateFunctionInfo or the appropriate type for the function. This documentation of the function should include examples, parameter types and parameter names. The function should be categorized. |
| 31 | + |
| 32 | +When making changes the version should always be updated to the current date plus an ordinal counter in the form of YYYYMMDDCC. |
| 33 | + |
| 34 | + |
| 35 | +## Build Outputs |
| 36 | + |
| 37 | +- `./build/release/duckdb` - DuckDB shell with extension auto-loaded |
| 38 | +- `./build/release/test/unittest` - Test runner |
| 39 | +- `./build/release/extension/quickjs/quickjs.duckdb_extension` - Loadable extension binary |
| 40 | + |
| 41 | +## Testing |
| 42 | + |
| 43 | +Tests are in `test/sql/quickjs.test` using DuckDB's SQL test format. Run a specific test pattern: |
| 44 | +```sh |
| 45 | +./build/release/test/unittest "test/sql/quickjs.test" |
| 46 | +``` |
| 47 | + |
| 48 | +## Architecture |
| 49 | + |
| 50 | +This is a DuckDB extension built using the extension template pattern: |
| 51 | + |
| 52 | +- **Main source**: `src/quickjs_extension.cpp` - Contains all extension logic |
| 53 | +- **Header**: `src/include/quickjs_extension.hpp` - Extension class declaration |
| 54 | +- **QuickJS submodule**: `quickjs/` - The QuickJS-NG engine |
| 55 | +- **DuckDB submodule**: `duckdb/` - DuckDB source for building |
| 56 | + |
| 57 | +### Extension Functions |
| 58 | + |
| 59 | +Three SQL functions are registered: |
| 60 | + |
| 61 | +1. **`quickjs(code)` (scalar)** - Executes JS, returns result as VARCHAR |
| 62 | +2. **`quickjs_eval(function, ...args)` (scalar)** - Executes JS function with args, returns JSON |
| 63 | +3. **`quickjs(code, ...args)` (table)** - Executes JS returning array, each element becomes a row |
| 64 | + |
| 65 | +### Key Implementation Details |
| 66 | + |
| 67 | +- Each function call creates a fresh `JSRuntime`/`JSContext` for complete state isolation |
| 68 | +- DuckDB types are converted to JS values via `DuckDBValueToJSValue()` |
| 69 | +- Table function uses bind/init/execute pattern with `QuickJSTableBindData` and `QuickJSTableGlobalState` |
| 70 | +- Supports both legacy (`DatabaseInstance&`) and new (`ExtensionLoader&`) DuckDB extension APIs via `DUCKDB_CPP_EXTENSION_ENTRY` preprocessor flag |
| 71 | + |
| 72 | +### Table Function Parameter Convention |
| 73 | + |
| 74 | +- `arg0`, `arg1`, etc. - Raw parameters |
| 75 | +- `parsed_arg0` - First parameter parsed as JSON (for array/object inputs) |
| 76 | + |
| 77 | +## Submodule Management |
| 78 | + |
| 79 | +```sh |
| 80 | +# Initialize submodules |
| 81 | +git submodule update --init --recursive |
| 82 | + |
| 83 | +# Update submodules to latest |
| 84 | +make update |
| 85 | +``` |
| 86 | + |
| 87 | +## Requirements |
| 88 | + |
| 89 | +- DuckDB 1.3.1+ |
| 90 | +- C++11 compatible compiler |
| 91 | +- CMake 3.16+ |
0 commit comments