Class DuckDBTerminal

A browser-based SQL terminal for DuckDB, powered by Ghostty terminal emulator.

DuckDBTerminal provides a full-featured SQL REPL (Read-Eval-Print Loop) that runs entirely in the browser using DuckDB WASM. It supports:

Multi-line SQL statements with syntax highlighting
Command history with arrow key navigation
Tab completion for SQL keywords, table names, and functions
Dot commands (.help, .tables, .schema, etc.)
Multiple output formats (table, CSV, JSON)
File loading via drag-and-drop or file picker
Result pagination for large datasets
Custom theming
Customizable prompts (via config or .prompt command)
Event system for integration with host applications

Implements

Example: Basic usage

const terminal = new DuckDBTerminal({
  container: '#terminal',
  theme: 'dark',
});
await terminal.start();

Example: With custom prompts

const terminal = new DuckDBTerminal({
  container: '#terminal',
  prompt: 'SQL> ',
  continuationPrompt: '... ',
});
await terminal.start();

Example: With event listeners

const terminal = new DuckDBTerminal({ container: '#terminal' });

terminal.on('queryEnd', ({ sql, result, duration }) => {
  console.log(`Query "${sql}" completed in ${duration}ms`);
});

terminal.on('error', ({ message, source }) => {
  console.error(`Error from ${source}: ${message}`);
});

await terminal.start();

Example: Programmatic SQL execution

const terminal = new DuckDBTerminal({ container: '#terminal' });
await terminal.start();

const result = await terminal.executeSQL('SELECT * FROM users LIMIT 10;');
console.log(result.columns); // ['id', 'name', 'email']
console.log(result.rows);    // [[1, 'Alice', 'alice@example.com'], ...]

Implements

TerminalInterface

Index

Constructors

constructor

Constructors

constructor

new DuckDBTerminal(config: TerminalConfig): DuckDBTerminal
Parameters
- config: TerminalConfig
Returns DuckDBTerminal
- Defined in terminal.ts:141

Properties

`Private`collectedSQL

collectedSQL: string[] = []

`Private`commands

commands: Map<string, Command> = ...

`Private`config

config: TerminalConfig

`Private`continuationPrompt

continuationPrompt: string

`Private`currentPage

currentPage: number = 0

`Private`currentThemeName

currentThemeName: "dark" | "light" | "custom"

`Private`customTheme

customTheme: Theme | null = null

`Private`database

database: Database

`Private`debouncedHighlight

debouncedHighlight: () => Promise<void> & { cancel: () => void } = ...

`Private`dragDropCleanup

dragDropCleanup: (() => void) | null = null

`Private`eventListeners

eventListeners: Map<keyof TerminalEvents, Set<TerminalEventListener<any>>> = ...

`Private`history

history: HistoryStore

`Private`inputBuffer

inputBuffer: InputBuffer

`Private`lastQueryResult

lastQueryResult: QueryResult | null = null

`Private`linkProvider

linkProvider: LinkProvider

`Private`loadedFiles

loadedFiles: Map<string, FileInfo> = ...

`Private`outputMode

outputMode: "table" | "csv" | "json" | "tsv" = 'table'

`Private`pageSize

pageSize: number = 0

`Private`paginationQuery

paginationQuery: string | null = null

`Private`prompt

prompt: string

`Private`queryQueue

queryQueue: Promise<QueryResult | null> = ...

`Private`showTimer

showTimer: boolean = false

`Private`state

state: TerminalState = 'idle'

`Private`syntaxHighlighting

syntaxHighlighting: boolean = true

`Private`terminalAdapter

terminalAdapter: TerminalAdapter

`Private`totalRows

totalRows: number = 0

Methods

clear

clear(): void
Clears the terminal screen.

This removes all content from the terminal display and moves the cursor to the top-left corner.

Returns void
Example
```
terminal.clear();
terminal.writeln('Screen cleared!');
```
Implementation of TerminalInterface.clear
- Defined in terminal.ts:1886

