Integrations

Connect Superset with external tools and services for a seamless workflow

Superset integrates with popular development tools to fit into your existing workflow. Open workspaces in your favorite editor, manage Git repositories, and connect to external services.

IDE Integration

Quickly open workspaces in external editors and IDEs.

Supported Editors

Superset automatically detects these editors on your system:

• Visual Studio Code (code)
• Cursor (cursor)
• Sublime Text (subl)
• IntelliJ IDEA (idea)
• WebStorm (webstorm)
• PyCharm (pycharm)
• Vim/Neovim (vim, nvim)
• Emacs (emacs)

Opening in External Editor

1. Configure Default Editor

   Go to Settings > Editor Preferences and select your preferred editor. Or set the EDITOR environment variable:

   export EDITOR="code"
   
2. Open Workspace

   Press ⌘O to open the current workspace in your configured editor.

The workspace will open in a new editor window while keeping Superset running for terminal access and change monitoring.

Command Line

You can also open editors directly from the terminal:

# VS Code
code .

# Cursor
cursor .

# Sublime Text
subl .

# Vim
vim .

Git Integration

Superset is built around Git worktrees and provides seamless Git integration.

Built-in Git Features

• Changes Panel (⌘L): View diffs, stage changes, and commit
• Branch Isolation: Each workspace is a separate git worktree with its own branch
• Status Indicators: See workspace status at a glance

Git Commands

All standard Git commands work in Superset terminals:

# View status
git status

# Create branch
git checkout -b feature/new-feature

# Commit changes
git add .
git commit -m "Implement feature"

# Push to remote
git push origin feature/new-feature

# View log
git log --oneline

# Merge branches
git merge main

Git Worktree Management

Superset manages worktrees automatically, but you can use Git worktree commands directly:

# List worktrees
git worktree list

# Add worktree manually
git worktree add ../my-workspace feature/my-branch

# Remove worktree
git worktree remove ../my-workspace

Deleting workspaces through Superset (⌘⇧Delete) properly cleans up worktrees and runs teardown scripts. Avoid manually deleting worktree directories.

GitHub CLI Integration

Use the GitHub CLI (gh) for managing issues, pull requests, and releases.

Installation

# macOS
brew install gh

# Authenticate
gh auth login

Common Commands

Pull Requests

# Create PR
gh pr create --title "Add feature" --body "Description"

# List PRs
gh pr list

# View PR
gh pr view 123

# Checkout PR
gh pr checkout 123

# Merge PR
gh pr merge 123 --squash

# Create issue
gh issue create --title "Bug report" --body "Description"

# List issues
gh issue list

# View issue
gh issue view 456

# Close issue
gh issue close 456

# Clone repo
gh repo clone owner/repo

# View repo
gh repo view

# Create repo
gh repo create my-new-repo --public

# Fork repo
gh repo fork owner/repo

GitHub Actions

Monitor CI/CD workflows:

# View workflow runs
gh run list

# Watch latest run
gh run watch

# View run logs
gh run view 789 --log

Caddy Integration

Superset uses Caddy as an HTTP/2 reverse proxy for Electric SQL streams.

Why Caddy?

Browsers limit concurrent HTTP/1.1 connections to 6 per domain. When running multiple Electric SQL shape streams, this becomes a bottleneck. Caddy provides HTTP/2 multiplexing to bypass this limit.

Installation

# macOS
brew install caddy

# Trust Caddy's certificate for HTTPS
sudo caddy trust

Configuration

Superset automatically generates a Caddyfile during workspace setup:

Caddyfile

https://localhost:{$CADDY_ELECTRIC_PORT} {
  reverse_proxy localhost:{$API_PORT} {
    flush_interval -1
  }
}

Starting Caddy

# Start Caddy (usually in setup script)
caddy start --config Caddyfile

# Stop Caddy (usually in teardown script)
caddy stop

Caddy runs on port SUPERSET_PORT_BASE + 10 by default (e.g., 3010 for base port 3000).

Docker Integration

Run Docker containers alongside your workspaces for databases, caches, and services.

Starting Containers in Setup Scripts

.superset/setup.sh

#!/bin/bash

# Start PostgreSQL
docker run -d \
  --name "${SUPERSET_WORKSPACE_NAME}-db" \
  -e POSTGRES_PASSWORD=dev \
  -p 5432:5432 \
  postgres:16

# Start Redis
docker run -d \
  --name "${SUPERSET_WORKSPACE_NAME}-redis" \
  -p 6379:6379 \
  redis:7-alpine

# Start Electric SQL
docker run -d \
  --name "${SUPERSET_WORKSPACE_NAME}-electric" \
  -p 3000:3000 \
  -e DATABASE_URL="$DATABASE_URL" \
  electricsql/electric:latest

Stopping Containers in Teardown Scripts

.superset/teardown.sh

#!/bin/bash

