SQL functions and settings

Hardcharger™ runs DuckDB 2.0, so the SQL is DuckDB’s: see DuckDB’s documentation for the language itself. This page lists what Hardcharger adds. The function and setting tables are generated from a running server (duckdb_functions(), DESCRIBE, hardcharger_settings()), and CI fails when they drift.

Functions

Scalar functions

Function	Returns	Description
`HARDCHARGER_CURRENT_CLUSTER()`	`VARCHAR`	The `cluster_id` the replicas share, or NULL when unset.
`HARDCHARGER_CURRENT_INSTANCE()`	`VARCHAR`	This server process's id (a UUID), new at every start.
`HARDCHARGER_CURRENT_SESSION()`	`VARCHAR`	This session's id, its Warp SQL session id (`s_...`), as `KILL SESSION` and instrumentation name it.
`HARDCHARGER_INSTRUMENTATION_CATALOG()`	`VARCHAR`	The catalog of the instrumentation tables (empty when off).
`HARDCHARGER_INSTRUMENTATION_ENABLED()`	`BOOLEAN`	Whether instrumentation is on.
`HARDCHARGER_INSTRUMENTATION_SCHEMA()`	`VARCHAR`	The schema of the instrumentation tables (empty when off).
`HARDCHARGER_ROLE()`	`VARCHAR`	The session's role: `admin`, `user` or `readonly` (for store users under access control, their role in the server's sense).
`HARDCHARGER_USER()`	`VARCHAR`	The user this session signed in as.
`HARDCHARGER_VERSION()`	`VARCHAR`	The server's version, such as `2.0.0-rc.1` (as `--version` prints it).
`hardcharger_cancel()`	`BOOLEAN`	Stops what a session runs and keeps the session (its next statement runs as usual): its statement ends cancelled, result streams are cut off, uploads in flight are aborted. Returns whether there was anything to stop; a session can't cancel itself. `KILL SESSION` does the same, then ends the session.

Table functions

`hardcharger_active_connections()`

A row per open session: who (user, role, tenant, how they signed in), from where (address, User-Agent, TLS, client certificate), what it runs (state, the statement, redacted as the log redacts it, since when) and its open result streams, partitions, uploads and retained results. Needs no instrumentation. Users see only their own sessions.

Column	Type
`session_id`	`VARCHAR`
`instance_id`	`VARCHAR`
`cluster_id`	`VARCHAR`
`username`	`VARCHAR`
`role`	`VARCHAR`
`tenant`	`VARCHAR`
`auth_method`	`VARCHAR`
`client_address`	`VARCHAR`
`proxy_address`	`VARCHAR`
`client_info`	`VARCHAR`
`session_tags`	`MAP(VARCHAR, VARCHAR)`
`tls`	`BOOLEAN`
`tls_version`	`VARCHAR`
`certificate_identity`	`VARCHAR`
`certificate_thumbprint`	`VARCHAR`
`token_certificate_bound`	`BOOLEAN`
`state`	`VARCHAR`
`transaction`	`VARCHAR`
`statement_id`	`VARCHAR`
`statement`	`VARCHAR`
`statement_started_at`	`TIMESTAMP WITH TIME ZONE`
`queued_since`	`TIMESTAMP WITH TIME ZONE`
`session_started_at`	`TIMESTAMP WITH TIME ZONE`
`last_activity_at`	`TIMESTAMP WITH TIME ZONE`
`cancel_reason`	`VARCHAR`
`result_partitions`	`INTEGER`
`open_result_streams`	`INTEGER`
`open_ingest_parts`	`INTEGER`
`retained_results`	`INTEGER`
`retained_rows`	`BIGINT`
`is_current`	`BOOLEAN`

`hardcharger_effective_privileges()`

