examples/QuerySLAShield

Query SLA Shield — query timeout governance for openGauss

Query SLA Shield adds policy-based statement timeout handling to openGauss. It keeps the existing statement_timeout timer path and adds:

• shared-memory timeout policies scoped by user, database, or normalized SQL-ID;
• a statement_timeout set-hint source for per-statement budgets;
• a SUSET hard ceiling for sessions that need an upper bound;
• timeout events exposed through dbe_perf.query_timeout_history.

The event records user, database, client, SQL-ID, timeout, elapsed time, and the source that selected the budget. Normalized SQL text can be recovered by joining dbe_perf.statement_history on unique_query_id when statement tracking has a matching row.

Layout

QuerySLAShield/
├── kernel/src/              new module sources at their kernel-relative paths
│   ├── gausskernel/cbb/instruments/query_sla/   query_sla.cpp, query_sla_funcs.cpp, Makefile, CMakeLists.txt
│   └── include/instruments/query_sla.h
├── patches/                 kernel changes as git patches, grouped by concern
│   ├── 0001-query-sla-guc-and-shared-memory.patch
│   ├── 0002-query-sla-hint-and-arming.patch
│   ├── 0003-query-sla-dbe-perf-sql-surface.patch
│   ├── 0004-query-sla-module-build-wiring.patch
│   └── 0005-query-sla-new-module-sources.patch    (the new module sources)
├── local_patches/           optional host-build patch, not part of the feature
├── sql/                     upgrade_query_sla.sql + rollback_query_sla.sql (existing-cluster install/uninstall)
├── scripts/                 apply_to_upstream, build, init_instance, run_tests, run_demo, ...
├── tests/                   demo.sql (bank-scenario sample), pbe_test.c (libpq extended-protocol check)
└── docs/                    DESIGN, OPERATIONS

The upstream clone, the third-party binarylibs, the local instance and logs are created under build/ (git-ignored). The kernel/ tree keeps the new module sources readable; patch 0005 applies those same sources to the upstream checkout. The patch set intentionally contains only the Query SLA Shield feature.

local_patches/0001-openEuler-build-on-generic-glibc-host.patch is an opt-in build-host aid for running the pinned openGauss 6.0.0 tree on generic glibc hosts. It is not applied by default and is not part of the feature patch series.

Build and run

Prerequisites: the openGauss third-party binarylibs for openEuler x86_64 (ships the gcc 7.3 toolchain) and the normal openGauss build dependencies for the host (including the libaio development header). Download the binarylibs from the openGauss site and point BINARYLIBS at the extracted directory (the one containing buildtools/gcc7.3).

cd QuerySLAShield
export BINARYLIBS=/abs/path/to/openGauss-third_party_binarylibs_openEuler_x86_64

# 1) fetch the pinned upstream and apply the feature patches
scripts/apply_to_upstream.sh

# On a generic glibc host where the unmodified openGauss 6.0.0 build does not
# compile, add GS_APPLY_LOCAL_PORTABILITY=1 to apply the local build-host patch.

# 2) build (debug)
scripts/build.sh debug

# 3) initialise + start the local instance (catalog changed -> first run needs --fresh)
scripts/init_instance.sh --fresh

# 4) automated suite + bank sample
scripts/run_tests.sh
scripts/run_demo.sh

Stop with scripts/stop_instance.sh. After editing module sources, rebuild incrementally with scripts/resume_build.sh.

Capabilities

Area	What
Timeout sources	query_sla_default_timeout_ms (global, admin-set / SUSET), SET statement_timeout (session), /*+ set(statement_timeout N) */ (hint)
Multi-scope policies	dbe_perf.set_query_timeout_policy('user'|'db'|'sqlid', key, ms) in a shared-memory registry, effective immediately for all sessions (in-memory only — re-apply after a restart; see docs/OPERATIONS.md)
Resolution	priority sqlid > user > db > hint > session > global (first non-zero); query_sla_safety_mode=on takes the minimum non-zero of all matched sources
Hard ceiling	query_sla_hard_limit_ms (SUSET, session-local) clamps everything
Event trail	every fusing recorded with user/db/client direct in the event; dbe_perf.query_timeout_history view; join statement_history by unique_query_id for the normalized SQL text when statement tracking is on and a row matches
Disabled (enable=off)	preserves legacy statement_timeout cancellation semantics and records no events — one parser-level change: a set(statement_timeout) hint is recognized (not rejected with an "unsupported hint" warning) but inert when disabled

SQL surface (dbe_perf schema)

Function / view	Purpose
set_query_timeout_policy(scope, key, timeout_ms)	register a policy, timeout_ms > 0 (system admin only)
clear_query_timeout_policy(scope, key)	remove a policy (system admin only)
list_query_timeout_policy()	list all policies — scope, policy_key, timeout_ms, creator, updated_at (system / monitor admin)
query_timeout_history() / view	timeout events — event_time, user_name, db_name, client_addr, unique_query_id, timeout_ms, elapsed_ms, policy_source, cancel_reason (system / monitor admin)

Design and correctness: docs/DESIGN.md. Operations: docs/OPERATIONS.md.