{"id":34502662,"url":"https://github.com/tobilg/duckdb-terminal","last_synced_at":"2025-12-24T02:11:32.511Z","repository":{"id":328216866,"uuid":"1110118516","full_name":"tobilg/duckdb-terminal","owner":"tobilg","description":"A browser-based SQL Terminal for DuckDB powered by Ghostty terminal emulator.","archived":false,"fork":false,"pushed_at":"2025-12-11T18:13:15.000Z","size":453,"stargazers_count":33,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-12T22:51:58.985Z","etag":null,"topics":["duckdb","shell","sql","terminal"],"latest_commit_sha":null,"homepage":"https://terminal.sql-workbench.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobilg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T18:31:24.000Z","updated_at":"2025-12-12T15:41:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tobilg/duckdb-terminal","commit_stats":null,"previous_names":["tobilg/duckdb-terminal"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tobilg/duckdb-terminal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobilg","download_url":"https://codeload.github.com/tobilg/duckdb-terminal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fduckdb-terminal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27992997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["duckdb","shell","sql","terminal"],"created_at":"2025-12-24T02:11:32.045Z","updated_at":"2025-12-24T02:11:32.497Z","avatar_url":"https://github.com/tobilg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DuckDB Terminal\n\nA browser-based SQL Terminal for [DuckDB](https://duckdb.org/) powered by [Ghostty](https://ghostty.org/) terminal emulator.\n\n## Try it live\nThe latest version is always deployed to [https://terminal.sql-workbench.com](https://terminal.sql-workbench.com).\n\n## API Docs\nThe TypeScript API Docs can be found at [https://tobilg.github.io/duckdb-terminal](https://tobilg.github.io/duckdb-terminal/).\n\n## Features\n\n- **Full SQL REPL** - Execute SQL queries with multi-line support\n- **Command History** - Navigate previous commands with arrow keys (persisted in IndexedDB)\n- **Auto-Complete** - Tab completion for SQL keywords, table names, and functions\n- **Multiple Output Modes** - Table, CSV, TSV, or JSON output formats\n- **Clipboard Support** - Copy query results to clipboard in any output format\n- **Result Pagination** - Navigate large result sets page by page\n- **Syntax Highlighting** - Color-coded SQL keywords, strings, and numbers\n- **Clickable URLs** - Automatically detect and make URLs clickable in results\n- **File Loading** - Load CSV, Parquet, and JSON files via drag-and-drop or file picker\n- **Dark/Light Themes** - Switchable themes with custom theme support\n- **Customizable Prompts** - Configure primary and continuation prompts\n- **Dot Commands** - Terminal commands like `.help`, `.tables`, `.schema`\n- **Query Timing** - Optional execution time display\n- **Persistent Storage** - Optional OPFS storage for data persistence\n- **Interactive Charts** - Visualize query results with auto-detected chart types (line, bar, scatter, histogram)\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                                 Browser                                     │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                             │\n│  ┌───────────────────────────────────────────────────────────────────────┐  │\n│  │                          DuckDB Terminal                              │  │\n│  │                                                                       │  │\n│  │  ┌─────────────────────────────────────────────────────────────────┐  │  │\n│  │  │                         Terminal                                │  │  │\n│  │  │                                                                 │  │  │\n│  │  │  - REPL (input, output, history)                                │  │  │\n│  │  │  - Command parsing (SQL, dot commands, multi-line)              │  │  │\n│  │  │  - Result formatting (table, CSV, TSV, JSON)                    │  │  │\n│  │  │  - Syntax highlighting                                          │  │  │\n│  │  └───────┬─────────────────────┬─────────────────────────┬─────────┘  │  │\n│  │          │                     │                         │            │  │\n│  │          ▼                     ▼                         │            │  │\n│  │  ┌───────────────┐   ┌─────────────────────┐             │            │  │\n│  │  │ Terminal      │   │      Database       │             │            │  │\n│  │  │ Adapter       │   │                     │             │            │  │\n│  │  │               │   │ - DuckDB WASM       │             │            │  │\n│  │  │ - Ghostty     │   │   wrapper           │             │            │  │\n│  │  │ - Themes      │   │ - Query execution   │             │            │  │\n│  │  │ - Keyboard    │   │ - Auto-complete     │             │            │  │\n│  │  │ - Mobile      │   │ - File loading      │             │            │  │\n│  │  └───────┬───────┘   └─────────┬───────────┘             │            │  │\n│  │          │                     │                         │            │  │\n│  └──────────┼─────────────────────┼─────────────────────────┼────────────┘  │\n│             │                     │                         │               │\n│             ▼                     ▼                         ▼               │\n│  ┌────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐   │\n│  │    Ghostty Web     │  │    DuckDB WASM      │  │     IndexedDB       │   │\n│  │    (npm package)   │  │    (Web Worker)     │  │  (Command History)  │   │\n│  │                    │  │                     │  │                     │   │\n│  │ - Canvas rendering │  │ - SQL engine        │  └─────────────────────┘   │\n│  │ - VT100 emulation  │  │ - Query processing  │                            │\n│  └────────────────────┘  └──────────┬──────────┘                            │\n│                                     │                                       │\n│                                     ▼                                       │\n│                          ┌─────────────────────┐                            │\n│                          │        OPFS         │                            │\n│                          │  (Database Storage) │                            │\n│                          └─────────────────────┘                            │\n│                                                                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## Installation\n\n```bash\nnpm install duckdb-terminal\n```\n\n## Quick Start\n\n### As a Library\n\n```typescript\nimport { createTerminal } from 'duckdb-terminal';\n\nconst Terminal = await createTerminal({\n  container: '#terminal',\n  theme: 'dark',\n});\n```\n\n### As a Standalone App\n\n```bash\ngit clone https://github.com/tobilg/duckdb-terminal.git\ncd duckdb-terminal\nnpm install\nnpm run dev\n```\n\nOpen http://localhost:5173 in your browser.\n\n## Configuration\n\n```typescript\ninterface TerminalConfig {\n  // Container element or CSS selector\n  container: HTMLElement | string;\n\n  // Font family (default: 'Fira Code', 'Cascadia Code', etc.)\n  fontFamily?: string;\n\n  // Font size in pixels (default: 14)\n  fontSize?: number;\n\n  // Theme: 'dark' | 'light' | Theme (default: 'dark')\n  theme?: 'dark' | 'light' | Theme;\n\n  // Storage: 'memory' | 'opfs' (default: 'memory')\n  storage?: 'memory' | 'opfs';\n\n  // Database path for OPFS storage\n  databasePath?: string;\n\n  // Show welcome message (default: true)\n  // When enabled, displays loading progress during DuckDB initialization\n  welcomeMessage?: boolean;\n\n  // Primary prompt string (default: '🦆 ')\n  prompt?: string;\n\n  // Continuation prompt for multi-line SQL (default: '  \u003e ')\n  continuationPrompt?: string;\n\n  // Enable clickable URL detection (default: true)\n  linkDetection?: boolean;\n\n  // Scrollback buffer size in bytes (default: 10485760 = 10MB)\n  scrollback?: number;\n\n  // Enable interactive charts feature (default: false)\n  enableCharts?: boolean;\n}\n```\n\n## Terminal Commands\n\n| Command | Description |\n|---------|-------------|\n| `.help` | Show available commands |\n| `.clear` | Clear the terminal |\n| `.clearhistory` | Clear command history |\n| `.tables` | List all tables |\n| `.schema \u003ctable\u003e` | Show table schema |\n| `.timer on\\|off` | Toggle query timing |\n| `.mode table\\|csv\\|tsv\\|json` | Set output format |\n| `.copy` | Copy last query results to clipboard |\n| `.download [filename]` | Download last result as file (format based on mode) |\n| `.pagesize \u003cn\u003e` | Set pagination size (0 to disable) |\n| `.theme dark\\|light` | Switch color theme (clears screen) |\n| `.highlight on\\|off` | Toggle syntax highlighting |\n| `.links on\\|off` | Toggle clickable URL detection |\n| `.files [list\\|add\\|remove]` | Manage loaded files (list, add, or remove) |\n| `.open` | Open file picker to load data files |\n| `.prompt [primary [cont]]` | Get or set the command prompt |\n| `.examples` | Show example queries |\n| `.reset` | Reset database and all settings to defaults |\n| `.chart [options]` | Show interactive chart of last query result |\n\n## Charts\n\nThe terminal includes an interactive charting feature powered by [uPlot](https://github.com/leeoniya/uPlot). Charts are displayed as an overlay on top of the terminal and support hover tooltips, legends, and PNG export.\n\n\u003e **Note:** Charts must be enabled in the configuration with `enableCharts: true`. The uPlot library (~50KB) is loaded from CDN on first use.\n\n### Basic Usage\n\n```sql\n-- Run a query, then visualize it\nSELECT date, revenue, cost FROM sales;\n.chart\n```\n\n### Chart Type Auto-Detection\n\nThe chart type is automatically detected based on your data:\n\n| Data Pattern | Chart Type | Example |\n|--------------|------------|---------|\n| Temporal + Numeric columns | **Line** | `DATE` + `revenue` → time series |\n| Categorical + Numeric columns | **Bar** | `category` + `total` → bar chart |\n| Two Numeric columns only | **Scatter** | `x_value` + `y_value` → scatter plot |\n| Single Numeric column | **Histogram** | `value` → distribution histogram |\n| Multiple Numeric columns | **Line** | `col1`, `col2`, `col3` → multi-series line |\n\n### Command Options\n\n| Option | Description | Example |\n|--------|-------------|---------|\n| `type=TYPE` | Force chart type: `line`, `bar`, `scatter`, `histogram` | `.chart type=bar` |\n| `x=COLUMN` | Specify X-axis column | `.chart x=date` |\n| `y=COLUMN` | Specify Y-axis column(s), comma-separated | `.chart y=revenue,cost` |\n| `export` | Export chart as PNG | `.chart export` |\n\n### Examples\n\n```sql\n-- Line chart: Time series with multiple series\nSELECT DATE '2024-01-01' + INTERVAL (i) DAY AS date,\n       100 + random() * 50 AS revenue,\n       80 + random() * 30 AS cost\nFROM generate_series(0, 11) AS t(i);\n.chart\n\n-- Bar chart: Categorical data\nSELECT category, SUM(amount) as total\nFROM (VALUES\n    ('Electronics', 1500),\n    ('Clothing', 800),\n    ('Food', 1200),\n    ('Books', 400),\n    ('Toys', 600)\n) AS t(category, amount)\nGROUP BY category;\n.chart\n\n-- Scatter plot: Two numeric columns\nSELECT random() * 100 AS x_value,\n       random() * 100 AS y_value\nFROM generate_series(1, 50);\n.chart\n\n-- Histogram: Single numeric column distribution\nSELECT (random() * 100)::INTEGER AS value\nFROM generate_series(1, 200);\n.chart\n\n-- Multi-series bar chart\nSELECT region,\n       SUM(CASE WHEN product = 'A' THEN sales ELSE 0 END) as product_a,\n       SUM(CASE WHEN product = 'B' THEN sales ELSE 0 END) as product_b\nFROM (VALUES\n    ('North', 'A', 120), ('North', 'B', 90),\n    ('South', 'A', 80), ('South', 'B', 150),\n    ('East', 'A', 200), ('East', 'B', 110),\n    ('West', 'A', 95), ('West', 'B', 130)\n) AS t(region, product, sales)\nGROUP BY region;\n.chart\n\n-- Line chart with numeric X axis (sine/cosine waves)\nSELECT i AS x,\n       sin(i * 0.5) * 50 + 50 AS sine_wave,\n       cos(i * 0.5) * 50 + 50 AS cosine_wave\nFROM generate_series(0, 20) AS t(i);\n.chart\n\n-- Force specific chart type and axes\n.chart type=line x=date y=revenue,cost\n```\n\n### Chart Interaction\n\n| Key | Action |\n|-----|--------|\n| Hover | Show tooltip with values at cursor position |\n| `ESC` | Close the chart |\n| `Ctrl+S` / `Cmd+S` | Export chart as PNG |\n\n## Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `Enter` | Execute command/SQL |\n| `Tab` | Auto-complete |\n| `Backspace` | Delete character before cursor |\n| `Delete` | Delete character at cursor |\n| `↑` / `↓` | Navigate history |\n| `←` / `→` | Move cursor |\n| `Home` | Move to start of line |\n| `End` | Move to end of line |\n| `Ctrl+A` | Move to start of line |\n| `Ctrl+E` | Move to end of line |\n| `Ctrl+K` | Clear from cursor to end of line |\n| `Ctrl+U` | Clear entire line |\n| `Ctrl+V` | Paste from clipboard |\n| `Ctrl+C` | Cancel current input |\n\n### Pagination Mode\n\nWhen viewing paginated results, the following keys are available:\n\n| Key | Action |\n|-----|--------|\n| `n` / `↓` / `Enter` | Next page |\n| `p` / `↑` | Previous page |\n| `q` / `Escape` / `Ctrl+C` | Quit pagination |\n\n## Example Usage\n\n```sql\n-- Create a table\nCREATE TABLE users (\n  id INTEGER PRIMARY KEY,\n  name VARCHAR,\n  email VARCHAR\n);\n\n-- Insert data\nINSERT INTO users VALUES\n  (1, 'Alice', 'alice@example.com'),\n  (2, 'Bob', 'bob@example.com');\n\n-- Query data\nSELECT * FROM users WHERE name LIKE 'A%';\n\n-- Use built-in functions\nSELECT range(10), current_timestamp;\n```\n\n## Querying and Copying Results\n\nThe terminal supports four output formats and provides an easy way to copy query results to your clipboard.\n\n### Output Formats\n\nUse the `.mode` command to switch between output formats:\n\n```sql\n-- Table format (default) - human-readable ASCII table\n.mode table\nSELECT * FROM users;\n+----+-------+-------------------+\n| id | name  | email             |\n+----+-------+-------------------+\n| 1  | Alice | alice@example.com |\n| 2  | Bob   | bob@example.com   |\n+----+-------+-------------------+\n\n-- CSV format - comma-separated values\n.mode csv\nSELECT * FROM users;\nid,name,email\n1,Alice,alice@example.com\n2,Bob,bob@example.com\n\n-- TSV format - tab-separated values\n.mode tsv\nSELECT * FROM users;\nid\tname\temail\n1\tAlice\talice@example.com\n2\tBob\tbob@example.com\n\n-- JSON format - array of objects\n.mode json\nSELECT * FROM users;\n[\n  {\"id\": 1, \"name\": \"Alice\", \"email\": \"alice@example.com\"},\n  {\"id\": 2, \"name\": \"Bob\", \"email\": \"bob@example.com\"}\n]\n```\n\n### Copying Results\n\nAfter running a query, use `.copy` to copy the results to your clipboard in the current output format:\n\n```sql\n-- Run your query\nSELECT * FROM users WHERE active = true;\n\n-- Copy results to clipboard (uses current .mode format)\n.copy\n```\n\nThe copied content respects your current output mode, so you can:\n1. Use `.mode csv` or `.mode tsv` then `.copy` to paste into a spreadsheet\n2. Use `.mode json` then `.copy` to paste into a JSON file or API tool\n3. Use `.mode table` then `.copy` to paste formatted output into documentation\n\n### Pagination for Large Results\n\nFor large result sets, enable pagination with `.pagesize`:\n\n```sql\n-- Enable pagination (50 rows per page)\n.pagesize 50\n\n-- Run a query with many results\nSELECT * FROM large_table;\n\n-- Navigate pages:\n-- n or Enter - next page\n-- p - previous page\n-- 1-9 - jump to page number\n-- q - quit pagination\n```\n\nSet `.pagesize 0` to disable pagination and show all results at once.\n\n**Note:** Queries that already contain `LIMIT` or `OFFSET` clauses bypass pagination, giving you full control over result size.\n\n## Custom Themes\n\nYou can create custom themes by providing a `Theme` object instead of `'dark'` or `'light'`:\n\n```typescript\nimport { createTerminal, type Theme, type ThemeColors } from 'duckdb-terminal';\n\n// Define custom colors\nconst myColors: ThemeColors = {\n  background: '#1a1b26',    // Terminal background\n  foreground: '#a9b1d6',    // Default text color\n  cursor: '#c0caf5',        // Cursor color\n  selection: '#33467c',     // Selection highlight\n  // Standard ANSI colors\n  black: '#15161e',\n  red: '#f7768e',\n  green: '#9ece6a',\n  yellow: '#e0af68',\n  blue: '#7aa2f7',\n  magenta: '#bb9af7',\n  cyan: '#7dcfff',\n  white: '#a9b1d6',\n  // Bright variants\n  brightBlack: '#414868',\n  brightRed: '#f7768e',\n  brightGreen: '#9ece6a',\n  brightYellow: '#e0af68',\n  brightBlue: '#7aa2f7',\n  brightMagenta: '#bb9af7',\n  brightCyan: '#7dcfff',\n  brightWhite: '#c0caf5',\n};\n\n// Create theme object\nconst tokyoNight: Theme = {\n  name: 'tokyo-night',\n  colors: myColors,\n};\n\n// Use custom theme\nconst Terminal = await createTerminal({\n  container: '#terminal',\n  theme: tokyoNight,\n});\n\n// You can also change theme at runtime\nTerminal.setTheme(tokyoNight);\n```\n\n### ThemeColors Reference\n\n| Property | Description | ANSI Code |\n|----------|-------------|-----------|\n| `background` | Terminal background color | - |\n| `foreground` | Default text color | - |\n| `cursor` | Cursor color | - |\n| `selection` | Text selection highlight | - |\n| `black` | ANSI black | `\\x1b[30m` |\n| `red` | ANSI red | `\\x1b[31m` |\n| `green` | ANSI green | `\\x1b[32m` |\n| `yellow` | ANSI yellow | `\\x1b[33m` |\n| `blue` | ANSI blue | `\\x1b[34m` |\n| `magenta` | ANSI magenta | `\\x1b[35m` |\n| `cyan` | ANSI cyan | `\\x1b[36m` |\n| `white` | ANSI white | `\\x1b[37m` |\n| `brightBlack` | Bright black (gray) | `\\x1b[90m` |\n| `brightRed` | Bright red | `\\x1b[91m` |\n| `brightGreen` | Bright green | `\\x1b[92m` |\n| `brightYellow` | Bright yellow | `\\x1b[93m` |\n| `brightBlue` | Bright blue | `\\x1b[94m` |\n| `brightMagenta` | Bright magenta | `\\x1b[95m` |\n| `brightCyan` | Bright cyan | `\\x1b[96m` |\n| `brightWhite` | Bright white | `\\x1b[97m` |\n\n### Built-in Themes\n\nThe library exports two built-in themes that you can use directly or extend:\n\n```typescript\nimport { darkTheme, lightTheme } from 'duckdb-terminal';\n\n// Use directly\nconst Terminal = await createTerminal({\n  container: '#terminal',\n  theme: darkTheme,\n});\n\n// Or extend\nconst myTheme: Theme = {\n  name: 'my-dark',\n  colors: {\n    ...darkTheme.colors,\n    background: '#000000',  // Override specific colors\n    cursor: '#ff0000',\n  },\n};\n```\n\n## API\n\n### createTerminal(config)\n\nCreates and starts a DuckDB Terminal instance.\n\n```typescript\nimport { createTerminal } from 'duckdb-terminal';\n\nconst Terminal = await createTerminal({\n  container: document.getElementById('terminal'),\n  theme: 'dark',\n});\n\n// Write to terminal\nTerminal.write('Hello, World!');\nTerminal.writeln('With newline');\n\n// Execute SQL programmatically\nconst result = await Terminal.executeSQL('SELECT 1+1 as answer');\nconsole.log(result); // { columns: ['answer'], rows: [[2]], rowCount: 1, duration: 5 }\n\n// Change theme\nTerminal.setTheme('light');\n\n// Clear terminal\nTerminal.clear();\n\n// Clean up when done (removes event listeners, closes database)\nTerminal.destroy();\n```\n\n### Events\n\nThe Terminal emits events that you can subscribe to for monitoring and integrating with your application:\n\n```typescript\nimport { createTerminal, type TerminalEvents } from 'duckdb-terminal';\n\nconst Terminal = await createTerminal({\n  container: '#terminal',\n  theme: 'dark',\n});\n\n// Subscribe to events\nTerminal.on('ready', () =\u003e {\n  console.log('Terminal is ready!');\n});\n\nTerminal.on('queryStart', ({ sql }) =\u003e {\n  console.log('Executing:', sql);\n});\n\nTerminal.on('queryEnd', ({ sql, result, error, duration }) =\u003e {\n  if (error) {\n    console.error('Query failed:', error);\n  } else {\n    console.log(`Query completed in ${duration}ms, ${result?.rowCount} rows`);\n  }\n});\n\nTerminal.on('stateChange', ({ state, previous }) =\u003e {\n  console.log(`State changed: ${previous} -\u003e ${state}`);\n});\n\nTerminal.on('themeChange', ({ theme, previous }) =\u003e {\n  console.log(`Theme changed to: ${theme.name}`);\n});\n\nTerminal.on('fileLoaded', ({ filename, size, type }) =\u003e {\n  console.log(`Loaded file: ${filename} (${size} bytes)`);\n});\n\nTerminal.on('commandExecute', ({ command, args }) =\u003e {\n  console.log(`Command: ${command}`, args);\n});\n\nTerminal.on('error', ({ message, source }) =\u003e {\n  console.error(`Error from ${source}: ${message}`);\n});\n\n// Unsubscribe using the returned function\nconst unsubscribe = Terminal.on('queryEnd', handler);\nunsubscribe(); // Stop listening\n\n// Or use off() directly\nTerminal.off('queryEnd', handler);\n```\n\n#### Available Events\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `ready` | `{}` | Terminal is fully initialized |\n| `queryStart` | `{ sql }` | SQL query execution started |\n| `queryEnd` | `{ sql, result, error?, duration }` | SQL query completed or failed |\n| `stateChange` | `{ state, previous }` | Terminal state changed (idle, collecting, executing, paginating) |\n| `themeChange` | `{ theme, previous }` | Theme was changed |\n| `fileLoaded` | `{ filename, size, type }` | File was loaded via drag-drop or picker |\n| `commandExecute` | `{ command, args }` | Dot command was executed |\n| `error` | `{ message, source }` | An error occurred |\n\n### Advanced Usage\n\n```typescript\nimport {\n  Terminal,\n  Database,\n  TerminalAdapter,\n  formatTable,\n  formatCSV,\n  formatJSON\n} from 'duckdb-terminal';\n\n// Use Database directly\nconst db = new Database({ storage: 'memory' });\nawait db.init();\nconst result = await db.executeQuery('SELECT 42');\n\n// Use formatters\nconsole.log(formatTable(result.columns, result.rows));\nconsole.log(formatCSV(result.columns, result.rows));\nconsole.log(formatJSON(result.columns, result.rows));\n\n// Get completions\nconst suggestions = await db.getCompletions('SEL', 3);\n```\n\n## Browser Requirements\n\n- Modern browser with WebAssembly support\n- SharedArrayBuffer (requires COOP/COEP headers)\n\nFor development, Vite automatically sets the required headers. For production, configure your server:\n\n```\nCross-Origin-Opener-Policy: same-origin\nCross-Origin-Embedder-Policy: require-corp\n```\n\n## Building\n\n```bash\n# Development\nnpm run dev\n\n# Production build\nnpm run build\n\n# Run tests\nnpm test\n\n# Type checking\nnpm run typecheck\n```\n\n## Bundle Outputs\n\n| File | Format | Usage |\n|------|--------|-------|\n| `dist/duckdb-terminal.js` | ESM | Modern bundlers |\n| `dist/duckdb-terminal.umd.cjs` | UMD | Script tags, legacy |\n| `dist/*.d.ts` | TypeScript | Type definitions |\n\n## Dependencies\n\n- [@duckdb/duckdb-wasm](https://www.npmjs.com/package/@duckdb/duckdb-wasm) - DuckDB WebAssembly build\n- [ghostty-web](https://www.npmjs.com/package/ghostty-web) - Ghostty terminal emulator for web\n\n## License\n\nMIT\n\n## Credits\n\n- [DuckDB](https://duckdb.org/) - The in-process analytical database\n- [Ghostty](https://ghostty.org/) - Fast, native terminal emulator\n- [ghostty-web](https://github.com/coder/ghostty-web) - Web port by Coder\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Fduckdb-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobilg%2Fduckdb-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Fduckdb-terminal/lists"}