Duck-UI
Duck-UI is a web-based interface for interacting with DuckDB, a high-performance analytical database system. This project leverages DuckDB's WebAssembly (WASM) capabilities to provide a seamless and efficient user experience directly in the browser.
# [Official Docs](https://duckui.com?utm_source=github&utm_medium=readme) 🚀
# [Demo](https://demo.duckui.com?utm_source=github&utm_medium=readme) 💻
## Features
- **SQL Editor**: Write and execute SQL queries with syntax highlighting and auto-completion.
- **Data Import**: Import data from CSV, JSON, Parquet, and Arrow files.
- **Data Explorer**: Browse and manage databases and tables.
- **Query History**: View and manage your recent SQL queries.
## Getting Started
### Docker (Recommended)
```bash
docker run -p 5522:5522 ghcr.io/caioricciuti/duck-ui:latest
```
Open your browser and navigate to `http://localhost:5522`.
### Environment Variables
You can customize Duck-UI behavior using environment variables:
```bash
# For external DuckDB connections
docker run -p 5522:5522 \
-e DUCK_UI_EXTERNAL_CONNECTION_NAME="My DuckDB Server" \
-e DUCK_UI_EXTERNAL_HOST="http://duckdb-server" \
-e DUCK_UI_EXTERNAL_PORT="8000" \
-e DUCK_UI_EXTERNAL_USER="username" \
-e DUCK_UI_EXTERNAL_PASS="password" \
-e DUCK_UI_EXTERNAL_DATABASE_NAME="my_database" \
-e DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS="true" \
ghcr.io/caioricciuti/duck-ui:latest
```
| Runtime Variable | Description | Default |
|----------|-------------|---------|
| `DUCK_UI_EXTERNAL_CONNECTION_NAME` | Name for the external connection | "" |
| `DUCK_UI_EXTERNAL_HOST` | Host URL for external DuckDB | "" |
| `DUCK_UI_EXTERNAL_PORT` | Port for external DuckDB | null |
| `DUCK_UI_EXTERNAL_USER` | Username for external connection | "" |
| `DUCK_UI_EXTERNAL_PASS` | Password for external connection | "" |
| `DUCK_UI_EXTERNAL_DATABASE_NAME` | Database name for external connection | "" |
| `DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS` | Allow unsigned extensions in DuckDB | false |
| `DUCK_UI_DUCKDB_WASM_USE_CDN` | Load DuckDB WASM from CDN (ignored when build-time `DUCK_UI_DUCKDB_WASM_CDN_ONLY=true`) | false |
| `DUCK_UI_DUCKDB_WASM_BASE_URL` | Custom CDN base URL (used when `DUCK_UI_DUCKDB_WASM_USE_CDN=true`) | auto jsDelivr |
| Build-time Variable | Description | Default |
|----------|-------------|---------|
| `DUCK_UI_DUCKDB_WASM_CDN_ONLY` | Build a CDN-only artifact (local DuckDB WASM assets are not bundled). | false |
When `DUCK_UI_DUCKDB_WASM_CDN_ONLY=true`, runtime `DUCK_UI_DUCKDB_WASM_USE_CDN=false` cannot switch back to local WASM.
### Prerequisites
- Node.js >= 20.x
- npm >= 10.x
### Installation
1. Clone the repository:
```bash
git clone https://github.com/caioricciuti/duck-ui.git
cd duck-ui
```
2. Install dependencies:
```bash
npm install
# or
yarn install
```
### Running the Application
1. Start the development server:
```bash
npm run dev
# or
yarn dev
```
2. Open your browser and navigate to `http://localhost:5173`.
### Building for Production
To create a production build, run:
```bash
npm run build
# or
yarn build
```
The output will be in the `dist` directory.
### Running with Docker
1. Build the Docker image:
```bash
docker build -t duck-ui .
```
2. Run the Docker container:
```bash
docker run -p 5522:5522 duck-ui
```
3. Open your browser and navigate to `http://localhost:5522`.
## Usage
### SQL Editor
- Write your SQL queries in the editor.
- Use `Cmd/Ctrl + Enter` to execute the query.
- View the results in the results pane.
### Data Import
- Click on the "Import Files" button to upload CSV, JSON, Parquet, or Arrow files.
- Configure the table name and import settings.
- For CSV files, you can customize import options:
- Header row detection
- Auto-detection of column types
- Delimiter specification
- Error handling (ignore errors, null padding for missing columns)
- View the imported data in the Data Explorer.
### Data Explorer
- Browse through the databases and tables.
- Preview table data and view table schemas.
- Delete tables if needed.
### Query History
- Access your recent queries from the Query History section.
- Copy queries to the clipboard or re-execute them.
### Theme Toggle
- Switch between light and dark themes using the theme toggle button.
### Keyboard Shortcuts
- `Cmd/Ctrl + B`: Expand/Shrink Sidebar
- `Cmd/Ctrl + K`: Open Search Bar
- `Cmd/Ctrl + Enter`: Run Query
- `Cmd/Ctrl + Shift + Enter`: Run highlighted query
## Contributing
Contributions are welcome! Please follow these steps to contribute:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature`).
3. Commit your changes (`git commit -m 'Add some feature'`).
4. Push to the branch (`git push origin feature/your-feature`).
5. Open a pull request.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.
## Acknowledgements
- [DuckDB](https://duckdb.org/)
- [React](https://reactjs.org/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Zustand](https://github.com/pmndrs/zustand)
- [Lucide Icons](https://lucide.dev/)
## Contact
For any inquiries or support, please contact [Caio Ricciuti](https://github.com/caioricciuti).
## Sponsors
This project is sponsored by:
### [Ibero Data](https://iberodata.es/)
### [qxip](https://qxip.net/?utm_source=duck-ui&utm_medium=sponsorship)
{connection.lastError}
Cloud storage has limited support in browsers. Consider using HTTPS URLs instead.
No cloud connections
{fileName}
{importMode === "table" ? "Copies data into DuckDB (faster queries)" : "Links to file (fresh data, less memory)"}
{sql}
{/* Actions */}
Hi! I'm Duck Brain
Ask me to write SQL queries for your data
{renderMentions(message.content)}
) : ({streamingContent}
WebGPU Not Supported
Duck Brain requires WebGPU for local AI processing. Please use Chrome 113+ or Edge 113+.
Download an AI model to enable natural language to SQL conversion. This runs 100% locally in your browser.
Model: {DEFAULT_MODEL.displayName}
Size: {DEFAULT_MODEL.size}
First load downloads the model. Future loads use cache.
{downloadStatus || `${downloadProgress}%`}
{error || "An unknown error occurred"}
{children}
);
}
// Inline code
return (
{children}
);
},
// Paragraph styling
p: ({ children }) => {children}
, // Strong/bold strong: ({ children }) => {children}, // Emphasis/italic em: ({ children }) => {children}, // Unordered list ul: ({ children }) =>{children}), // Headings (rarely used in chat but good to have) h1: ({ children }) =>
Query failed
{error || "Unknown error occurred"}
|
{col}
{columnTypes[i]}
|
))}
{hasMoreColumns && (
+{columns.length - MAX_INLINE_COLUMNS} more | )}
|---|---|
| {formatCellValue(row[col])} | ))} {hasMoreColumns &&... | }
Copy shareable URL
Save Query
{duckBrain.isPanelOpen ? "Close Duck Brain" : "Open Duck Brain"}
Explain Plan
Drop files to import
Loading databases...
Connection error
{schemaFetchError}
) : ( <>No schema found from the remote server.
Try refreshing or run queries directly in the editor.
)} ) : ( <>No databases found. Start by importing some data!
)}{tableNameError}
}This name will be used to reference the table in SQL queries
Common values: , (comma), ; (semicolon), tab, pipe (|)
Values matching this string will be treated as NULL
Table Name: {previewTableName}
Showing first {PREVIEW_ROW_LIMIT} rows • {previewData.rowCount} total rows
Customize column names, types, and visibility before importing
| Include | Original Name | New Name | Type |
|---|---|---|---|
|
|
{col.originalName}
|
handleRenameColumn(col.originalName, e.target.value) } disabled={!col.included} className="h-8 text-xs" placeholder="Column name" /> |
{schemaColumns.filter((col) => col.included).length} of{" "} {schemaColumns.length} columns will be imported
{error.message}
{suggestion && (Suggestion: {suggestion}
)}Drop the files here ...
) : ( <>Drag & drop files here, or
Supported formats: CSV, JSON, Parquet, Arrow and DuckDB
Maximum file size: {formatFileSize(MAX_FILE_SIZE)}
Views reference the original file without copying data. Queries re-read the file each time, using less memory but may be slower.
)}{error.file ? `${error.file}: ${error.message}` : error.message}
{suggestion && (Suggestion: {suggestion}
)}DuckDB can directly read files from HTTP/HTTPS URLs. Supports CSV, JSON, and Parquet files.
Enter a direct URL to a CSV, JSON, or Parquet file
{importMode === "view" ? "View references URL directly (fresh data, less memory)" : "Table copies data into DuckDB (faster queries)"}
{error.message}
{suggestion && (Suggestion: {suggestion}
)}Execute a SQL query and create a table from the result. Use DuckDB functions like read_csv, read_json, read_parquet, or query existing tables.