GitHub - tobilg/duckdb-terminal: A browser-based SQL Terminal for DuckDB powered by Ghostty terminal emulator.

┌─────────────────────────────────────────────────────────────────────────────┐
│                                 Browser                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                          DuckDB Terminal                              │  │
│  │                                                                       │  │
│  │  ┌─────────────────────────────────────────────────────────────────┐  │  │
│  │  │                         Terminal                                │  │  │
│  │  │                                                                 │  │  │
│  │  │  - REPL (input, output, history)                                │  │  │
│  │  │  - Command parsing (SQL, dot commands, multi-line)              │  │  │
│  │  │  - Result formatting (table, CSV, TSV, JSON)                    │  │  │
│  │  │  - Syntax highlighting                                          │  │  │
│  │  └───────┬─────────────────────┬─────────────────────────┬─────────┘  │  │
│  │          │                     │                         │            │  │
│  │          ▼                     ▼                         │            │  │
│  │  ┌───────────────┐   ┌─────────────────────┐             │            │  │
│  │  │ Terminal      │   │      Database       │             │            │  │
│  │  │ Adapter       │   │                     │             │            │  │
│  │  │               │   │ - DuckDB WASM       │             │            │  │
│  │  │ - Ghostty     │   │   wrapper           │             │            │  │
│  │  │ - Themes      │   │ - Query execution   │             │            │  │
│  │  │ - Keyboard    │   │ - Auto-complete     │             │            │  │
│  │  │ - Mobile      │   │ - File loading      │             │            │  │
│  │  └───────┬───────┘   └─────────┬───────────┘             │            │  │
│  │          │                     │                         │            │  │
│  └──────────┼─────────────────────┼─────────────────────────┼────────────┘  │
│             │                     │                         │               │
│             ▼                     ▼                         ▼               │
│  ┌────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐   │
│  │    Ghostty Web     │  │    DuckDB WASM      │  │     IndexedDB       │   │
│  │    (npm package)   │  │    (Web Worker)     │  │  (Command History)  │   │
│  │                    │  │                     │  │                     │   │
│  │ - Canvas rendering │  │ - SQL engine        │  └─────────────────────┘   │
│  │ - VT100 emulation  │  │ - Query processing  │                            │
│  └────────────────────┘  └──────────┬──────────┘                            │
│                                     │                                       │
│                                     ▼                                       │
│                          ┌─────────────────────┐                            │
│                          │        OPFS         │                            │
│                          │  (Database Storage) │                            │
│                          └─────────────────────┘                            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

npm install duckdb-terminal

import { createTerminal } from 'duckdb-terminal';

const Terminal = await createTerminal({
  container: '#terminal',
  theme: 'dark',
});

git clone https://github.com/tobilg/duckdb-terminal.git
cd duckdb-terminal
npm install
npm run dev

interface TerminalConfig {
  // Container element or CSS selector
  container: HTMLElement | string;

  // Font family (default: 'Fira Code', 'Cascadia Code', etc.)
  fontFamily?: string;

  // Font size in pixels (default: 14)
  fontSize?: number;

  // Theme: 'dark' | 'light' | Theme (default: 'dark')
  theme?: 'dark' | 'light' | Theme;

  // Storage: 'memory' | 'opfs' (default: 'memory')
  storage?: 'memory' | 'opfs';

  // Database path for OPFS storage
  databasePath?: string;

  // Show welcome message (default: true)
  // When enabled, displays loading progress during DuckDB initialization
  welcomeMessage?: boolean;

  // Primary prompt string (default: '🦆 ')
  prompt?: string;

  // Continuation prompt for multi-line SQL (default: '  > ')
  continuationPrompt?: string;

  // Enable clickable URL detection (default: true)
  linkDetection?: boolean;

  // Scrollback buffer size in bytes (default: 10485760 = 10MB)
  scrollback?: number;

