StarQuery is a desktop and web database/resource browser with support for SQL datasources, Elasticsearch, and S3-compatible object storage.

Run the prebuilt single-image deployment:

docker run -it --rm \
  -p 8080:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v starquery-data:/var/lib/starquery \
  interaapps/starquery

Then open:

• App: http://localhost:8080

Networking note:

• If StarQuery inside the container should connect to services running on your host machine, use host.docker.internal as the host in your datasource config instead of localhost.
• The --add-host=host.docker.internal:host-gateway flag makes that work on Linux as well.

Release automation note:

• The GitHub Docker release workflow publishes to ghcr.io and, when DOCKERHUB_USERNAME and DOCKERHUB_TOKEN are configured in GitHub Actions secrets, also to Docker Hub.

Status:

• Work in progress
• No stable releases yet
• Configuration and data formats may still change

Datasource types:

• mysql
• mariadb
• postgres
• cockroachdb
• sqlite (local only)
• duckdb (local only)
• mssql
• clickhouse
• oracle
• cassandra
• mongodb
• redis
• elasticsearch
• s3
• minio

Frontend export formats:

• csv
• json
• sql inserts
• xml
• html table

Runtime targets:

• Electron desktop app with a built-in local backend
• Hosted backend + Vite frontend for browser usage
• Browser frontend against a configured remote StarQuery server

Electron release outputs:

• macOS .zip
• Windows Squirrel installer
• Windows .msix
• Linux .deb
• Linux .rpm

• Starts its own local backend automatically
• Provides the built-in Local computer server
• Local computer is available only inside Electron
• Auth is disabled completely for the built-in local backend
• SQLite datasources are only available here
• You can still add remote StarQuery servers and use those with auth

• Intended for self-hosting on a server
• Auth is enabled by default
• Uses MySQL as the default meta database in the generic backend config
• The published Docker image uses SQLite for the meta database by default so no extra DB is required
• Can optionally bootstrap users, projects, and datasources from JSON

• Connects to remote StarQuery servers
• Does not expose Local computer
• Can auto-register the current origin as a default hosted server in production
• Can be locked to exactly one server via frontend env vars

Run local seeded test databases:

docker compose up -d

This starts:

• MySQL on 127.0.0.1:3307
• Postgres on the configured compose port

Useful commands:

docker compose down
docker compose down -v

Use docker compose down -v if you want to wipe the database and re-run the seed from scratch.

There is a dedicated Docker deployment for the hosted web version with:

• one Node app image that serves both the built frontend and the backend API
• a SQLite metastore by default, stored in a Docker volume

This means the default self-hosted setup does not require any separate database container or database configuration.

Start it with:

docker compose -f docker-compose.hosted.yml up -d --build

Then open:

• App: http://localhost:8080

You can also run the single image directly without compose:

docker build -t starquery -f Dockerfile.backend .
docker run -it --rm \
  -p 8080:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v starquery-data:/var/lib/starquery \
  starquery

Services in the hosted stack:

• app: public StarQuery web UI and backend API on port 8080

Stop it with:

docker compose -f docker-compose.hosted.yml down

Reset the hosted metastore volume with:

docker compose -f docker-compose.hosted.yml down -v

The hosted compose file now uses:

• STARQUERY_META_DRIVER=sqlite
• STARQUERY_META_SQLITE_PATH=/var/lib/starquery/starquery-meta.sqlite
• VITE_LOCKED_SERVER_URL=/
• PORT=8080

If you prefer MySQL for the metastore, you can still switch the backend to MySQL by providing the normal STARQUERY_META_MYSQL_* environment variables in your own compose override.

There are three main configuration surfaces:

• frontend env vars for the browser UI
• backend env vars for the API server and auth
• optional bootstrap JSON for provisioning users, projects, and datasources

These are read by the Vite frontend.

Behavior notes:

• In production web builds, if VITE_DEFAULT_SERVER_URL is not set, the frontend will use the current browser origin as the default hosted server when possible.
• VITE_LOCKED_SERVER_URL takes precedence over all other frontend server defaults.
• The built-in Local computer server is not created in the plain web frontend.

These are read by the StarQuery backend.

Auth mode notes:

• In local mode, auth is disabled completely in the backend.
• In hosted mode, auth is enabled.
• The Electron-built-in Local computer server runs in local mode.

If these are set in hosted mode, the backend will provision an admin-capable user on startup if needed.