`Private`cmdExamples

cmdExamples(): Promise<void>
Returns Promise<void>
- Defined in terminal.ts:1606

`Private`cmdFiles

cmdFiles(args: string[]): Promise<void>
Parameters
- args: string[]
Returns Promise<void>
- Defined in terminal.ts:1622

`Private`cmdHelp

cmdHelp(): void
Returns void
- Defined in terminal.ts:1524

`Private`cmdHighlight

cmdHighlight(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1700

`Private`cmdLinks

cmdLinks(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1717

`Private`cmdMode

cmdMode(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1578

`Private`cmdOpen

cmdOpen(): Promise<void>
Returns Promise<void>
- Defined in terminal.ts:1683

`Private`cmdPageSize

cmdPageSize(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1734

`Private`cmdPrompt

cmdPrompt(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1810

`Private`cmdReset

cmdReset(): Promise<void>
Returns Promise<void>
- Defined in terminal.ts:1756

`Private`cmdSchema

cmdSchema(args: string[]): Promise<void>
Parameters
- args: string[]
Returns Promise<void>
- Defined in terminal.ts:1546

`Private`cmdTables

cmdTables(): Promise<void>
Returns Promise<void>
- Defined in terminal.ts:1535

`Private`cmdTheme

cmdTheme(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1592

`Private`cmdTimer

cmdTimer(args: string[]): void
Parameters
- args: string[]
Returns void
- Defined in terminal.ts:1561

copyLastResult

copyLastResult(): Promise<boolean>
Copy last query result to clipboard

Returns Promise<boolean>
- Defined in terminal.ts:1248

destroy

destroy(): void
Cleans up resources and event listeners.

Call this method when disposing of the terminal to prevent memory leaks. This removes drag-and-drop handlers and clears internal state.

Returns void
- Defined in terminal.ts:485

`Private`displayResult

displayResult(result: QueryResult): void
Displays a query result in the current output mode.

Formats and writes the result as table, CSV, TSV, or JSON based on the current outputMode setting.
Parameters
- result: QueryResult
  The query result to display
Returns void
- Defined in terminal.ts:1499

`Private`emit

emit<K extends keyof TerminalEvents>(event: K, payload: TerminalEvents[K]): void
Internal
Emits an event to all registered listeners.
Type Parameters
- K extends keyof TerminalEvents
  The event type key from TerminalEvents
Parameters
- event: K
  The event name to emit
- payload: TerminalEvents[K]
  The event payload to pass to listeners
Returns void
- Defined in terminal.ts:250

`Private`executeCommand

executeCommand(input: string): Promise<void>
Executes a dot command (e.g., .help, .tables, .schema).

Parses the command and arguments, looks up the handler, and executes it. Emits 'commandExecute' event on execution and 'error' on failure.
Parameters
- input: string
  The full command string including arguments
Returns Promise<void>
- Defined in terminal.ts:1286

`Private`executePaginatedQuery

executePaginatedQuery(): Promise<QueryResult | null>
Executes the current paginated query for the current page.

Adds LIMIT/OFFSET to the stored query and displays results with pagination controls.

Returns Promise<QueryResult | null>
The query result for the current page, or null on error
- Defined in terminal.ts:1441

executeSQL

executeSQL(sql: string): Promise<QueryResult | null>
Executes a SQL query and displays the results.

This method executes the provided SQL statement against the DuckDB database, displays the results in the configured output format (table, CSV, or JSON), and adds the query to the command history.

For large result sets (when pagination is enabled via .pagesize), the method will automatically paginate the results and enter pagination mode.
Parameters
- sql: string
  The SQL statement to execute (should end with a semicolon)
Returns Promise<QueryResult | null>
A promise that resolves to the query result, or null if an error occurred
Fires
queryStart - Emitted before query execution begins

Fires
queryEnd - Emitted after query execution completes (success or failure)

Fires
error - Emitted if the query fails
Example: Execute a SELECT query
```
const result = await terminal.executeSQL('SELECT * FROM users;');
if (result) {
  console.log(`Retrieved ${result.rowCount} rows in ${result.duration}ms`);
  console.log('Columns:', result.columns);
  console.log('First row:', result.rows[0]);
}
```
Example: Execute DDL statements
```
await terminal.executeSQL('CREATE TABLE products (id INTEGER, name VARCHAR);');
await terminal.executeSQL("INSERT INTO products VALUES (1, 'Widget');");
```
Implementation of TerminalInterface.executeSQL
- Defined in terminal.ts:1342

`Private`executeSQLInternal

executeSQLInternal(sql: string): Promise<QueryResult | null>
Internal
Internal SQL execution logic.
Parameters
- sql: string
  The SQL statement to execute
Returns Promise<QueryResult | null>
The query result, or null on error
- Defined in terminal.ts:1356

`Private`exitPagination

exitPagination(): void
Exits pagination mode and resets pagination state.

Returns void
- Defined in terminal.ts:1484

`Private`findCommonPrefix

findCommonPrefix(strings: string[]): string
Finds the longest common prefix among an array of strings.

Used for auto-completion to expand to the longest unambiguous prefix.
Parameters
- strings: string[]
  Array of strings to find common prefix for
Returns string
The longest common prefix (case-insensitive comparison)
- Defined in terminal.ts:1201

`Private`getCurrentThemeObject

getCurrentThemeObject(): Theme
Returns the current theme object for terminal styling.

Returns Theme
The custom theme if set, otherwise the built-in theme ('dark' or 'light')
- Defined in terminal.ts:382

`Private`getHighlightedSQLAsync

getHighlightedSQLAsync(sql: string): Promise<string>
Asynchronously highlights SQL using DuckDB's tokenizer.
Parameters
- sql: string
  The SQL string to highlight
Returns Promise<string>
The highlighted SQL string with ANSI color codes
- Defined in terminal.ts:285

getTheme

getTheme(): "dark" | "light"
Gets the current theme mode.

Returns 'dark' or 'light' based on the current theme. For custom themes, this returns 'light' if the theme name is 'light', otherwise 'dark'.

Returns "dark" | "light"
The current theme mode: 'dark' or 'light'
Example
```
const mode = terminal.getTheme();
console.log(`Current theme mode: ${mode}`);
```
Implementation of TerminalInterface.getTheme
- Defined in terminal.ts:1962

`Private`handleArrowDown

handleArrowDown(): void
Navigates to the next command in history (Arrow Down).

Returns void
- Defined in terminal.ts:1125

`Private`handleArrowUp

handleArrowUp(): void
Navigates to the previous command in history (Arrow Up).

Returns void
- Defined in terminal.ts:1109

`Private`handleChar

handleChar(char: string): void
Processes a single character of user input.

Handles special characters (Enter, Backspace, Tab, Ctrl sequences) and regular printable characters including Unicode.
Parameters
- char: string
  The single character to process
Returns void
- Defined in terminal.ts:918

`Private`handleCtrlC

handleCtrlC(): void
Handles Ctrl+C to cancel current input or multi-line collection.

Returns void
- Defined in terminal.ts:1218

`Private`handleDroppedFiles

handleDroppedFiles(files: File[]): Promise<void>
Processes files dropped onto the terminal via drag-and-drop.

Uses Promise.allSettled to ensure all files are attempted even if some fail.
Parameters
- files: File[]
  Array of File objects to load into DuckDB
Returns Promise<void>
- Defined in terminal.ts:506

`Private`handleEnter

handleEnter(): Promise<void>
Handles the Enter key press.

For dot commands, executes immediately. For SQL, collects lines until a semicolon terminates the statement, then executes.

Returns Promise<void>
- Defined in terminal.ts:1035

`Private`handleEscapeSequence

handleEscapeSequence(seq: string): void
Processes VT100 escape sequences for special keys.

Handles arrow keys (up/down for history, left/right for cursor), Home, End, and Delete keys.
Parameters
- seq: string
  The escape sequence string (e.g., '\x1b[A' for Arrow Up)
Returns void
- Defined in terminal.ts:1003

`Private`handleInput

handleInput(data: string): void
Handles raw terminal input data.

Routes input to the appropriate handler based on terminal state (executing, paginating, or normal input mode). Processes escape sequences separately from regular character input.
Parameters
- data: string
  The raw input data from the terminal
Returns void
- Defined in terminal.ts:813

`Private`handlePaginationInput

handlePaginationInput(data: string): Promise<void>
Handles input during pagination mode.

Supports: [n]ext page, [p]revious page, [q]uit, page number entry, and arrow keys for navigation.
Parameters
- data: string
  The input character or escape sequence
Returns Promise<void>
- Defined in terminal.ts:843

`Private`handlePaste

handlePaste(): Promise<void>
Handles Ctrl+V to paste content from clipboard.

Inserts text character-by-character, skipping newlines.

Returns Promise<void>
- Defined in terminal.ts:1231

`Private`handleResize

handleResize(cols: number): void
Handles terminal resize events.

Updates the InputBuffer with the new terminal width and redraws the current input line to ensure proper visual alignment after resize.
Parameters
- cols: number
  The new terminal width in columns
Returns void
- Defined in terminal.ts:739

`Private`handleTab

handleTab(): Promise<void>
Handles Tab key for auto-completion.

Provides suggestions for SQL keywords, table names, and functions. Single match is applied directly; multiple matches are displayed.

Returns Promise<void>
- Defined in terminal.ts:1144

`Private`isHighlightTrigger

isHighlightTrigger(char: string): boolean
Checks if a character should trigger syntax highlighting redraw.
Parameters
- char: string
  The character to check
Returns boolean
True if the character is a highlighting trigger (space, semicolon, parentheses, comma)
- Defined in terminal.ts:990

`Private`loadFile

loadFile(file: File): Promise<boolean>
Loads a file into DuckDB's virtual filesystem.

Registers the file and displays usage hints for supported file types (CSV, Parquet, JSON). Emits a 'fileLoaded' event on success.
Parameters
- file: File
  The file to load
Returns Promise<boolean>
True if the file was loaded successfully, false otherwise
- Defined in terminal.ts:534

off

off<K extends keyof TerminalEvents>(
event: K,
listener: TerminalEventListener<K>,
): void
Unsubscribes a listener from a terminal event.

This is an alternative to using the unsubscribe function returned by on.
Type Parameters
- K extends keyof TerminalEvents
  The event type key from TerminalEvents
Parameters
- event: K
  The event name to unsubscribe from
- listener: TerminalEventListener<K>
  The callback function to remove
Returns void
Example
```
const handler = ({ sql }) => console.log(sql);
terminal.on('queryStart', handler);

// Later:
terminal.off('queryStart', handler);
```
- Defined in terminal.ts:235

on

on<K extends keyof TerminalEvents>(
event: K,
listener: TerminalEventListener<K>,
): () => void
Subscribes to a terminal event.

The terminal emits various events during its lifecycle that you can subscribe to for monitoring, logging, or integrating with your application.
Type Parameters
- K extends keyof TerminalEvents
  The event type key from TerminalEvents
Parameters
- event: K
  The event name to subscribe to
- listener: TerminalEventListener<K>
  The callback function to invoke when the event occurs
Returns () => void
An unsubscribe function that removes the listener when called
Example: Subscribe to query events
```
const unsubscribe = terminal.on('queryEnd', ({ sql, result, duration }) => {
  console.log(`Query completed in ${duration}ms`);
});

// Later, to stop listening:
unsubscribe();
```
Example: Monitor state changes
```
terminal.on('stateChange', ({ state, previous }) => {
  console.log(`Terminal state: ${previous} -> ${state}`);
});
```
- Defined in terminal.ts:204

`Private`redrawInputLine

redrawInputLine(
_oldCursorPos: { col: number; row: number },
_oldEndPos: { col: number; row: number },
): void
Redraws the current input line from scratch.

After a terminal resize, Ghostty re-wraps content and the cursor position becomes unpredictable. The safest approach is to:
1. Print a newline to ensure we're on a fresh line
2. Redraw the prompt and content from scratch
This may result in the old (garbled) content remaining visible above, but the current input will be correctly displayed and functional.
Parameters
- _oldCursorPos: { col: number; row: number }
  The cursor position before the change (unused, kept for API stability)
- _oldEndPos: { col: number; row: number }
  The end position before the change (unused, kept for API stability)
Returns void
- Defined in terminal.ts:774

`Private`redrawLineHighlighted

redrawLineHighlighted(): Promise<void>
Redraws the current input line with syntax highlighting applied.

This method clears the current line content and rewrites it with color codes for SQL keywords, strings, numbers, etc. Called on delimiter characters (space, semicolon, parentheses, comma) via debouncing.

Uses DuckDB's internal parser via the poached extension for accurate tokenization.

Returns Promise<void>
- Defined in terminal.ts:307

`Private`registerCommands

registerCommands(): void
Registers all built-in dot commands (.help, .tables, .schema, etc.).

Called during construction to populate the commands map with handlers for terminal commands.

Returns void
- Defined in terminal.ts:609

`Private`resolveContainer

resolveContainer(): HTMLElement
Resolves the container element from the configuration.

Returns HTMLElement
The resolved HTML element to attach the terminal to

Throws
Error if the container selector doesn't match any element
- Defined in terminal.ts:592

`Private`setState

setState(newState: TerminalState): void
Internal
Sets the terminal state and emits a stateChange event.
Parameters
- newState: TerminalState
  The new terminal state
Returns void
- Defined in terminal.ts:269

setTheme

setTheme(theme: Theme | "dark" | "light"): void
Sets the terminal color theme.

You can set a built-in theme ('dark' or 'light') or provide a custom theme object with your own colors. Built-in theme preferences are persisted to localStorage.
Parameters
- theme: Theme | "dark" | "light"
  The theme to apply: 'dark', 'light', or a custom Theme object
Returns void
Fires
themeChange - Emitted after the theme is changed
Example: Set a built-in theme
```
terminal.setTheme('light');
```
Example: Set a custom theme
```
terminal.setTheme({
  name: 'my-theme',
  colors: {
    background: '#1a1b26',
    foreground: '#a9b1d6',
    cursor: '#c0caf5',
    // ... other color properties
  },
});
```
Implementation of TerminalInterface.setTheme
- Defined in terminal.ts:1919

`Private`showPrompt

showPrompt(): void
Displays the command prompt (primary or continuation based on state).

Sets terminal state to 'idle' if not currently collecting multi-line SQL.

Returns void
- Defined in terminal.ts:721

start

start(): Promise<void>
Initializes and starts the terminal.

This method performs the following initialization steps:
1. Resolves the container element
2. Initializes the terminal adapter (Ghostty), database (DuckDB), and history store in parallel
3. Sets up input handling and drag-and-drop file loading
4. Displays the welcome message (if enabled)
5. Shows the command prompt
6. Emits the 'ready' event
Returns Promise<void>
A promise that resolves when the terminal is fully initialized
Throws
Error if the container element cannot be found

Throws
Error if DuckDB WASM initialization fails
Example
```
const terminal = new DuckDBTerminal({ container: '#terminal' });
await terminal.start();
console.log('Terminal is ready!');
```
Fires
ready - Emitted when initialization is complete
- Defined in terminal.ts:414

write

write(text: string): void
Writes text to the terminal without a trailing newline.

Use this method for inline output where you don't want to start a new line. The text is written directly to the terminal without any processing.
Parameters
- text: string
  The text to write to the terminal
Returns void
Example
```
terminal.write('Loading');
terminal.write('...');
terminal.write(' Done!\n');
```
Implementation of TerminalInterface.write
- Defined in terminal.ts:1848

writeln

writeln(text: string): void
Writes text to the terminal followed by a newline.

The text is processed for clickable URLs (if link detection is enabled) and newlines are normalized to CRLF for proper terminal display.
Parameters
- text: string
  The text to write to the terminal
Returns void
Example
```
terminal.writeln('Query completed successfully!');
terminal.writeln('Visit https://duckdb.org for documentation');
```
Implementation of TerminalInterface.writeln
- Defined in terminal.ts:1866

Class DuckDBTerminal

Implements

Example: Basic usage

Example: With custom prompts

Example: With event listeners

Example: Programmatic SQL execution

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns DuckDBTerminal

Properties

PrivatecollectedSQL

Privatecommands

Privateconfig

PrivatecontinuationPrompt

PrivatecurrentPage

PrivatecurrentThemeName

PrivatecustomTheme

Privatedatabase

PrivatedebouncedHighlight

PrivatedragDropCleanup

PrivateeventListeners

Privatehistory

PrivateinputBuffer

PrivatelastQueryResult

PrivatelinkProvider

PrivateloadedFiles

PrivateoutputMode

PrivatepageSize

PrivatepaginationQuery

Privateprompt

PrivatequeryQueue

PrivateshowTimer

Privatestate

PrivatesyntaxHighlighting

PrivateterminalAdapter

PrivatetotalRows

Methods

clear

Returns void

Example

PrivatecmdExamples

Returns Promise<void>

PrivatecmdFiles

Parameters

Returns Promise<void>

PrivatecmdHelp

Returns void

PrivatecmdHighlight

Parameters

Returns void

PrivatecmdLinks

Parameters

Returns void

PrivatecmdMode

Parameters

Returns void

PrivatecmdOpen

Returns Promise<void>

PrivatecmdPageSize

Parameters

Returns void

PrivatecmdPrompt

Parameters

Returns void

PrivatecmdReset

Returns Promise<void>

PrivatecmdSchema

Parameters

Returns Promise<void>

PrivatecmdTables

Returns Promise<void>

PrivatecmdTheme

Parameters

Returns void

`Private`collectedSQL

`Private`commands

`Private`config

`Private`continuationPrompt

`Private`currentPage

`Private`currentThemeName

`Private`customTheme

`Private`database

`Private`debouncedHighlight

`Private`dragDropCleanup

`Private`eventListeners

`Private`history

`Private`inputBuffer

`Private`lastQueryResult

`Private`linkProvider

`Private`loadedFiles

`Private`outputMode

`Private`pageSize

`Private`paginationQuery

`Private`prompt

`Private`queryQueue

`Private`showTimer

`Private`state

`Private`syntaxHighlighting

`Private`terminalAdapter

`Private`totalRows

`Private`cmdExamples

`Private`cmdFiles

`Private`cmdHelp

`Private`cmdHighlight

`Private`cmdLinks

`Private`cmdMode

`Private`cmdOpen

`Private`cmdPageSize

`Private`cmdPrompt

`Private`cmdReset

`Private`cmdSchema

`Private`cmdTables

`Private`cmdTheme

`Private`cmdTimer

`Private`displayResult

`Private`emit

`Private`executeCommand

`Private`executePaginatedQuery

`Private`executeSQLInternal

`Private`exitPagination

`Private`findCommonPrefix

`Private`getCurrentThemeObject

`Private`getHighlightedSQLAsync

`Private`handleArrowDown

`Private`handleArrowUp

`Private`handleChar

`Private`handleCtrlC

`Private`handleDroppedFiles

`Private`handleEnter

`Private`handleEscapeSequence

`Private`handleInput

`Private`handlePaginationInput

`Private`handlePaste

`Private`handleResize