  // Enable interactive charts feature (default: false)
  enableCharts?: boolean;
}

-- Run a query, then visualize it
SELECT date, revenue, cost FROM sales;
.chart

-- Line chart: Time series with multiple series
SELECT DATE '2024-01-01' + INTERVAL (i) DAY AS date,
       100 + random() * 50 AS revenue,
       80 + random() * 30 AS cost
FROM generate_series(0, 11) AS t(i);
.chart

-- Bar chart: Categorical data
SELECT category, SUM(amount) as total
FROM (VALUES
    ('Electronics', 1500),
    ('Clothing', 800),
    ('Food', 1200),
    ('Books', 400),
    ('Toys', 600)
) AS t(category, amount)
GROUP BY category;
.chart

-- Scatter plot: Two numeric columns
SELECT random() * 100 AS x_value,
       random() * 100 AS y_value
FROM generate_series(1, 50);
.chart

-- Histogram: Single numeric column distribution
SELECT (random() * 100)::INTEGER AS value
FROM generate_series(1, 200);
.chart

-- Multi-series bar chart
SELECT region,
       SUM(CASE WHEN product = 'A' THEN sales ELSE 0 END) as product_a,
       SUM(CASE WHEN product = 'B' THEN sales ELSE 0 END) as product_b
FROM (VALUES
    ('North', 'A', 120), ('North', 'B', 90),
    ('South', 'A', 80), ('South', 'B', 150),
    ('East', 'A', 200), ('East', 'B', 110),
    ('West', 'A', 95), ('West', 'B', 130)
) AS t(region, product, sales)
GROUP BY region;
.chart

-- Line chart with numeric X axis (sine/cosine waves)
SELECT i AS x,
       sin(i * 0.5) * 50 + 50 AS sine_wave,
       cos(i * 0.5) * 50 + 50 AS cosine_wave
FROM generate_series(0, 20) AS t(i);
.chart

-- Force specific chart type and axes
.chart type=line x=date y=revenue,cost

-- Create a table
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  name VARCHAR,
  email VARCHAR
);

-- Insert data
INSERT INTO users VALUES
  (1, 'Alice', 'alice@example.com'),
  (2, 'Bob', 'bob@example.com');

-- Query data
SELECT * FROM users WHERE name LIKE 'A%';

-- Use built-in functions
SELECT range(10), current_timestamp;

-- Table format (default) - human-readable ASCII table
.mode table
SELECT * FROM users;
+----+-------+-------------------+
| id | name  | email             |
+----+-------+-------------------+
| 1  | Alice | alice@example.com |
| 2  | Bob   | bob@example.com   |
+----+-------+-------------------+

-- CSV format - comma-separated values
.mode csv
SELECT * FROM users;
id,name,email
1,Alice,alice@example.com
2,Bob,bob@example.com

-- TSV format - tab-separated values
.mode tsv
SELECT * FROM users;
id	name	email
1	Alice	alice@example.com
2	Bob	bob@example.com

-- JSON format - array of objects
.mode json
SELECT * FROM users;
[
  {"id": 1, "name": "Alice", "email": "alice@example.com"},
  {"id": 2, "name": "Bob", "email": "bob@example.com"}
]

-- Run your query
SELECT * FROM users WHERE active = true;

-- Copy results to clipboard (uses current .mode format)
.copy

-- Enable pagination (50 rows per page)
.pagesize 50

-- Run a query with many results
SELECT * FROM large_table;

-- Navigate pages:
-- n or Enter - next page
-- p - previous page
-- 1-9 - jump to page number
-- q - quit pagination

import { createTerminal, type Theme, type ThemeColors } from 'duckdb-terminal';