Under access control, what a user may do, directly or through its roles (via). Without an argument, the current user; with a user name, that user, for the administrator (or a tenant admin, for its own tenant's users).

Column	Type
`user_name`	`VARCHAR`
`privilege`	`VARCHAR`
`object_type`	`VARCHAR`
`catalog_name`	`VARCHAR`
`schema_name`	`VARCHAR`
`object_name`	`VARCHAR`
`column_name`	`VARCHAR`
`via`	`VARCHAR`
`with_grant_option`	`BOOLEAN`

`hardcharger_grants()`

Under access control, the grants in the store: who (grantee, a role or user), what (privilege, object_type and the object; column_name for a column grant), by whom and with grant option. The administrator sees all of them; a store user only grants to itself and to the roles it holds. No rows without access control.

Column	Type
`grantee`	`VARCHAR`
`grantee_type`	`VARCHAR`
`privilege`	`VARCHAR`
`object_type`	`VARCHAR`
`catalog_name`	`VARCHAR`
`schema_name`	`VARCHAR`
`object_name`	`VARCHAR`
`column_name`	`VARCHAR`
`grantor`	`VARCHAR`
`with_grant_option`	`BOOLEAN`
`tenant`	`VARCHAR`

`hardcharger_metrics()`

The runtime metrics /metrics serves, one row per sample. Needs --enable-metrics.

Column	Type
`name`	`VARCHAR`
`value`	`DOUBLE`
`labels`	`MAP(VARCHAR, VARCHAR)`

`hardcharger_policies()`

Under access control, the row policies and column masks on tables the caller can see, and whether each applies to the current user.

Column	Type
`name`	`VARCHAR`
`kind`	`VARCHAR`
`catalog_name`	`VARCHAR`
`schema_name`	`VARCHAR`
`table_name`	`VARCHAR`
`column_name`	`VARCHAR`
`permissive`	`BOOLEAN`
`roles`	`VARCHAR[]`
`exempt_roles`	`VARCHAR[]`
`expression`	`VARCHAR`
`applies_to_current_user`	`BOOLEAN`

`hardcharger_role_members()`

Under access control, who holds which role (a user or another role), with admin option and grantor. A store user sees only its own memberships.

Column	Type
`role`	`VARCHAR`
`member`	`VARCHAR`
`member_type`	`VARCHAR`
`admin_option`	`BOOLEAN`
`grantor`	`VARCHAR`
`issuer`	`VARCHAR`
`tenant`	`VARCHAR`

`hardcharger_roles()`

Under access control, the roles (PUBLIC among them). A store user sees only the roles it holds.

Column	Type
`name`	`VARCHAR`
`builtin`	`BOOLEAN`
`tenant`	`VARCHAR`
`is_active`	`BOOLEAN`

`hardcharger_server_info()`

One row: the versions, the instance and cluster ids, the start time and the uptime; for an administrator without catalog_access rules also the host, listen addresses and ports, TLS, the web UI, the access-control store and the session count (NULL for everyone else).

Column	Type
`hardcharger_version`	`VARCHAR`
`duckdb_version`	`VARCHAR`
`arrow_version`	`VARCHAR`
`instance_id`	`VARCHAR`
`cluster_id`	`VARCHAR`
`instance_tag`	`VARCHAR`
`start_time`	`TIMESTAMP WITH TIME ZONE`
`uptime`	`INTERVAL`
`uptime_seconds`	`BIGINT`
`hostname`	`VARCHAR`
`os_platform`	`VARCHAR`
`os_name`	`VARCHAR`
`os_version`	`VARCHAR`
`cpu_arch`	`VARCHAR`
`cpu_model`	`VARCHAR`
`cpu_count`	`INTEGER`
`memory_total_bytes`	`BIGINT`
`memory_resident_bytes`	`BIGINT`
`database_path`	`VARCHAR`
`read_only`	`BOOLEAN`
`listen_address`	`VARCHAR`
`port`	`INTEGER`
`health_port`	`INTEGER`
`metrics_address`	`VARCHAR`
`metrics_port`	`INTEGER`
`oauth_enabled`	`BOOLEAN`
`tls_enabled`	`BOOLEAN`
`mtls_enabled`	`BOOLEAN`
`mtls_client_certificate_required`	`BOOLEAN`
`server_certificate_sha256`	`VARCHAR`
`web_ui_enabled`	`BOOLEAN`
`rbac_store_type`	`VARCHAR`
`session_count`	`INTEGER`
`default_catalog`	`VARCHAR`
`default_schema`	`VARCHAR`
`instrumentation_queued`	`BIGINT`
`instrumentation_dropped`	`BIGINT`
`instrumentation_failed`	`BIGINT`

`hardcharger_sessions()`

The open sessions. Administrators see all of them; other users only their own.

Column	Type
`session_id`	`VARCHAR`
`username`	`VARCHAR`
`role`	`VARCHAR`
`auth_method`	`VARCHAR`
`start_time`	`TIMESTAMP WITH TIME ZONE`
`running`	`BOOLEAN`
`is_current`	`BOOLEAN`

`hardcharger_settings()`

Every hardcharger.* setting with its current, session and global value, scope, flag, environment variable, default and description.

Column	Type
`name`	`VARCHAR`
`value`	`VARCHAR`
`session_value`	`VARCHAR`
`global_value`	`VARCHAR`
`scope`	`VARCHAR`
`settable`	`BOOLEAN`
`cli_flag`	`VARCHAR`
`input_type`	`VARCHAR`
`default_value`	`VARCHAR`
`env_var`	`VARCHAR`
`description`	`VARCHAR`

`hardcharger_users()`

Under access control, the store users: enabled, whether they have a password, tenant and attributes. A store user sees only itself.

Column	Type
`name`	`VARCHAR`
`enabled`	`BOOLEAN`
`has_password`	`BOOLEAN`
`tenant`	`VARCHAR`
`attributes`	`MAP(VARCHAR, VARCHAR)`
`is_current`	`BOOLEAN`

Settings

SET [SESSION | GLOBAL] hardcharger.<name> = <value> (or TO) and RESET [SESSION | GLOBAL] hardcharger.<name>. SET GLOBAL needs an administrator; startup settings can only be read, and say which option sets them.

SET hardcharger.query_timeout = 60;
SELECT name, value, scope FROM hardcharger_settings() WHERE name = 'hardcharger.query_timeout';
RESET hardcharger.query_timeout;

SET SESSION only

Setting	Type	Default	Description
`hardcharger.bypass_queue`	BOOLEAN	`false`	Skip the statement queue for this session (admins only may turn it on).
`hardcharger.query_tag`	VARCHAR		JSON object tagging this session's statements in instrumentation.
`hardcharger.session_tag`	VARCHAR		JSON object tagging this session in instrumentation.

SET SESSION, or SET GLOBAL (administrators)

Setting	Type	Default	Description
`hardcharger.capture_query_profile`	VARCHAR	`off`	Record DuckDB's query profile with each execution in instrumentation (off, standard, detailed). Startup option: `--capture-query-profile`.
`hardcharger.max_queue_wait`	INTEGER	`300`	Seconds a statement may wait in the queue (0: forever). Startup option: `--max-queue-wait`.
`hardcharger.query_log_level`	VARCHAR	`INFO`	Level of statement log lines (DEBUG, INFO, WARNING, ERROR). Startup option: `--query-log-level`.
`hardcharger.query_timeout`	INTEGER	`0`	Statement timeout in seconds (0: none). A request's Warp-Statement-Timeout wins. Startup option: `--query-timeout-seconds`.

SET GLOBAL only (administrators)

Setting	Type	Default	Description
`hardcharger.graceful_shutdown`	BOOLEAN	`true`	On the first stop signal, let running statements finish (false: stop at once). Takes effect at the next signal. Startup option: `--graceful-shutdown`.
`hardcharger.max_concurrent_statements`	INTEGER	`0`	Statements that run at once; more wait in the queue (0: no queue). Startup option: `--max-concurrent-statements`.
`hardcharger.max_queued_statements`	INTEGER	`-1`	Statements that may wait for a slot (-1: 8 x max_concurrent_statements; 0: unbounded). Startup option: `--max-queued-statements`.
`hardcharger.shutdown_grace_period_seconds`	INTEGER	`300`	How long a graceful shutdown waits for running statements (0: forever); also during a shutdown. Startup option: `--shutdown-grace-period-seconds`.

Read-only: set at startup

Setting	Type	Default	Description
`hardcharger.admin_bypass_queue_default`	BOOLEAN	`true`	Admin sessions skip the statement queue by default. Startup option: `--admin-bypass-queue-default`.
`hardcharger.allow_unsigned_extensions`	BOOLEAN	`false`	DuckDB may load unsigned extensions. Startup option: `--allow-unsigned-extensions`.
`hardcharger.auth_log_level`	VARCHAR	`INFO`	Level of sign-in log lines. Startup option: `--auth-log-level`.
`hardcharger.cluster_id`	VARCHAR		UUID shared by the replicas of one cluster (empty when unset). Startup option: `--cluster-id`.
`hardcharger.enable_catalog_logging`	BOOLEAN	`false`	Log lines are also written to a logs table. Startup option: `--enable-catalog-logging`.
`hardcharger.enable_instrumentation`	BOOLEAN	`false`	Sessions, statements and executions are recorded. Startup option: `--enable-instrumentation`.
`hardcharger.enable_metrics`	BOOLEAN	`false`	Runtime metrics are collected and served (/metrics, hardcharger_metrics()). Startup option: `--enable-metrics`.
`hardcharger.health_check_interval_seconds`	INTEGER	`5`	Seconds between background health checks. Startup option: `--health-check-interval-seconds`.
`hardcharger.health_check_staleness_seconds`	INTEGER	`15`	Age at which the last health check no longer counts. Startup option: `--health-check-staleness-seconds`.
`hardcharger.instance_id`	VARCHAR		This server process's UUID (as HARDCHARGER_CURRENT_INSTANCE()).
`hardcharger.instance_tag`	VARCHAR		JSON object recorded with this instance. Startup option: `--instance-tag`.
`hardcharger.instrumentation_catalog`	VARCHAR		Catalog of the instrumentation tables (empty when instrumentation is off). Startup option: `--instrumentation-catalog`.
`hardcharger.instrumentation_schema`	VARCHAR		Schema of the instrumentation tables (empty when instrumentation is off). Startup option: `--instrumentation-schema`.
`hardcharger.log_catalog`	VARCHAR		Catalog of the logs table (empty when catalog logging is off). Startup option: `--log-catalog`.
`hardcharger.log_schema`	VARCHAR		Schema of the logs table (empty when catalog logging is off). Startup option: `--log-schema`.
`hardcharger.max_header_bytes`	INTEGER	`16384`	Largest request header block accepted, in bytes. Startup option: `--max-header-bytes`.
`hardcharger.max_sessions`	INTEGER	`0`	Most non-admin sessions at once; more get too_many_sessions (0: unlimited). Startup option: `--max-sessions`.
`hardcharger.memory_limit`	VARCHAR		DuckDB memory_limit (empty: DuckDB's default). Startup option: `--memory-limit`.
`hardcharger.read_only`	BOOLEAN	`false`	Database opened read-only: every write is refused. Startup option: `--read-only`.
`hardcharger.session_idle_timeout`	INTEGER	`900`	Seconds an idle session lives (0: forever). Startup option: `--session-idle-timeout`.
`hardcharger.session_log_level`	VARCHAR	`INFO`	Level of session log lines. Startup option: `--session-log-level`.
`hardcharger.storage_version`	VARCHAR		DuckDB storage version for new databases (empty: DuckDB's default). Startup option: `--storage-version`.
`hardcharger.version`	VARCHAR		Server version (as HARDCHARGER_VERSION()).

HUGEINT and UHUGEINT

DuckDB’s 128-bit integers travel as Arrow decimal128(38, 0) by default, which every Arrow client reads. That type holds at most 38 digits, so a value of 10³⁸ or more (a HUGEINT can reach about 1.7 × 10³⁸, a UHUGEINT twice that) can’t be sent in it. Such a statement fails with a conversion error that names the value, rather than sending a wrong number:

$ HARDCHARGER_PASSWORD='change-me' hardcharger --host localhost --tls=false --username hardcharger --csv \
    --command "SELECT 170141183460469231731687303715884105727::HUGEINT AS big"
Error: Conversion Error: Hardcharger cannot send the HUGEINT value 170141183460469231731687303715884105727 as Arrow decimal128(38, 0), which holds at most 38 digits. CAST it to VARCHAR, or run SET SESSION arrow_lossless_conversion = true (DuckDB's 16-byte HUGEINT Arrow type, which holds every value)

Every value that fits is sent exactly as before. For the others, either CAST to VARCHAR:

$ HARDCHARGER_PASSWORD='change-me' hardcharger --host localhost --tls=false --username hardcharger --csv \
    --command "SELECT CAST(170141183460469231731687303715884105727::HUGEINT AS VARCHAR) AS big"
big
170141183460469231731687303715884105727

or turn on arrow_lossless_conversion for the session, which sends DuckDB’s own 16-byte Arrow types (an arrow.opaque extension type over fixed_size_binary(16), little-endian) that hold every value, and decode them in the client. It also changes how UUID and JSON columns are sent.

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="SET SESSION arrow_lossless_conversion = true")
        cur.execute(operation="SELECT 340282366920938463463374607431768211455::UHUGEINT AS biggest")
        raw = cur.fetchone()[0]
        print(int.from_bytes(raw, byteorder="little", signed=False))

340282366920938463463374607431768211455

The hardcharger CLI decodes them for you: with the option on, it prints exact integers in every output mode.

$ HARDCHARGER_PASSWORD='change-me' hardcharger --host localhost --tls=false --username hardcharger --csv --quiet \
    --command "SET SESSION arrow_lossless_conversion = true; SELECT 340282366920938463463374607431768211455::UHUGEINT AS biggest"
OK
biggest
340282366920938463463374607431768211455

Write SET SESSION: a plain SET arrow_lossless_conversion is DuckDB’s global setting, which changes every session’s results and needs an administrator (MANAGE CONFIG under access control). Over plain HTTP, the Warp SQL session option duckdb_arrow_lossless_conversion does the same for one session. JSON bind parameters beyond the 64-bit range bind exactly as HUGEINT or UHUGEINT; wider ones are refused.

KILL SESSION

KILL SESSION '<session id>';

Ends another session at once (administrators only); its next request gets 401 session_ended with reason killed. hardcharger_sessions() lists the ids. See Statement control.

Access-control statements

With access control on, these run like SQL, one per statement:

Statements	Guide
`CREATE`/`ALTER`/`DROP USER`, `CREATE`/`DROP ROLE`, `GRANT role TO`, `REVOKE role FROM`	Users, roles and grants
`GRANT`/`REVOKE` privileges `ON` table, view, `SCHEMA`, `CATALOG`; system privileges	Users, roles and grants
`SHOW GRANTS`, `ALTER TABLE`/`VIEW … OWNER TO`, `SET ROLE`	Users, roles and grants
`CREATE`/`DROP ROW POLICY`, `SHOW ROW POLICIES`	Row policies
`CREATE`/`DROP MASKING POLICY`, `ALTER TABLE … MODIFY COLUMN … SET`/`UNSET MASKING POLICY`, `SHOW MASKING POLICIES`	Masking
`CREATE`/`DROP TENANT`, `ALTER CATALOG … SET TENANT`, `ALTER TENANT … SET DEFAULT CATALOG`, `SHOW TENANTS`	Tenants
`CREATE`/`DROP GROUP MAPPING`, `SHOW GROUP MAPPINGS`	SSO
`CREATE`/`DROP SCOPED TOKEN`, `SHOW SCOPED TOKENS`	Scoped tokens

Row policies may call session_attribute('key') (a user attribute set with ALTER USER … SET ATTRIBUTE) and is_role_active('role').

System catalogs

Catalog	Contents
`_hardcharger_system`	Read-only views the drivers use: `hardcharger_index_info` (JDBC `getIndexInfo`) and `hardcharger_view_definition`
`_hardcharger_instr`	Instrumentation (with `--enable-instrumentation`; administrators only)
`_hardcharger_logs`	Catalog logging (with `--enable-catalog-logging`; administrators only)

Nobody writes to, detaches or USEs these catalogs.