https://github.com/tobilg/vue-sql-workbench-embedded

Last synced: 29 days ago
JSON representation
Host: GitHub
URL: https://github.com/tobilg/vue-sql-workbench-embedded
Owner: tobilg
License: mit
Created: 2025-10-27T14:57:59.000Z (9 months ago)
Default Branch: main
Last Pushed: 2025-10-28T17:36:07.000Z (9 months ago)
Last Synced: 2025-10-29T02:16:24.225Z (9 months ago)
Language: TypeScript
Size: 78.1 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          # Vue 3 SQL Workbench Embedded

A Vue 3 wrapper component for [sql-workbench-embedded](https://github.com/tobilg/sql-workbench-embedded), which provides an interactive SQL editor powered by DuckDB WASM.

## Features

- 🚀 Easy integration with Vue 3 applications

- 🎨 Theme support (light, dark, auto)

- ✏️ Editable or read-only SQL code

- 🔧 Full TypeScript support

- 📦 Tree-shakeable ESM and UMD builds

- 🎯 Template ref support for programmatic access

## Installation

```bash

npm install vue-sql-workbench-embedded

# or

yarn add vue-sql-workbench-embedded

# or

pnpm add vue-sql-workbench-embedded

```

## Usage

### CDN Usage

#### ES Module (Recommended)

**Important:** When using the ESM build in browsers, you need an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to resolve the `"vue"` dependency.

```html

  

  

    {

      "imports": {

        "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"

      }

    }

  

  


  

    import { createApp, h } from 'vue';

    import { SQLWorkbenchEmbedded, SQLWorkbenchProvider } from 'https://unpkg.com/vue-sql-workbench-embedded@latest/dist/vue-sql-workbench-embedded.esm.js';

    const app = createApp({

      setup() {

        return () => h(SQLWorkbenchProvider, {}, () => [

          h(SQLWorkbenchEmbedded, {

            initialCode: 'SELECT * FROM generate_series(1, 10);',

            theme: 'auto',

            editable: true

          })

        ]);

      }

    });

    app.mount('#app');

  

```

#### UMD (Global)

The UMD build works directly in browsers without build tools. Use Vue's `h()` render function for component composition:

```html

  


  

  

  

    const { createApp, h } = Vue;

    const { SQLWorkbenchEmbedded, SQLWorkbenchProvider } = VueSQLWorkbenchEmbedded;

    const app = createApp({

      setup() {

        return () => h(SQLWorkbenchProvider, {}, () => [

          h(SQLWorkbenchEmbedded, {

            initialCode: 'SELECT * FROM generate_series(1, 10);',

            theme: 'auto',

            editable: true

          })

        ]);

      }

    });

    app.mount('#app');

  

```

> **Note:** Template strings (e.g., `template: '
...
'`) require Vue's template compiler and won't work with the browser ESM/UMD builds. Use the `h()` render function as shown above, or use a build tool like Vite.

### NPM Installation

```bash

npm install vue-sql-workbench-embedded

# or

yarn add vue-sql-workbench-embedded

# or

pnpm add vue-sql-workbench-embedded

```

### Basic Example

```vue

import { SQLWorkbenchEmbedded } from 'vue-sql-workbench-embedded';

const initialCode = `

SELECT * FROM generate_series(1, 10);

`;

  

```

### With Provider (Recommended for Multiple Instances)

```vue

import {

  SQLWorkbenchProvider,

  SQLWorkbenchEmbedded,

  useSQLWorkbench

} from 'vue-sql-workbench-embedded';

const { isReady, error } = useSQLWorkbench();

  

    
Error: {{ error.message }}

    Loading...

    

      

    

  

```

### Using Template Refs

```vue

import { ref, onMounted } from 'vue';

import { SQLWorkbenchEmbedded } from 'vue-sql-workbench-embedded';

const workbenchRef = ref(null);

onMounted(() => {

  // Access the underlying SQL Workbench instance

  const instance = workbenchRef.value?.getInstance();

  console.log('Workbench instance:', instance);

  // Access the container element

  const element = workbenchRef.value?.getElement();

  console.log('Container element:', element);

});

  

```

### TypeScript Usage

```vue

import { ref } from 'vue';

import {

  SQLWorkbenchEmbedded,

  SQLWorkbenchProvider,

  useSQLWorkbench,

  type SQLWorkbenchEmbeddedInstance,

  type Theme

} from 'vue-sql-workbench-embedded';

const { isReady, error } = useSQLWorkbench();

const theme = ref<Theme>('auto');

const workbenchRef = ref<InstanceType<typeof SQLWorkbenchEmbedded> | null>(null);

const onReady = (instance: SQLWorkbenchEmbeddedInstance) => {

  console.log('SQL Workbench instance ready:', instance);

};

const onError = (error: Error) => {

  console.error('SQL Workbench error:', error);

};

  

    

  

```

## API

### SQLWorkbenchEmbedded Props

| Prop | Type | Default | Description |

|------|------|---------|-------------|

| `initialCode` | `string` | `''` | Initial SQL code to display |

| `theme` | `'light' \| 'dark' \| 'auto' \| string` | `'auto'` | Color theme (auto detects system preference) |

| `editable` | `boolean` | `true` | Whether the editor is editable |

| `showOpenButton` | `boolean` | `true` | Show "Open in SQL Workbench" button |

| `className` | `string` | `''` | Custom CSS class for container |

| `style` | `Record` | `undefined` | Custom inline styles |

### SQLWorkbenchEmbedded Events

| Event | Payload | Description |

|-------|---------|-------------|

| `ready` | `SQLWorkbenchEmbeddedInstance` | Fired when the workbench is initialized |

| `error` | `Error` | Fired when initialization fails |

### SQLWorkbenchEmbedded Template Refs

| Method | Return Type | Description |

|--------|-------------|-------------|

| `getInstance()` | `SQLWorkbenchEmbeddedInstance \| null` | Get the underlying SQL Workbench instance |

| `getElement()` | `HTMLDivElement \| null` | Get the container DOM element |

### SQLWorkbenchProvider Props

| Prop | Type | Description |

|------|------|-------------|

| `config` | `SQLWorkbenchConfig` | Global configuration for SQL Workbench |

#### SQLWorkbenchConfig

| Property | Type | Default | Description |

|----------|------|---------|-------------|

| `theme` | `'light' \| 'dark' \| 'auto' \| string` | `'auto'` | Global theme |

| `editable` | `boolean` | `true` | Default editable state |

| `showOpenButton` | `boolean` | `true` | Default show open button state |

| `initQueries` | `string[]` | `[]` | Initialization queries to run |

| `duckdbVersion` | `string` | `'1.31.1-dev1.0'` | DuckDB WASM version |

| `duckdbCDN` | `string` | `'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm'` | DuckDB CDN URL |

| `baseUrl` | `string` | `'https://data.sql-workbench.com'` | Base URL for file resolution |

| `customThemes` | `Record` | `{}` | Custom theme definitions |

### SQLWorkbenchProvider Events

| Event | Payload | Description |

|-------|---------|-------------|

| `ready` | - | Fired when SQL Workbench is ready |

| `error` | `Error` | Fired when initialization fails |

### useSQLWorkbench Composable

Returns an object with:

- `isReady`: `Ref` - Whether SQL Workbench is initialized

- `error`: `Ref` - Any initialization error

### Keyboard Shortcuts

| Shortcut | Action |

|----------|--------|

| `Ctrl/Cmd + Enter` | Execute SQL query |

| `Ctrl/Cmd + Shift + Enter` | Open in SQL Workbench |

| `Ctrl/Cmd + Backspace` | Reset to original code |

| `Tab` | Insert 2 spaces |

| `Enter` | Insert newline |

## Development

```bash

# Install dependencies

npm install

# Run demo in development mode

npm run dev

# Build library

npm run build

# Run tests

npm test

# Run tests in watch mode

npm run test:watch

# Lint

npm run lint

```

### Testing Builds

The `examples/` directory contains HTML files for testing the UMD and ESM builds:

- **`examples/test-umd.html`** - Test the UMD build (can open directly in browser)

- **`examples/test-esm.html`** - Test the ESM build (requires HTTP server)

- **`examples/README.md`** - Full documentation for the test files

To test the ESM build:

```bash

# Start a local HTTP server

python3 -m http.server 8000

# Then open in browser:

# http://localhost:8000/examples/test-esm.html

```

See [examples/README.md](examples/README.md) for more details.

## License

MIT
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/tobilg/vue-sql-workbench-embedded

Awesome Lists containing this project

README