# Stop and remove all workspace containers
docker stop "${SUPERSET_WORKSPACE_NAME}-db" 2>/dev/null || true
docker rm "${SUPERSET_WORKSPACE_NAME}-db" 2>/dev/null || true

docker stop "${SUPERSET_WORKSPACE_NAME}-redis" 2>/dev/null || true
docker rm "${SUPERSET_WORKSPACE_NAME}-redis" 2>/dev/null || true

docker stop "${SUPERSET_WORKSPACE_NAME}-electric" 2>/dev/null || true
docker rm "${SUPERSET_WORKSPACE_NAME}-electric" 2>/dev/null || true

Managing Containers from Terminal

# List running containers
docker ps

# View logs
docker logs ${SUPERSET_WORKSPACE_NAME}-db

# Follow logs
docker logs -f ${SUPERSET_WORKSPACE_NAME}-db

# Execute commands in container
docker exec -it ${SUPERSET_WORKSPACE_NAME}-db psql -U postgres

# Restart container
docker restart ${SUPERSET_WORKSPACE_NAME}-db

Database Service Integration

Connect to managed database services like Neon, PlanetScale, and Supabase.

Neon

Superset’s setup scripts can automatically create database branches using Neon:

# Create branch
BRANCH_ID=$(neonctl branches create \
  --project-id "$NEON_PROJECT_ID" \
  --name "$SUPERSET_WORKSPACE_NAME" \
  --output json | jq -r '.branch.id')

# Get connection string
DATABASE_URL=$(neonctl connection-string "$BRANCH_ID" \
  --project-id "$NEON_PROJECT_ID" \
  --pooled)

echo "DATABASE_URL=$DATABASE_URL" >> .env

See the Setup/Teardown Scripts guide for more examples.

PlanetScale

Create branches for MySQL databases:

# Create branch
pscale branch create my-database "$SUPERSET_WORKSPACE_NAME"

# Get connection string
DATABASE_URL=$(pscale connect my-database "$SUPERSET_WORKSPACE_NAME" --format json | jq -r .url)

Supabase

Use Supabase CLI for local development:

# Initialize Supabase
supabase init

# Start local Supabase
supabase start

# Get connection string
supabase status | grep "DB URL"

External Tool Launching

Launch external tools from Superset terminals.

Browser

Open URLs in your default browser:

# macOS
open http://localhost:3000

# Linux
xdg-open http://localhost:3000

# Windows
start http://localhost:3000

Database Clients

# Postico (PostgreSQL GUI for macOS)
open -a Postico "postgres://localhost:5432/mydb"

# TablePlus
open -a TablePlus "postgres://localhost:5432/mydb"

# psql (command line)
psql "$DATABASE_URL"

API Clients

# Postman
open -a Postman

# Insomnia
open -a Insomnia

# HTTPie (CLI)
http GET localhost:3000/api/users

Custom Integrations

Build your own integrations using Superset’s MCP server.

Available Tools

The Superset MCP server provides tools for:

• Creating workspaces
• Switching workspaces
• Listing workspaces
• Updating workspace metadata
• Deleting workspaces
• Managing tasks

See the MCP Servers guide for details.

Example: Custom CLI Tool

superset-cli.sh

#!/bin/bash
# Custom CLI tool that uses Superset MCP

SUPERSET_API="http://localhost:3001/api/agent/mcp"

case "$1" in
  create)
    curl -X POST "$SUPERSET_API/workspaces" \
      -H "Content-Type: application/json" \
      -d '{"name": "'"$2"'", "projectId": "'"$3"'"}'
    ;;
  list)
    curl -X GET "$SUPERSET_API/workspaces"
    ;;
  *)
    echo "Usage: $0 {create|list} [args]"
    exit 1
    ;;
esac

Environment Variables

Integrations often require environment variables. Manage them in your .env file:

.env

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Neon
NEON_PROJECT_ID=xxx-xxx-xxx
NEON_API_KEY=xxxxxxxx

# Docker
DOCKER_HOST=unix:///var/run/docker.sock

# Editor
EDITOR=code

Never commit .env files to Git. Add .env to your .gitignore.

Troubleshooting

Editor command not found

If ⌘O fails to open your editor:

1. Make sure the editor is installed
2. Check that the command is in your PATH: which code
3. Set the EDITOR environment variable manually
4. Try running the command in terminal first

GitHub CLI not authenticated

If gh commands fail:

1. Run gh auth login
2. Follow the authentication flow
3. Verify: gh auth status

Docker containers won't start

If Docker commands fail:

1. Make sure Docker Desktop is running
2. Check Docker status: docker ps
3. Verify port availability: lsof -i :5432
4. Check logs: docker logs <container-name>

Caddy certificate errors

If HTTPS connections fail:

1. Trust Caddy’s certificate: sudo caddy trust
2. Restart Caddy
3. Check Caddy status: caddy status

Related Topics

Setup Scripts

Automate integrations with setup scripts

MCP Servers

Build integrations using MCP

Workspace Management

Learn how workspaces work