Skip to content

tobilg/vue-sql-workbench-embedded

BranchesTags

Repository files navigation

Vue 3 SQL Workbench Embedded

A Vue 3 wrapper component for 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

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 to resolve the "vue" dependency.

<!DOCTYPE html>
<html>
<head>
  <!-- Import map to resolve bare module specifiers -->
  <script type="importmap">
    {
      "imports": {
        "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
      }
    }
  </script>
</head>
<body>
  <div id="app"></div>

  <script type="module">
    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');
  </script>
</body>
</html>

UMD (Global)

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

<!DOCTYPE html>
<html>
<body>
  <div id="app"></div>

  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <script src="https://unpkg.com/vue-sql-workbench-embedded@latest/dist/vue-sql-workbench-embedded.umd.js"></script>

  <script>
    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');
  </script>
</body>
</html>

Note: Template strings (e.g., template: '<div>...</div>') 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

npm install vue-sql-workbench-embedded
# or
yarn add vue-sql-workbench-embedded
# or
pnpm add vue-sql-workbench-embedded

Basic Example

<script setup>
import { SQLWorkbenchEmbedded } from 'vue-sql-workbench-embedded';

const initialCode = `
SELECT * FROM generate_series(1, 10);
`;
</script>

<template>
  <SQLWorkbenchEmbedded
    :initialCode="initialCode"
    theme="dark"
    :editable="true"
  />
</template>

With Provider (Recommended for Multiple Instances)

<script setup>
import {
  SQLWorkbenchProvider,
  SQLWorkbenchEmbedded,
  useSQLWorkbench
} from 'vue-sql-workbench-embedded';

const { isReady, error } = useSQLWorkbench();
</script>

<template>
  <SQLWorkbenchProvider
    :config="{
      theme: 'dark',
      editable: true,
      initQueries: ['INSTALL spatial', 'LOAD spatial']
    }"
  >
    <div v-if="error">Error: {{ error.message }}</div>
    <div v-else-if="!isReady">Loading...</div>
    <div v-else>
      <SQLWorkbenchEmbedded
        initialCode="SELECT * FROM generate_series(1, 10);"
      />
    </div>
  </SQLWorkbenchProvider>
</template>

Using Template Refs

<script setup>
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);
});
</script>

<template>
  <SQLWorkbenchEmbedded
    ref="workbenchRef"
    initialCode="SELECT 1;"
  />
</template>

TypeScript Usage

<script setup lang="ts">
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);
};
</script>

<template>
  <SQLWorkbenchProvider>
    <SQLWorkbenchEmbedded
      ref="workbenchRef"
      :initialCode="'SELECT 1;'"
      :theme="theme"
      @ready="onReady"
      @error="onError"
    />
  </SQLWorkbenchProvider>
</template>

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<string, string> 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<string, CustomTheme> {} 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<boolean> - Whether SQL Workbench is initialized
  • error: Ref<Error \| null> - 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

# 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:

# 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 for more details.

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages