Quickstart

You need about a minute. Pick one way to get the server, start it with an administrator password, then run a query.

1. Get the server

Installer

macOS on Apple silicon and Linux (x86-64 or arm64, glibc 2.28 or newer: RHEL, Rocky and Alma Linux 8, Debian 10, Ubuntu 20.04, Amazon Linux 2023):

$ curl https://install.hardcharger.gizmodata.com | sh
…
$ ~/.hardcharger/bin/hardcharger-server --version
Hardcharger …

The installer puts every version under ~/.hardcharger/versions/ and links the current one into ~/.hardcharger/bin; add that directory to your PATH. It checks each download against the release’s SHA-256 before switching. HARDCHARGER_VERSION=0.3.0 installs a given version, and sh -s -- --list lists what you have.

Start the server:

HARDCHARGER_ADMIN_PASSWORD='change-me' ~/.hardcharger/bin/hardcharger-server --database my.duckdb

Docker

Images are multi-architecture (linux/amd64, linux/arm64):

docker run --rm --name hardcharger -p 31337:31337 -p 31338:31338 \
  -e HARDCHARGER_ADMIN_PASSWORD='change-me' \
  ghcr.io/gizmodata/hardcharger:latest

Port 31337 speaks Warp SQL; 31338 answers /health.

Binaries

Linux (x86-64, arm64) and macOS (Apple silicon) tarballs, and Windows zips and MSIs, are attached to every release. Download the one for your platform, then unpack it:

case "$(uname -sm)" in
  "Linux x86_64")  PLATFORM=linux-amd64 ;;
  "Linux aarch64") PLATFORM=linux-arm64 ;;
  "Darwin arm64")  PLATFORM=macos-arm64 ;;
esac
tar -xzf "hardcharger-$PLATFORM.tar.gz"
mv "hardcharger-$PLATFORM" hardcharger

HARDCHARGER_ADMIN_PASSWORD='change-me' ./hardcharger/bin/hardcharger-server --database my.duckdb

On Windows (x64 and arm64), unzip hardcharger-windows-amd64.zip or -arm64.zip in PowerShell, or run Hardcharger-windows-amd64.msi / -arm64.msi, which installs under Program Files and puts hardcharger-server.exe and the hardcharger.exe client on the PATH. The executables are single files that need no Visual C++ Redistributable. Ctrl+C or Ctrl+Break stops the server as SIGINT or SIGTERM does elsewhere.

Expand-Archive hardcharger-windows-amd64.zip -DestinationPath .
$env:HARDCHARGER_ADMIN_PASSWORD = 'change-me'
.\hardcharger-windows-amd64\bin\hardcharger-server.exe --database my.duckdb

Python

The hardcharger Python package runs the server for you. It downloads the release for your platform on first use, checks its SHA-256, caches it and starts it on a free port:

import hardcharger

with hardcharger.Server(password="change-me") as server:
    print(server.uri)

hardcharger://127.0.0.1:…?tls=false

pip install hardcharger

See Python (ADBC) for server.connect().

Tip

Pass the password in the HARDCHARGER_ADMIN_PASSWORD environment variable, not as a flag: flags show up in process listings. The administrator’s user name is hardcharger unless you set --admin-username.

2. Check that it is up

$ curl -s localhost:31337/warp/v1/health
{"status":"serving"}

The health endpoint needs no credentials. For load balancers and Kubernetes probes, also serve it on its own plaintext port with --health-port 31338 (the Docker image does). Port 31337 describes itself at /warp:

$ curl -s localhost:31337/warp | jq -r '.server.name, .protocol'
Hardcharger
warp-sql

3. Run a query

Warp SQL is plain HTTP, so curl is enough. Get a token, open a session, run SQL:

TOKEN=$(curl -s localhost:31337/warp/v1/auth/token -H 'Content-Type: application/json' \
  -d '{"grant_type": "password", "username": "hardcharger", "password": "change-me"}' | jq -r .access_token)
SESSION=$(curl -s localhost:31337/warp/v1/sessions -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{}' | jq -r .session_id)
curl -s localhost:31337/warp/v1/sessions/$SESSION/statements -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"sql": "SELECT 42 AS answer"}' | jq .result.kind

"rows"

That answer is a statement document. Ask for Accept: application/vnd.apache.arrow.stream and the rows themselves arrive as an Arrow IPC stream in the same response; the plain HTTP client page shows both.

Next steps

• Your first query in Python, Go, Java, JavaScript or the CLI.
• Configure the server with flags, environment variables or YAML.
• Turn on TLS before anyone else connects: ?tls=false and plain HTTP are for your own machine.