Getting Started with Duck-UI

Duck-UI is a web-based interface for interacting with DuckDB, providing a powerful and intuitive way to work with data directly in your browser. This guide will help you get Duck-UI up and running quickly.

Installation Options

Choose your preferred installation method:

Docker (Recommended)

The easiest way to get started with Duck-UI is using Docker. You can use either the simple docker run command or Docker Compose.

Using docker run

Run this command:

docker run -p 5522:5522 ghcr.io/caioricciuti/duck-ui:latest

Then open your browser and navigate to http://localhost:5522.

Using Docker Compose

1. Create a docker-compose.yml file with the following content:

version: '3.8'
services:
  duck-ui:
    image: ghcr.io/caioricciuti/duck-ui:latest
    restart: always
    ports:
      - "${DUCK_UI_PORT:-5522}:5522"
    environment:
      # External connection (optional)
      - DUCK_UI_EXTERNAL_CONNECTION_NAME=${DUCK_UI_EXTERNAL_CONNECTION_NAME:-}
      - DUCK_UI_EXTERNAL_HOST=${DUCK_UI_EXTERNAL_HOST:-}
      - DUCK_UI_EXTERNAL_PORT=${DUCK_UI_EXTERNAL_PORT:-}
      - DUCK_UI_EXTERNAL_USER=${DUCK_UI_EXTERNAL_USER:-}
      - DUCK_UI_EXTERNAL_PASS=${DUCK_UI_EXTERNAL_PASS:-}
      - DUCK_UI_EXTERNAL_DATABASE_NAME=${DUCK_UI_EXTERNAL_DATABASE_NAME:-}
      # DuckDB configuration
      - DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS=${DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS:-false}

2. Run docker compose:

docker-compose up -d

You can then access Duck-UI in your browser at http://localhost:5522 (or the port you have set using DUCK_UI_PORT environment variable).

From Source

If you prefer to run from source, follow these steps:

Prerequisites

• Node.js >= 20.x
• npm >= 10.x

Steps

1. Clone the repository:

git clone https://github.com/caioricciuti/duck-ui.git
cd duck-ui

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The application will be available at http://localhost:5173.

Environment Variables

Duck-UI can be customized through environment variables when running with Docker:

Variable	Description	Default
DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS	Allow unsigned DuckDB extensions to be loaded (useful for custom or development extensions)	false
DUCK_UI_EXTERNAL_CONNECTION_NAME	Display name for external DuckDB connection	""
DUCK_UI_EXTERNAL_HOST	Host URL for external DuckDB server	""
DUCK_UI_EXTERNAL_PORT	Port for external DuckDB server	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	""

Example with Environment Variables

docker run -p 5522:5522 \
  -e DUCK_UI_ALLOW_UNSIGNED_EXTENSIONS=true \
  -e DUCK_UI_EXTERNAL_CONNECTION_NAME="My DuckDB Server" \
  -e DUCK_UI_EXTERNAL_HOST="https://duckdb-server.example.com" \
  -e DUCK_UI_EXTERNAL_PORT=8000 \
  -e DUCK_UI_EXTERNAL_USER="duckuser" \
  -e DUCK_UI_EXTERNAL_PASS="duckpass" \
  ghcr.io/caioricciuti/duck-ui:latest

Core Features

SQL Editor

• Write and execute SQL queries with syntax highlighting
• Auto-completion support
• Execute queries using Cmd/Ctrl + Enter
• View results in a formatted table

Data Import

Duck-UI supports importing data from various file formats:

Supported File Formats

• CSV files (.csv)
• JSON files (.json)
• Parquet files (.parquet)
• Apache Arrow files (.arrow)
• Excel files (.xlsx)
• DuckDB database files (.duckdb)

Import Features

• Drag-and-drop interface
• Multiple file import
• Custom table naming
• Automatic schema detection
• Format-specific options
• Import progress tracking

Enhanced CSV Import Options

When importing CSV files, Duck-UI provides advanced configuration options:

Option	Description	Default
Header Row	Treat the first row as column headers	True
Auto-detect Types	Automatically detect column data types	True
Ignore Errors	Skip rows with parsing errors	True
Pad Missing Columns	Fill missing columns with NULL values	True
Delimiter	Character used to separate columns	Comma (,)

To import data:

1. Click the "Import Files" button in the sidebar
2. Drag & drop files or use the file picker
3. Configure import options for each file
4. Click "Import" to load your data

tip

For large CSV files with complex schemas, consider using a combination of "Auto-detect Types" and "Ignore Errors" to ensure the best import results.

info

File must have a maximum of 2gb!

Data Explorer

• Browse databases and tables
• View table schemas
• Preview table contents
• Manage table operations

Keyboard Shortcuts

Action	Shortcut
Expand/Shrink Sidebar	Cmd/Ctrl + B
Open Search Bar	Cmd/Ctrl + K
Run Query	Cmd/Ctrl + Enter
Run Highlighted Query	Cmd/Ctrl + Shift + Enter

Quick Start Example

Here's a quick example to get you started:

1. Launch Duck-UI and navigate to the SQL Editor

2. Create a sample table:

   CREATE TABLE users (
     id INTEGER,
     name VARCHAR,
     email VARCHAR
   );
   
   INSERT INTO users VALUES
     (1, 'John Doe', '[email protected]'),
     (2, 'Jane Smith', '[email protected]');

3. Query the data:

   SELECT * FROM users;

Troubleshooting

If you encounter any issues:

1. Check if you're using the latest version
2. Verify that your browser supports WebAssembly
3. Clear your browser cache and reload
4. Check our GitHub Issues page

Need Help?

• Join our GitHub Discussions
• Report bugs on GitHub Issues
• Follow updates on our GitHub Repository

---