// Define custom colors
const myColors: ThemeColors = {
  background: '#1a1b26',    // Terminal background
  foreground: '#a9b1d6',    // Default text color
  cursor: '#c0caf5',        // Cursor color
  selection: '#33467c',     // Selection highlight
  // Standard ANSI colors
  black: '#15161e',
  red: '#f7768e',
  green: '#9ece6a',
  yellow: '#e0af68',
  blue: '#7aa2f7',
  magenta: '#bb9af7',
  cyan: '#7dcfff',
  white: '#a9b1d6',
  // Bright variants
  brightBlack: '#414868',
  brightRed: '#f7768e',
  brightGreen: '#9ece6a',
  brightYellow: '#e0af68',
  brightBlue: '#7aa2f7',
  brightMagenta: '#bb9af7',
  brightCyan: '#7dcfff',
  brightWhite: '#c0caf5',
};

// Create theme object
const tokyoNight: Theme = {
  name: 'tokyo-night',
  colors: myColors,
};

// Use custom theme
const Terminal = await createTerminal({
  container: '#terminal',
  theme: tokyoNight,
});

// You can also change theme at runtime
Terminal.setTheme(tokyoNight);

import { darkTheme, lightTheme } from 'duckdb-terminal';

// Use directly
const Terminal = await createTerminal({
  container: '#terminal',
  theme: darkTheme,
});

// Or extend
const myTheme: Theme = {
  name: 'my-dark',
  colors: {
    ...darkTheme.colors,
    background: '#000000',  // Override specific colors
    cursor: '#ff0000',
  },
};

import { createTerminal } from 'duckdb-terminal';

const Terminal = await createTerminal({
  container: document.getElementById('terminal'),
  theme: 'dark',
});

// Write to terminal
Terminal.write('Hello, World!');
Terminal.writeln('With newline');

// Execute SQL programmatically
const result = await Terminal.executeSQL('SELECT 1+1 as answer');
console.log(result); // { columns: ['answer'], rows: [[2]], rowCount: 1, duration: 5 }

// Change theme
Terminal.setTheme('light');

// Clear terminal
Terminal.clear();

// Clean up when done (removes event listeners, closes database)
Terminal.destroy();

import { createTerminal, type TerminalEvents } from 'duckdb-terminal';

const Terminal = await createTerminal({
  container: '#terminal',
  theme: 'dark',
});

// Subscribe to events
Terminal.on('ready', () => {
  console.log('Terminal is ready!');
});

Terminal.on('queryStart', ({ sql }) => {
  console.log('Executing:', sql);
});

Terminal.on('queryEnd', ({ sql, result, error, duration }) => {
  if (error) {
    console.error('Query failed:', error);
  } else {
    console.log(`Query completed in ${duration}ms, ${result?.rowCount} rows`);
  }
});

Terminal.on('stateChange', ({ state, previous }) => {
  console.log(`State changed: ${previous} -> ${state}`);
});

Terminal.on('themeChange', ({ theme, previous }) => {
  console.log(`Theme changed to: ${theme.name}`);
});

Terminal.on('fileLoaded', ({ filename, size, type }) => {
  console.log(`Loaded file: ${filename} (${size} bytes)`);
});

Terminal.on('commandExecute', ({ command, args }) => {
  console.log(`Command: ${command}`, args);
});

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

// Unsubscribe using the returned function
const unsubscribe = Terminal.on('queryEnd', handler);
unsubscribe(); // Stop listening

// Or use off() directly
Terminal.off('queryEnd', handler);

import {
  Terminal,
  Database,
  TerminalAdapter,
  formatTable,
  formatCSV,
  formatJSON
} from 'duckdb-terminal';

// Use Database directly
const db = new Database({ storage: 'memory' });
await db.init();
const result = await db.executeQuery('SELECT 42');

// Use formatters
console.log(formatTable(result.columns, result.rows));
console.log(formatCSV(result.columns, result.rows));
console.log(formatJSON(result.columns, result.rows));

// Get completions
const suggestions = await db.getCompletions('SEL', 3);

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

# Development
npm run dev

# Production build
npm run build

# Run tests
npm test

# Type checking
npm run typecheck