Optional hosted-mode OpenID Connect / OAuth2 login.

These are only relevant for Windows Electron builds. The Electron Forge setup now emits an additional .msix artifact beside the existing Windows installer artifacts.

The Electron Forge setup can now sign and notarize the regular macOS ZIP distribution without enabling any Mac App Store packaging path.

Build-time environment variables:

GitHub Actions secrets for the macOS release job:

STARQUERY_MODE=hosted
HOST=0.0.0.0
PORT=3000
STARQUERY_SERVER_NAME="StarQuery Hosted"

STARQUERY_META_DRIVER=mysql
STARQUERY_META_MYSQL_HOST=127.0.0.1
STARQUERY_META_MYSQL_PORT=3306
STARQUERY_META_MYSQL_USER=starquery
STARQUERY_META_MYSQL_PASSWORD=secret
STARQUERY_META_MYSQL_DATABASE=starquery

STARQUERY_MODE=local
HOST=127.0.0.1
PORT=3000

STARQUERY_META_DRIVER=sqlite
STARQUERY_META_SQLITE_PATH=/absolute/path/to/starquery-meta.sqlite

The bootstrap file is loaded from STARQUERY_BOOTSTRAP_CONFIG_PATH.

Supported top-level keys:

• users
• projects

Example:

{
  "users": [
    {
      "email": "admin@example.com",
      "name": "Admin",
      "password": "change-me",
      "permissions": ["*"],
      "roles": ["admin"]
    }
  ],
  "projects": [
    {
      "slug": "analytics",
      "name": "Analytics",
      "description": "Shared analytics resources",
      "dataSources": [
        {
          "name": "Primary MySQL",
          "type": "mysql",
          "position": 0,
          "config": {
            "host": "127.0.0.1",
            "port": 3306,
            "user": "app",
            "password": "secret",
            "database": "analytics"
          }
        }
      ]
    }
  ]
}

Bootstrap behavior:

• Users are matched by email and updated if they already exist.
• Projects are matched by slug and updated if they already exist.
• Datasources are matched by name within a project and updated if they already exist.
• Datasource configs are normalized through the datasource registry before being saved.
• Local-only datasource types such as sqlite cannot be bootstrapped on hosted servers.

Capabilities:

• SQL query editor
• table browser
• schema editor

Config fields:

• host
• port
• user
• password
• database

Capabilities:

• SQL query editor
• table browser
• schema editor

Config fields:

• host
• port
• user
• password
• database

Capabilities:

• SQL query editor
• table browser
• schema editor

Restrictions:

• local only

Config fields:

• filePath

Capabilities:

• resource browser
• document search/edit workflow

Config fields:

• node
• username
• password
• apiKey
• index

Auth notes:

• you can use either apiKey
• or username plus password
• or no auth if the cluster allows it

Capabilities:

• bucket/object browser
• preview
• upload
• download
• delete

Config fields:

• endPoint
• port
• useSSL
• pathStyle
• accessKey
• secretKey
• sessionToken
• region
• bucket

Capabilities:

• bucket/object browser
• preview
• upload
• download
• delete

Config fields:

• endPoint
• port
• useSSL
• pathStyle
• accessKey
• secretKey
• sessionToken
• region
• bucket

Defaults compared to s3:

• useSSL=false
• pathStyle=true
• port=9000

Hosted mode includes:

• local email/password auth
• optional OpenID Connect auth
• sessions
• API keys
• roles and wildcard-based permissions

Electron local backend behavior:

• no login required
• auth disabled completely
• wildcard access is effectively available for the built-in local server

Permissions support:

• plain path permissions such as project.analytics
• explicit read permissions such as project.analytics:read
• explicit write permissions such as project.analytics:write
• wildcard patterns such as project.*

Examples:

• datasource.analytics.primary
• datasource.analytics.primary:read
• datasource.analytics.primary:write
• project.analytics.users:write
• *

• If you self-host the browser build, the frontend and backend can live behind the same origin and the frontend will talk to /api.
• If you want a browser build that can only talk to one server, use VITE_LOCKED_SERVER_URL.
• If you use Electron, the built-in local backend is managed by the app and should not require a manual URL.
• Password-like datasource fields are redacted when datasources are read back from the API.

Potential next improvements:

• replace the current custom meta migration runner with generated Drizzle migrations
• add a root .env.example
• add production HTTPS reverse-proxy examples
• move Electron password storage to keytar