gizmodata/hardcharger repository overview

⁠Fast, secure, remote DuckDB. Every feature included.

⁠🏎️ What is Hardcharger?

Hardcharger puts DuckDB 2.0⁠ on the network. Clients connect over Warp SQL⁠, an open HTTP protocol that moves Apache Arrow record batches straight from DuckDB to your application: no gRPC, no Flight, no sidecars. It is the successor to GizmoSQL, rebuilt from scratch for DuckDB 2.0, and it is free and open source (Apache 2.0): no editions, no license keys.

• 🦆 DuckDB 2.0 inside, with DuckLake and DuckDB's built-in extensions.
• ⚡ Warp SQL on the wire: a query and its first rows in one HTTP round trip; large results stream as Arrow IPC, LZ4 or zstd compressed when asked, split into partitions a client reads in parallel, and resumable. Bulk ingest streams Arrow straight into a table.
• 🖥️ Web UI built into the binary (--web-ui): SQL editor, results grid, schema browser, uploads, sessions and an API page.
• 🔐 Security in the core: TLS and mTLS, password and token sign-in, SSO (OIDC/JWKS), role-based access control checked against each statement's plan, row policies, column masking, tenants, a tamper-evident audit log.
• 🔭 Observable: instrumentation tables, catalog logging, a Prometheus /metrics endpoint, query profiles, KILL SESSION.
• 🧩 Configured your way: flags, HARDCHARGER_* environment variables, or a YAML file.

📚 Documentation: https://docs.hardcharger.gizmodata.com⁠ 🧑‍💻 Source and issues: https://github.com/gizmodata/hardcharger⁠

⁠⚡ Quick start

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

Port 31337 speaks Warp SQL (plain HTTP until you give it a certificate); 31338 answers GET /health for load balancers and orchestrators. The administrator is hardcharger with the password you set.

Keep the database on a volume and turn on the web UI:

docker run -d --name hardcharger -p 31337:31337 -p 31338:31338 \
  -v hardcharger-data:/data \
  -e HARDCHARGER_ADMIN_PASSWORD='change-me' \
  gizmodata/hardcharger:latest --database /data/analytics.duckdb --web-ui

Then open http://localhost:31337/ui/⁠ and sign in as hardcharger / change-me.

Extensions you INSTALL and persistent secrets live under the container user's home, /var/lib/hardcharger/.duckdb/, as DuckDB keeps them. To keep them across container replacements, mount a second volume there (-v hardcharger-home:/var/lib/hardcharger), or point them at the data volume from the init SQL:

SET extension_directory = '/data/extensions';
SET secret_directory = '/data/secrets';

⁠🔌 Connect

Command-line client, included in the image (it uses TLS by default; --no-tls for a server without a certificate):

docker exec -it -e HARDCHARGER_PASSWORD='change-me' hardcharger \
  hardcharger --host 127.0.0.1 --no-tls --username hardcharger

One statement, as CSV:

docker exec -e HARDCHARGER_PASSWORD='change-me' hardcharger \
  hardcharger --host 127.0.0.1 --no-tls --username hardcharger --csv \
  --command "SELECT 42 AS answer, version() AS duckdb"

Python (pip install adbc-driver-hardcharger):

from adbc_driver_hardcharger import dbapi as hardcharger

with hardcharger.connect(uri="hardcharger://localhost?tls=false", username="hardcharger", password="change-me") as conn:
    with conn.cursor() as cur:
        cur.execute(operation="SELECT 42 AS answer, ? AS greeting", parameters=["hello"])
        print(cur.fetch_arrow_table())

hardcharger://host is HTTPS on port 31337; ?tls=false is plain HTTP for local use.

Java: hardcharger-jdbc⁠, one jar for Java 17+, jdbc:hardcharger://host[:port]. JavaScript: @gizmodata/hardcharger⁠ for Node, browsers, Deno, Bun and Cloudflare Workers. Anything else: Warp SQL is plain HTTP, so curl works, and the server describes its API in OpenAPI 3.1 at GET /warp/v1/openapi.json.

⁠⚙️ Configuration

Every option is a flag (--read-only), an environment variable (HARDCHARGER_READ_ONLY) or a key in a YAML file passed with --config (read_only: true). Flags win over the environment, which wins over the file. docker run --rm gizmodata/hardcharger --help lists them all. The ones most deployments set:

A YAML file, mounted and passed with --config /etc/hardcharger/hardcharger.yaml:

database: /data/analytics.duckdb
port: 31337
health_port: 31338
web_ui: true
log_level: info
print_queries: true
init_sql_commands_file: /etc/hardcharger/init.sql

Access control (users, roles, grants, row policies, masking), SSO, client certificates, instrumentation and the audit log are covered in the documentation⁠ and the README⁠.

⁠🐳 The image

• Tags: latest and X.Y.Z are releases; main and sha-<commit> are development builds of the newest commit on main that passed every CI gate, built exactly as a release. Use latest or a version for anything that matters.
• Architectures: linux/amd64 and linux/arm64, one multi-architecture tag.
• Contents: hardcharger-server and the hardcharger command-line client under /opt/hardcharger/bin, on PATH. Both are the release tarballs' binaries, built for glibc 2.28 with every dependency (DuckDB and its extensions, OpenSSL, Arrow, the web UI) linked in statically, on ubuntu:24.04 with only CA certificates and time zones added.
• User: runs as the non-root user hardcharger (home and working directory /var/lib/hardcharger). A volume mounted for the database must be writable by it, or run the container with --user and a HOME it can write.
• Entrypoint: hardcharger-server; arguments to docker run are its flags. Listens on 0.0.0.0:31337, health on 31338.
• Licenses: LICENSE and the third-party notices are in /opt/hardcharger and /usr/share/doc/hardcharger; hardcharger-server --licenses prints them.
• The same image is published to GitHub Container Registry as ghcr.io/gizmodata/hardcharger.

An -adbc variant (X.Y.Z-adbc, latest-adbc) adds 15 native ADBC drivers (BigQuery, Databricks, Exasol, Flight SQL, SQL Server, MySQL, PostgreSQL, Redshift, Snowflake, Trino, GizmoSQL, Oracle, Db2, Quack and Hardcharger) with system-wide manifests in /etc/adbc/drivers, for data movement jobs that run next to the server. See the README's Docker section for details.

⁠📦 Also available

• Binaries for Linux (x86-64, arm64), macOS (Apple silicon) and Windows (x64, arm64) on every GitHub release⁠.
• Python: pip install hardcharger runs the server; pip install adbc-driver-hardcharger is the client.
• iPhone and iPad: the whole server on the device, on the App Store.

⁠💬 Community and support

Documentation: https://docs.hardcharger.gizmodata.com⁠. Issues and feature requests: https://github.com/gizmodata/hardcharger/issues⁠. Slack: GizmoData Community⁠.

Hardcharger™ and GizmoData™ are trademarks of GizmoData LLC. Apache License 2.0.