diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4ac0b96..a7090f2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -83,7 +83,7 @@ jobs:
--outputdir=test/regression/results \
--temp-instance=test/regression/tmp_check \
--temp-config=test/regression/pg_stat_ch.conf \
- basic version guc stats utility buffers cmd_type client_info error_capture upgrade
+ basic version guc stats utility buffers cmd_type client_info error_capture upgrade relations
- name: Run isolation tests
run: |
diff --git a/README.md b/README.md
index 492d627..9c27d4c 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,8 @@ SELECT * FROM pg_stat_ch_stats();
| `pg_stat_ch.clickhouse_use_tls` | bool | `off` | Restart | Enable TLS for ClickHouse connections |
| `pg_stat_ch.clickhouse_skip_tls_verify` | bool | `off` | Restart | Skip TLS certificate verification (insecure) |
| `pg_stat_ch.log_min_elevel` | enum | `warning` | Superuser | Minimum error level to capture (debug5..panic) |
+| `pg_stat_ch.relations_enabled` | bool | `off` | Restart | Collect the relations array (tables/views a query touches); apply the relations schema migrations before enabling |
+| `pg_stat_ch.relations_max_len` | int | `1023` | Superuser | Maximum encoded size in bytes of the per-query relations blob |
See [Error Level Values](docs/version-compatibility.md#error-fields) for the complete list of error levels and their numeric values in ClickHouse.
diff --git a/docs/guides/opentelemetry.mdx b/docs/guides/opentelemetry.mdx
index da4c27b..f82c661 100644
--- a/docs/guides/opentelemetry.mdx
+++ b/docs/guides/opentelemetry.mdx
@@ -21,6 +21,7 @@ When `use_otel` is enabled, the ClickHouse connection parameters are ignored. Th
The OTel exporter maps pg_stat_ch events to OpenTelemetry semantic conventions:
- **Logs**: Each query execution becomes an OTel log record with attributes following the [database semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/) (`db.name`, `db.user`, `db.operation.name`, `db.query.text`).
+- **Relations**: tables/views touched by the query are exported as 3 separate native OTel array attributes, positionally parallel to each other: `relation_namespaces` (schema names), `relation_names` (relation names), `relation_kinds` (single-character `pg_class.relkind` per entry: `r`=table, `v`=view, `m`=matview, `f`=foreign table, `p`=partitioned table, ...). This mirrors the 3-array shape used for the ClickHouse-native export path; neither shape is final -- OTLP 1.9.0 added complex-type array attributes, and the ClickHouse schema may move to `Array(Tuple(...))`, so this representation may change.
The exporter builds OTLP log requests directly in the bgworker. pg_stat_ch's shared-memory queue already buffers events, and the exporter chunks those events into bounded gRPC requests.
diff --git a/docs/reference/configuration.mdx b/docs/reference/configuration.mdx
index 680adfe..851fda0 100644
--- a/docs/reference/configuration.mdx
+++ b/docs/reference/configuration.mdx
@@ -141,6 +141,47 @@ Extract [sqlcommenter](https://google.github.io/sqlcommenter/) labels from query
When enabled, the background worker parses the `/* key='value' */` comment that ends each query and exports the pairs as a JSON object in the `labels` column (the `labels` attribute in OpenTelemetry). When disabled, no `labels` column is sent, so ClickHouse stores its `{}` default. Apply the `labels` schema migration before enabling it.
+## Relations
+
+### `pg_stat_ch.relations_enabled`
+
+Collect the relations array (tables/views a query touches).
+
+| | |
+|---|---|
+| **Type** | boolean |
+| **Default** | `off` |
+| **Context** | postmaster |
+
+When enabled, pg_stat_ch resolves each query's touched relations (tables, views, materialized views, foreign tables, partitioned tables) and exports them as three parallel arrays -- `relation_namespaces`/`relation_names`/`relation_kinds` -- plus a `relations_truncated` flag. Toggling this off skips the catalog lookups entirely, not just the storage -- useful for isolating this feature's hot-path cost from pg_stat_ch's baseline overhead.
+
+PGC_POSTMASTER: the ClickHouse exporter keeps its column set for the life of the bgworker, so changing this requires a restart. Apply the relations schema migrations before enabling it.
+
+```sql
+-- Enable relations collection after applying the schema migrations
+ALTER SYSTEM SET pg_stat_ch.relations_enabled = on;
+-- then restart PostgreSQL
+```
+
+### `pg_stat_ch.relations_max_len`
+
+Maximum encoded size, in bytes, of the per-query relations blob.
+
+| | |
+|---|---|
+| **Type** | integer |
+| **Default** | `1023` |
+| **Min** | `2` (just enough room for the 2-byte header) |
+| **Max** | `1023` |
+| **Context** | suset |
+
+Queries touching enough distinct relations to exceed this budget are truncated: `relations_truncated` is set to `true` for that event, and the relation arrays contain only as many entries as fit. Lower this if you want to bound the per-event ClickHouse payload size further; it cannot be raised above the compiled-in maximum.
+
+```sql
+-- Lower the budget, e.g. to bound payload size more aggressively
+SET pg_stat_ch.relations_max_len = 256;
+```
+
## Queue
The shared-memory ring buffer sits between the foreground hooks and the background worker. These settings control its size and drain behavior.
diff --git a/docs/reference/events-schema.mdx b/docs/reference/events-schema.mdx
index dee5413..dacd2da 100644
--- a/docs/reference/events-schema.mdx
+++ b/docs/reference/events-schema.mdx
@@ -44,6 +44,19 @@ Query text is cut at 2,047 bytes, and text that reaches that length gets no labe
Label values are exported as written by the application. Don't put PII, tokens, or secrets in sqlcommenter comments.
+## Relations
+
+| Column | Type | Description |
+|---|---|---|
+| `relation_namespaces` | `Array(LowCardinality(String))` | Schema name of each distinct table/view/materialized view/foreign table/partitioned table the query touched, positionally parallel to `relation_names` and `relation_kinds`. Partitions and inheritance children are reported through their parent, not individually (for example, `SELECT * FROM inh_p` lists only `inh_p`). Recorded only for queries that complete; error events have empty relation arrays. |
+| `relation_names` | `Array(LowCardinality(String))` | Relation name of each distinct relation the query touched. |
+| `relation_kinds` | `Array(FixedString(1))` | `pg_class.relkind` for each entry: `r` (table), `v` (view), `m` (materialized view), `f` (foreign table), `p` (partitioned table), etc. |
+| `relations_truncated` | `Bool` | `true` if the query touched more relations than fit within `pg_stat_ch.relations_max_len`; the arrays above are incomplete for that event. |
+
+
+These columns require [`pg_stat_ch.relations_enabled`](/reference/configuration#pg_stat_chrelations_enabled) (off by default -- apply the relations schema migrations, then enable it). Once enabled, all three relation arrays are still empty for utility statements and for queries that touch no relations. See [`pg_stat_ch.relations_max_len`](/reference/configuration#pg_stat_chrelations_max_len) for the truncation budget. `events_recent_1h` keeps the columns it was created with, so it has no relation columns.
+
+
## Shared buffer usage
These columns show how queries interact with PostgreSQL's `shared_buffers` cache. The cache hit ratio for a query is `shared_blks_hit / (shared_blks_hit + shared_blks_read)`. Target above 99% for OLTP workloads.
diff --git a/docs/reference/hooks.mdx b/docs/reference/hooks.mdx
index 18e23e4..5a3a052 100644
--- a/docs/reference/hooks.mdx
+++ b/docs/reference/hooks.mdx
@@ -59,7 +59,8 @@ This hook is used purely for nesting level tracking. The actual metric capture h
1. Finalizes instrumentation (`InstrEndLoop`)
2. Computes CPU time delta from `getrusage()`
3. Extracts all metrics from `QueryDesc`
-4. Builds a `PschEvent` and enqueues it to shared memory
+4. If `pg_stat_ch.relations_enabled` is on, walks `query_desc->plannedstmt->rtable`, resolving each distinct relation to its schema-qualified name and `pg_class.relkind` into a length-prefixed buffer bounded by `pg_stat_ch.relations_max_len` (queries that exceed the budget are truncated and flagged via `relations_truncated`)
+5. Builds a `PschEvent` and enqueues it to shared memory
## Metrics Captured from QueryDesc
@@ -182,6 +183,7 @@ Parallel workers execute portions of a query plan. pg_stat_ch:
│ ├─ Finalize instrumentation │
│ ├─ Compute CPU delta │
│ ├─ Extract metrics from QueryDesc │
+│ ├─ Collect touched relations (schema, name, relkind) │
│ └─ Enqueue PschEvent to shared memory │
│ │
│ ProcessUtility_hook │
diff --git a/include/config/guc.h b/include/config/guc.h
index 75e1066..efe574c 100644
--- a/include/config/guc.h
+++ b/include/config/guc.h
@@ -38,6 +38,8 @@ extern bool psch_use_unified_arrow_exporter;
extern int psch_otel_max_block_bytes;
extern char* psch_extra_attributes;
extern char* psch_debug_arrow_dump_dir;
+extern int psch_relations_max_len;
+extern bool psch_relations_enabled;
// Initialize GUC variables
void PschInitGuc(void);
diff --git a/include/hooks/relations_budget.h b/include/hooks/relations_budget.h
new file mode 100644
index 0000000..2d5397b
--- /dev/null
+++ b/include/hooks/relations_budget.h
@@ -0,0 +1,11 @@
+#ifndef PG_STAT_CH_INCLUDE_HOOKS_RELATIONS_BUDGET_H_
+#define PG_STAT_CH_INCLUDE_HOOKS_RELATIONS_BUDGET_H_
+
+// [truncated:u8][count:u8] -- the GUC's minimum must never go below this.
+#define PSCH_RELATIONS_HEADER_LEN 2
+
+// Sentinel relations_len for "blob lost to DSA OOM" -- distinct from 0 (no
+// relations) and real blob lengths (>= PSCH_RELATIONS_HEADER_LEN).
+#define PSCH_RELATIONS_OOM_LEN 1
+
+#endif // PG_STAT_CH_INCLUDE_HOOKS_RELATIONS_BUDGET_H_
diff --git a/schema/migrations/20261116000001_add_relation_columns.sql b/schema/migrations/20261116000001_add_relation_columns.sql
new file mode 100644
index 0000000..5061614
--- /dev/null
+++ b/schema/migrations/20261116000001_add_relation_columns.sql
@@ -0,0 +1,19 @@
+-- Adds structured relation columns: namespace, name, and relkind kept as
+-- separate parallel arrays. Collected in src/hooks/hooks.c at ExecutorEnd.
+
+-- +goose Up
+
+-- +goose StatementBegin
+ALTER TABLE pg_stat_ch.events_raw
+ ADD COLUMN IF NOT EXISTS relation_namespaces Array(LowCardinality(String)) COMMENT 'Schema name per entry, positionally parallel to relation_names/relation_kinds.',
+ ADD COLUMN IF NOT EXISTS relation_names Array(LowCardinality(String)) COMMENT 'Relation name per entry, positionally parallel to relation_namespaces/relation_kinds.',
+ ADD COLUMN IF NOT EXISTS relation_kinds Array(FixedString(1)) COMMENT 'pg_class.relkind char per entry (r=table, v=view, m=matview, f=foreign table, p=partitioned table, ...).',
+ ADD COLUMN IF NOT EXISTS relations_truncated Bool DEFAULT false COMMENT 'True if pg_stat_ch.relations_max_len was exceeded and this list is incomplete.';
+-- +goose StatementEnd
+
+-- +goose Down
+
+-- Keep the columns on rollback: ClickHouse refuses to drop them while
+-- events_recent_1h's SELECT * depends on them, and producers that don't send
+-- them still insert.
+SELECT 1;
diff --git a/scripts/run-tests.sh b/scripts/run-tests.sh
index 98033bd..9c8ed2a 100755
--- a/scripts/run-tests.sh
+++ b/scripts/run-tests.sh
@@ -110,7 +110,7 @@ run_regress() {
--outputdir=test/regression/results \
--temp-instance=test/regression/tmp_check \
--temp-config=test/regression/pg_stat_ch.conf \
- basic version guc stats utility buffers cmd_type client_info error_capture drop_database_barrier upgrade
+ basic version guc stats utility buffers cmd_type client_info error_capture drop_database_barrier upgrade relations
}
# Run TAP tests
diff --git a/src/config/guc.c b/src/config/guc.c
index d6a80ff..329c01f 100644
--- a/src/config/guc.c
+++ b/src/config/guc.c
@@ -7,6 +7,7 @@
#include
#include "config/guc.h"
+#include "hooks/relations_budget.h"
// GUC variable storage
bool psch_enabled = true;
@@ -40,6 +41,8 @@ bool psch_use_unified_arrow_exporter = false;
int psch_otel_max_block_bytes = 3 * 1024 * 1024; // 3 MiB (max: 16 MiB)
char* psch_extra_attributes = NULL;
char* psch_debug_arrow_dump_dir = NULL;
+int psch_relations_max_len = 1023; // bytes, leaves room for the NUL in PSCH_MAX_RELATIONS_LEN=1024
+bool psch_relations_enabled = false;
// Log level options (matches PostgreSQL's server_message_level_options pattern)
// clang-format off
@@ -410,6 +413,35 @@ void PschInitGuc(void) {
0,
NULL, NULL, NULL);
+ DefineCustomIntVariable(
+ "pg_stat_ch.relations_max_len",
+ "Maximum bytes for the encoded list of tables/views a query touches.",
+ "Mirrors the query-text truncation pattern: the relations blob is a fixed "
+ "backend-local buffer, truncated (not grown) when a query touches enough "
+ "distinct relations to exceed this budget.",
+ &psch_relations_max_len,
+ 1023, // bootValue
+ PSCH_RELATIONS_HEADER_LEN, // min -- the header alone must still fit
+ 1023, // max (PSCH_MAX_RELATIONS_LEN - 1, room for the NUL)
+ PGC_SUSET,
+ 0,
+ NULL, NULL, NULL);
+
+ DefineCustomBoolVariable(
+ "pg_stat_ch.relations_enabled",
+ "Collect the relations array (tables/views a query touches).",
+ "When enabled, each backend resolves a query's touched relations from "
+ "its plan's range table at ExecutorEnd and exports them as the "
+ "relation_namespaces/relation_names/relation_kinds/relations_truncated "
+ "columns. Apply the relations schema migrations before enabling. "
+ "PGC_POSTMASTER: the ClickHouse exporter keeps its column set for the "
+ "life of the bgworker, so a runtime change would leave a stale column.",
+ &psch_relations_enabled,
+ false,
+ PGC_POSTMASTER,
+ 0,
+ NULL, NULL, NULL);
+
DefineCustomBoolVariable(
"pg_stat_ch.track_labels",
"Extract sqlcommenter labels from query comments.",
diff --git a/src/export/clickhouse_exporter.cc b/src/export/clickhouse_exporter.cc
index 19c6a41..09fc7e3 100644
--- a/src/export/clickhouse_exporter.cc
+++ b/src/export/clickhouse_exporter.cc
@@ -180,6 +180,9 @@ class ClickHouseExporter : public StatsExporter {
shared_ptr> StatHCUInt64(string_view name) final {
return MakeCol>(name, "UInt64");
}
+ shared_ptr>> StatHCStringArray(string_view name) final {
+ return MakeCol(name);
+ }
shared_ptr> StatTimestamp(string_view name) final {
return MakeCol>(name, "DateTime64(6)");
@@ -263,6 +266,41 @@ class ClickHouseExporter : public StatsExporter {
chc_column col_{};
};
+ // Array(String) column: same flattened-bytes approach as StringCol, plus
+ // row_offsets_ tracking each row's cumulative element count.
+ class ArrayStringCol : public Column>, public ChColumn {
+ public:
+ ArrayStringCol(ClickHouseExporter* exp, string_view name) : exp_(exp), name_(name) {}
+ void Append(const std::vector& arr) final {
+ for (const auto& s : arr) {
+ bytes_.insert(bytes_.end(), s.data(), s.data() + s.size());
+ value_offsets_.push_back(bytes_.size());
+ }
+ row_offsets_.push_back(value_offsets_.size());
+ }
+ bool Crunch() final {
+ values_col_ = chc_build_string(value_offsets_.data(),
+ reinterpret_cast(bytes_.data()),
+ value_offsets_.size());
+ col_ = chc_build_array(row_offsets_.data(), row_offsets_.size(), &values_col_);
+ return exp_->AppendColumn(name_, "Array(String)", &col_);
+ }
+ void Clear() final {
+ bytes_.clear();
+ value_offsets_.clear();
+ row_offsets_.clear();
+ }
+
+ private:
+ ClickHouseExporter* const exp_;
+ const std::string name_;
+ std::vector bytes_;
+ std::vector value_offsets_;
+ std::vector row_offsets_;
+ chc_column values_col_{};
+ chc_column col_{};
+ };
+
template
shared_ptr MakeCol(string_view name, Args&&... args) {
if (auto it = col_index_.find(name); it != col_index_.end()) {
diff --git a/src/export/exporter_interface.h b/src/export/exporter_interface.h
index a70abfb..bef6a15 100644
--- a/src/export/exporter_interface.h
+++ b/src/export/exporter_interface.h
@@ -6,6 +6,7 @@
#include
#include
#include
+#include
class StatsExporter {
protected:
@@ -21,6 +22,15 @@ class StatsExporter {
virtual ~Column() = default;
};
+ // No-op column: the default StatHCStringArray() implementation below
+ // returns this so callers never need a null check, matching the "not every
+ // backend implements every column" pattern SendArrowBatch already uses.
+ template
+ class NoopColumn : public Column {
+ public:
+ void Append(const T& /*t*/) final {}
+ };
+
public:
// ===========================================================================
// Cardinality-typed columns.
@@ -55,6 +65,14 @@ class StatsExporter {
virtual shared_ptr> StatHCInt64(string_view name) = 0;
virtual shared_ptr> StatHCUInt64(string_view name) = 0;
+ // Array-of-strings column. Non-pure with a no-op default so a backend
+ // that doesn't implement it yet simply discards, rather than a pure
+ // virtual forcing every backend to handle it explicitly.
+ virtual shared_ptr>> StatHCStringArray(string_view name) {
+ (void)name;
+ return std::make_shared>>();
+ }
+
// Domain-specific. Caller appends a Unix-epoch microsecond timestamp.
// (PG-epoch values must be offset by kPostgresEpochOffsetUs before append;
// CH DateTime64(6) and OTel time_unix_nano both interpret the wire value
diff --git a/src/export/otel_arrow_exporter.cc b/src/export/otel_arrow_exporter.cc
index ad85c91..0ccaf71 100644
--- a/src/export/otel_arrow_exporter.cc
+++ b/src/export/otel_arrow_exporter.cc
@@ -21,6 +21,7 @@ extern "C" {
#include
#include
+#include
#include
#include
#include
@@ -180,6 +181,9 @@ class OTelArrowExporter : public StatsExporter {
shared_ptr> StatHCUInt64(string_view n) final {
return MakeNum(n, arrow::uint64());
}
+ shared_ptr>> StatHCStringArray(string_view n) final {
+ return MakeListUtf8Sv(n);
+ }
shared_ptr> StatTimestamp(string_view n) final { return MakeTimestamp(n); }
@@ -301,6 +305,39 @@ class OTelArrowExporter : public StatsExporter {
size_t* const bytes_;
};
+ // list(utf8) column for StatHCStringArray -- mirrors the OTelExporter's
+ // array_value log attribute (used for relation_namespaces/relation_names/
+ // relation_kinds, e.g. relation_names -> ["foo1","foo3"], namespace kept
+ // in the parallel relation_namespaces array, not inlined here), just
+ // built as an Arrow list instead of an OTLP AnyValue.array_value.
+ class ArrowListUtf8SvColumn : public Column> {
+ public:
+ ArrowListUtf8SvColumn(arrow::ListBuilder* builder, arrow::StringBuilder* value_builder,
+ size_t* bytes)
+ : builder_(builder), value_builder_(value_builder), bytes_(bytes) {}
+ void Append(const std::vector& v) final {
+ arrow::Status s = builder_->Append();
+ if (!s.ok()) {
+ LogArrowFailure("Arrow list append", s);
+ return;
+ }
+ *bytes_ += kVarLenOffsetBytes;
+ for (const auto& elem : v) {
+ s = value_builder_->Append(elem.data(), static_cast(elem.size()));
+ if (!s.ok()) {
+ LogArrowFailure("Arrow list element append", s);
+ return;
+ }
+ *bytes_ += elem.size() + kVarLenOffsetBytes;
+ }
+ }
+
+ private:
+ arrow::ListBuilder* const builder_;
+ arrow::StringBuilder* const value_builder_;
+ size_t* const bytes_;
+ };
+
class ArrowTimestampColumn : public Column {
public:
ArrowTimestampColumn(arrow::TimestampBuilder* builder, size_t* bytes)
@@ -351,6 +388,17 @@ class OTelArrowExporter : public StatsExporter {
{std::string(name), arrow::field(std::string(name), arrow::utf8()), std::move(builder)});
return std::make_shared(raw, &bytes_estimate_);
}
+ shared_ptr>> MakeListUtf8Sv(string_view name) {
+ auto value_builder = std::make_shared();
+ auto* raw_value = value_builder.get();
+ auto builder =
+ std::make_shared(arrow::default_memory_pool(), value_builder);
+ auto* raw = builder.get();
+ slots_.push_back({std::string(name),
+ arrow::field(std::string(name), arrow::list(arrow::utf8())),
+ std::move(builder)});
+ return std::make_shared(raw, raw_value, &bytes_estimate_);
+ }
shared_ptr> MakeTimestamp(string_view name) {
auto builder =
std::make_shared(TimestampType(), arrow::default_memory_pool());
diff --git a/src/export/otel_exporter.cc b/src/export/otel_exporter.cc
index a97ea8b..fcb6560 100644
--- a/src/export/otel_exporter.cc
+++ b/src/export/otel_exporter.cc
@@ -17,6 +17,7 @@
#include "config/guc.h"
#include "export/exporter_interface.h"
+#include "export/otel_string_array_attr.h"
#include
#include
@@ -181,6 +182,9 @@ class OTelExporter : public StatsExporter {
shared_ptr> StatHCUInt64(string_view name) final {
return MakeIntCol(name);
}
+ shared_ptr>> StatHCStringArray(string_view name) final {
+ return MakeArrayStrCol(name);
+ }
shared_ptr> StatTimestamp(string_view name) final {
return MakeDateTimeCol(name);
@@ -239,6 +243,22 @@ class OTelExporter : public StatsExporter {
string name_;
};
+ class ArrayStrColumn : public Column> {
+ public:
+ ArrayStrColumn(OTelExporter* e, string_view n) : exp_(e), name_(n) {}
+ void Append(const std::vector& v) final {
+ if (exp_->current_record_ == nullptr) {
+ return;
+ }
+ psch::SetStringArrayAttr(AddAttr(exp_->current_record_), name_, v);
+ exp_->chunk_bytes_ += psch::EstimateStringArrayAttrBytes(name_, v);
+ }
+
+ private:
+ OTelExporter* exp_;
+ string name_;
+ };
+
class StrColumn : public Column {
public:
StrColumn(OTelExporter* e, string_view n) : exp_(e), name_(n) {}
@@ -301,6 +321,10 @@ class OTelExporter : public StatsExporter {
return std::make_shared(this, name);
}
+ shared_ptr>> MakeArrayStrCol(string_view name) {
+ return std::make_shared(this, name);
+ }
+
shared_ptr> MakeStringCol(string_view name) {
return std::make_shared(this, name);
}
diff --git a/src/export/otel_string_array_attr.h b/src/export/otel_string_array_attr.h
new file mode 100644
index 0000000..4508e59
--- /dev/null
+++ b/src/export/otel_string_array_attr.h
@@ -0,0 +1,41 @@
+// Builds an array-valued OTLP attribute for any HC string-array stat.
+#ifndef PG_STAT_CH_SRC_EXPORT_OTEL_STRING_ARRAY_ATTR_H_
+#define PG_STAT_CH_SRC_EXPORT_OTEL_STRING_ARRAY_ATTR_H_
+
+#include
+
+#include
+#include
+#include
+
+namespace psch {
+
+// AnyValue.array_value is a plain repeated AnyValue -- every element gets
+// its own string_value, same as a top-level string attribute would.
+inline void SetStringArrayAttr(opentelemetry::proto::common::v1::KeyValue* kv,
+ std::string_view key,
+ const std::vector& values) {
+ kv->set_key(key.data(), key.size());
+ auto* arr = kv->mutable_value()->mutable_array_value();
+ for (const auto& value : values) {
+ arr->add_values()->set_string_value(value.data(), value.size());
+ }
+}
+
+// Used to decide when a chunk is full. Unlike a scalar attribute, each
+// array element is its own nested AnyValue, with its own protobuf framing
+// on top of the string bytes -- kPerElementOverheadBytes covers that.
+inline size_t EstimateStringArrayAttrBytes(std::string_view key,
+ const std::vector& values) {
+ constexpr size_t kAttrOverheadBytes = 24;
+ constexpr size_t kPerElementOverheadBytes = 4;
+ size_t total = kAttrOverheadBytes + key.size();
+ for (const auto& value : values) {
+ total += value.size() + kPerElementOverheadBytes;
+ }
+ return total;
+}
+
+} // namespace psch
+
+#endif // PG_STAT_CH_SRC_EXPORT_OTEL_STRING_ARRAY_ATTR_H_
diff --git a/src/export/relations_decode.h b/src/export/relations_decode.h
new file mode 100644
index 0000000..fbdf887
--- /dev/null
+++ b/src/export/relations_decode.h
@@ -0,0 +1,75 @@
+// Pure C++, no PostgreSQL headers: decodes the relations blob built by
+// CollectRelations in relations_collect.c.
+#ifndef PG_STAT_CH_SRC_EXPORT_RELATIONS_DECODE_H_
+#define PG_STAT_CH_SRC_EXPORT_RELATIONS_DECODE_H_
+
+#include
+#include
+#include
+
+#include "hooks/relations_budget.h"
+
+// Decoded form of the relations blob built by CollectRelations in relations_collect.c:
+// [truncated:u8][count:u8]{[ns_len:u8][ns][name_len:u8][name][relkind:u8]}*count
+struct DecodedRelations {
+ bool truncated = false;
+ std::vector namespaces;
+ std::vector names;
+ std::vector kinds; // one-byte spans, e.g. "r", "v", "m"
+};
+
+// Decodes buf[0..len). Malformed input (an entry's declared length running
+// past the end of buf) stops decoding at that point rather than reading out
+// of bounds; entries decoded so far are still returned.
+inline DecodedRelations DecodeRelations(const char* buf, uint16_t len) {
+ DecodedRelations out;
+ if (len == 0) {
+ return out;
+ }
+ // PSCH_RELATIONS_OOM_LEN: blob lost to DSA OOM, not zero relations.
+ if (len == PSCH_RELATIONS_OOM_LEN) {
+ out.truncated = true;
+ return out;
+ }
+ if (len < PSCH_RELATIONS_HEADER_LEN) {
+ return out;
+ }
+
+ out.truncated = buf[0] != 0;
+ auto count = static_cast(buf[1]);
+ size_t pos = 2;
+ const size_t end = len;
+
+ // Reads a [len:u8][bytes] field at pos, advancing it past the field.
+ // Returns false (leaving *field untouched) if len or bytes run past end.
+ auto read_field = [&](std::string_view* field) {
+ if (pos + 1 > end) {
+ return false;
+ }
+ auto field_len = static_cast(buf[pos]);
+ if (pos + 1 + field_len > end) {
+ return false;
+ }
+ *field = std::string_view(buf + pos + 1, field_len);
+ pos += 1 + field_len;
+ return true;
+ };
+
+ for (uint8_t i = 0; i < count; i++) {
+ std::string_view ns;
+ std::string_view name;
+ if (!read_field(&ns) || !read_field(&name) || pos + 1 > end) {
+ break;
+ }
+ std::string_view kind(buf + pos, 1);
+ pos += 1;
+
+ out.namespaces.push_back(ns);
+ out.names.push_back(name);
+ out.kinds.push_back(kind);
+ }
+
+ return out;
+}
+
+#endif // PG_STAT_CH_SRC_EXPORT_RELATIONS_DECODE_H_
diff --git a/src/export/stats_exporter.cc b/src/export/stats_exporter.cc
index 4710d9a..7352e7c 100644
--- a/src/export/stats_exporter.cc
+++ b/src/export/stats_exporter.cc
@@ -19,6 +19,7 @@ extern "C" {
#include "export/exporter_interface.h"
#include "export/otel_arrow_exporter.h"
#include "export/otel_exporter.h"
+#include "export/relations_decode.h"
#include "export/sqlcommenter_parse.h"
#include "export/stats_exporter.h"
#include "queue/event.h"
@@ -240,6 +241,16 @@ void ExportEventStatsInternal(PschEvent* event, int max_events, StatsExporter* e
// Only declared when label tracking is on, so inserts keep the old column
// set until the destination schema has `labels`.
auto col_labels = psch_track_labels ? exporter->StatHCString("labels") : nullptr;
+ // Only declared when relations tracking is on, so inserts keep the old
+ // column set until the destination schema has these columns.
+ auto col_relation_namespaces =
+ psch_relations_enabled ? exporter->StatHCStringArray("relation_namespaces") : nullptr;
+ auto col_relation_names =
+ psch_relations_enabled ? exporter->StatHCStringArray("relation_names") : nullptr;
+ auto col_relation_kinds =
+ psch_relations_enabled ? exporter->StatHCStringArray("relation_kinds") : nullptr;
+ auto col_relations_truncated =
+ psch_relations_enabled ? exporter->StatLCUInt8("relations_truncated") : nullptr;
auto col_shared_blks_hit = exporter->StatHCInt64("shared_blks_hit");
auto col_shared_blks_read = exporter->StatHCInt64("shared_blks_read");
@@ -305,6 +316,16 @@ void ExportEventStatsInternal(PschEvent* event, int max_events, StatsExporter* e
col_labels->Append(QueryLabelsJson(query_text, PSCH_MAX_QUERY_LEN));
}
+ if (col_relation_namespaces != nullptr) {
+ auto rlen = ClampFieldLen(ev.relations_len, static_cast(PSCH_MAX_RELATIONS_LEN),
+ "relations_len");
+ auto decoded = DecodeRelations(ev.relations, rlen);
+ col_relation_namespaces->Append(decoded.namespaces);
+ col_relation_names->Append(decoded.names);
+ col_relation_kinds->Append(decoded.kinds);
+ col_relations_truncated->Append(decoded.truncated ? 1 : 0);
+ }
+
col_shared_blks_hit->Append(ev.shared_blks_hit);
col_shared_blks_read->Append(ev.shared_blks_read);
col_shared_blks_dirtied->Append(ev.shared_blks_dirtied);
diff --git a/src/hooks/hooks.c b/src/hooks/hooks.c
index e3c39ad..48f8d60 100644
--- a/src/hooks/hooks.c
+++ b/src/hooks/hooks.c
@@ -12,6 +12,7 @@
#include "executor/executor.h"
#include "executor/instrument.h"
#include "jit/jit.h"
+#include "lib/stringinfo.h"
#include "libpq/libpq-be.h"
#include "miscadmin.h"
#include "nodes/queryjumble.h"
@@ -21,7 +22,6 @@
#include "tcop/utility.h"
#include "utils/elog.h"
#include "utils/guc.h"
-#include "utils/lsyscache.h"
#include "utils/timestamp.h"
#include "compat.h"
@@ -29,6 +29,7 @@
#include "hooks/hooks.h"
#include "hooks/query_normalize.h"
#include "hooks/query_normalize_state.h"
+#include "hooks/relations_collect.h"
#include "hooks/string_utils.h"
#include "queue/event.h"
#include "queue/shmem.h"
@@ -304,6 +305,29 @@ static void CopyQueryText(PschEvent* event, uint64 query_id) {
sizeof(event->query), &event->query_len);
}
+// Relations are collected only here, at ExecutorEnd, so only queries that run
+// to completion carry them. A query that errors out (including failures before
+// execution starts, e.g. permission denied) never reaches ExecutorEnd, and its
+// error event (built from ErrorData in CaptureLogEvent) has relations_len = 0.
+// That reads as empty arrays with relations_truncated = false, so an empty list
+// on an error event means "not recorded", not "touched nothing".
+static void CopyRelations(PschEvent* event, QueryDesc* query_desc) {
+ if (!psch_relations_enabled) {
+ event->relations_len = 0;
+ return;
+ }
+
+ MemoryContext oldcxt = MemoryContextSwitchTo(query_desc->estate->es_query_cxt);
+ StringInfoData buf;
+ initStringInfo(&buf);
+ CollectRelations(&buf, query_desc->plannedstmt->rtable, query_desc->plannedstmt->appendRelations);
+ Assert(buf.len <= (int)sizeof(event->relations));
+ event->relations_len = (uint16)Min(buf.len, (int)sizeof(event->relations));
+ memcpy(event->relations, buf.data, event->relations_len);
+ pfree(buf.data);
+ MemoryContextSwitchTo(oldcxt);
+}
+
// Resolve database and user names, using the session cache when available.
// Falls back to catalog lookups if cache hasn't been initialized yet (e.g.,
// emit_log_hook fires before the first executor hook).
@@ -392,6 +416,7 @@ static void BuildEventFromQueryDesc(QueryDesc* query_desc, PschEvent* event, int
CopyParallelWorkerInfo(event, query_desc);
CopyClientContext(event);
CopyQueryText(event, query_desc->plannedstmt->queryId);
+ CopyRelations(event, query_desc);
}
// post_parse_analyze_hook — decide query text at parse time.
diff --git a/src/hooks/relations_collect.c b/src/hooks/relations_collect.c
new file mode 100644
index 0000000..f02cda8
--- /dev/null
+++ b/src/hooks/relations_collect.c
@@ -0,0 +1,148 @@
+#include "postgres.h"
+
+#include "catalog/pg_class.h"
+#include "common/hashfn.h"
+#include "nodes/pathnodes.h"
+#include "parser/parsetree.h"
+#include "utils/lsyscache.h"
+
+#include "config/guc.h"
+#include "hooks/relations_budget.h"
+#include "hooks/relations_collect.h"
+
+// Oid set for CollectRelations' dedup below. Created fresh per call in the
+// caller's es_query_cxt. Planner-generated partition/inheritance children are
+// skipped before they reach this set, so it stays small: it is bounded by the
+// byte budget, not by the range-table length.
+typedef struct PschRelidSeenEntry {
+ Oid relid;
+ char status;
+} PschRelidSeenEntry;
+
+#define SH_PREFIX psch_relid_seen
+#define SH_ELEMENT_TYPE PschRelidSeenEntry
+#define SH_KEY_TYPE Oid
+#define SH_KEY relid
+#define SH_HASH_KEY(tb, key) murmurhash32((uint32)(key))
+#define SH_EQUAL(tb, a, b) ((a) == (b))
+#define SH_SCOPE static inline
+#define SH_DECLARE
+#define SH_DEFINE
+#include "lib/simplehash.h"
+
+// Fills parent_of_rti[child's rti] = parent's rti for every planner-generated
+// partition/inheritance child; everything else stays 0 (the palloc0 default).
+// Indexed by range-table index (1..nrt), so parent_of_rti must have nrt+1
+// elements.
+static void BuildChildMap(Index* parent_of_rti, int nrt, List* append_rel_infos) {
+ (void)nrt; // Only used by the Assert below, which compiles out in release builds.
+ ListCell* alc;
+ foreach (alc, append_rel_infos) {
+ AppendRelInfo* appinfo = (AppendRelInfo*)lfirst(alc);
+ Assert(appinfo->child_relid >= 1 && (int)appinfo->child_relid <= nrt);
+ parent_of_rti[appinfo->child_relid] = appinfo->parent_relid;
+ }
+}
+
+// True if the range-table entry at rti should be considered for reporting.
+//
+// Plain tables, plus view-expansion artifacts: the rewriter turns a
+// referenced view into an RTE_SUBQUERY wrapping its definition, but stamps
+// relkind='v' on that entry so it's still identifiable as a view.
+// RTE_RELATION alone already covers every other relkind (matview,
+// partitioned, foreign table) uniformly -- unaffected by that work.
+//
+// Partition and inheritance children are collapsed into their parent: the
+// parent is reported, planner-generated children are not. Collapsing happens
+// before deduplication, so a later explicit reference to the same partition
+// is still reported.
+static bool ShouldReportRte(RangeTblEntry* rte, List* rt, Index* parent_of_rti, int rti) {
+ if (rte->rtekind != RTE_RELATION && rte->relkind != RELKIND_VIEW) {
+ return false;
+ }
+
+ Index parent_rti = parent_of_rti[rti];
+ if (parent_rti != 0 && rt_fetch(parent_rti, rt)->rtekind == RTE_RELATION) {
+ return false;
+ }
+
+ return true;
+}
+
+// Appends one [ns_len][ns][name_len][name][relkind] entry to buf. Returns
+// false (buf unchanged) if the entry would exceed psch_relations_max_len,
+// signaling the caller to stop and flag truncation, same as query text does.
+static bool AppendRelationEntry(StringInfo buf, const char* namespace_name,
+ const char* relation_name, char relkind) {
+ // NAMEDATALEN-1 (63) max per Postgres identifier rules, so these always
+ // fit in a uint8 length prefix.
+ size_t ns_len = strlen(namespace_name);
+ size_t name_len = strlen(relation_name);
+ Assert(ns_len < NAMEDATALEN);
+ Assert(name_len < NAMEDATALEN);
+
+ // No separator byte to account for -- every entry is self-delimiting.
+ int entry_len = (int)(1 + ns_len + 1 + name_len + 1);
+ if (buf->len + entry_len > psch_relations_max_len) {
+ return false;
+ }
+
+ appendStringInfoChar(buf, (char)ns_len);
+ appendBinaryStringInfo(buf, namespace_name, (int)ns_len);
+ appendStringInfoChar(buf, (char)name_len);
+ appendBinaryStringInfo(buf, relation_name, (int)name_len);
+ appendStringInfoChar(buf, (char)relkind);
+ return true;
+}
+
+void CollectRelations(StringInfo buf, List* rt, List* append_rel_infos) {
+ int nrt = list_length(rt);
+ // Starting size only: simplehash grows on demand, and the byte budget caps
+ // this set at roughly 200 relations, so don't scale it with the range table.
+ psch_relid_seen_hash* seen = psch_relid_seen_create(CurrentMemoryContext, 64, NULL);
+ uint8 count = 0;
+ bool truncated = false;
+ int rti = 0;
+ ListCell* lc;
+
+ // Defense in depth -- the GUC's own min bound (guc.c) already enforces this.
+ Assert(psch_relations_max_len >= PSCH_RELATIONS_HEADER_LEN);
+
+ Index* parent_of_rti = palloc0(sizeof(Index) * (nrt + 1));
+ BuildChildMap(parent_of_rti, nrt, append_rel_infos);
+
+ // Reserve the header now; patched with real values once known.
+ appendStringInfoChar(buf, 0);
+ appendStringInfoChar(buf, 0);
+
+ foreach (lc, rt) {
+ rti++;
+ RangeTblEntry* rte = (RangeTblEntry*)lfirst(lc);
+
+ if (!ShouldReportRte(rte, rt, parent_of_rti, rti)) {
+ continue;
+ }
+
+ bool found;
+ psch_relid_seen_insert(seen, rte->relid, &found);
+ if (found) {
+ continue;
+ }
+
+ const char* namespace_name = get_namespace_name(get_rel_namespace(rte->relid));
+ const char* relation_name = get_rel_name(rte->relid);
+ if (namespace_name == NULL || relation_name == NULL) {
+ continue; // Relation dropped concurrently; skip rather than crash.
+ }
+
+ if (!AppendRelationEntry(buf, namespace_name, relation_name, (char)rte->relkind)) {
+ truncated = true;
+ break;
+ }
+ count++;
+ }
+
+ buf->data[0] = truncated ? 1 : 0;
+ buf->data[1] = (char)count;
+ psch_relid_seen_destroy(seen);
+}
diff --git a/src/hooks/relations_collect.h b/src/hooks/relations_collect.h
new file mode 100644
index 0000000..498db7b
--- /dev/null
+++ b/src/hooks/relations_collect.h
@@ -0,0 +1,23 @@
+// Builds the relations blob reported per query: the tables/views/matviews
+// the executor touched, deduplicated, with partition and inheritance
+// children collapsed into their parent. Layout:
+// [truncated:u8][count:u8]{[ns_len:u8][ns][name_len:u8][name][relkind:u8]}*count.
+#ifndef PG_STAT_CH_SRC_HOOKS_RELATIONS_COLLECT_H_
+#define PG_STAT_CH_SRC_HOOKS_RELATIONS_COLLECT_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "postgres.h"
+
+#include "lib/stringinfo.h"
+#include "nodes/pg_list.h"
+
+void CollectRelations(StringInfo buf, List* rt, List* append_rel_infos);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // PG_STAT_CH_SRC_HOOKS_RELATIONS_COLLECT_H_
diff --git a/src/queue/event.h b/src/queue/event.h
index 4f680be..c527095 100644
--- a/src/queue/event.h
+++ b/src/queue/event.h
@@ -16,10 +16,8 @@
// 4. FAST COPY: memcpy() of 2KB is ~20ns on modern CPUs with cache. Variable-length
// would require copying arbitrary amounts of data under lock.
//
-// ALTERNATIVE CONSIDERED: pg_stat_monitor uses DSA (Dynamic Shared Area) for
-// variable-length query text. This allows unlimited query length but adds complexity
-// with DSA allocation, OOM handling, and pointer management. For telemetry/metrics,
-// 2KB query text is sufficient - we don't need full query text for aggregation.
+// Each cap below also bounds how much of PschRingEntry's shared DSA pool one
+// query can consume, so no single query can starve others.
#ifndef PG_STAT_CH_SRC_QUEUE_EVENT_H_
#define PG_STAT_CH_SRC_QUEUE_EVENT_H_
@@ -45,6 +43,11 @@ extern "C" {
// Maximum error message length (truncated if longer)
#define PSCH_MAX_ERR_MSG_LEN 2048
+// Maximum length of the relations blob (layout in relations_collect.c,
+// CollectRelations), truncated on overflow like query text -- truncation is
+// self-flagged.
+#define PSCH_MAX_RELATIONS_LEN 1024
+
// Maximum application name length
#define PSCH_MAX_APP_NAME_LEN (NAMEDATALEN - 1)
@@ -163,11 +166,19 @@ typedef struct PschEvent {
char client_addr[46]; // Client IP address (INET6_ADDRSTRLEN=46)
uint8 client_addr_len; // Actual length
uint16 query_len; // Actual length of query text
+ uint16 relations_len; // Actual length of relations blob (0 for utility statements)
+ // Keeps the fixed prefix's tail 8-byte aligned so it stays byte-identical
+ // to PschRingEntry's (dsa_pointer needs 8-byte alignment; char[] doesn't).
+ uint8 _padding4[6];
// Variable-length text fields — kept last so the fixed-size prefix can be
// block-copied between PschEvent and PschRingEntry with a single memcpy.
+ // All copied as raw bytes with no encoding conversion -- assumes UTF-8.
+ // A real fix needs pg_do_encoding_conversion() per field plus a test
+ // matrix across non-UTF-8/ICU locales; left as a documented gap for now.
char err_message[PSCH_MAX_ERR_MSG_LEN]; // Error message text (truncated if necessary)
char query[PSCH_MAX_QUERY_LEN]; // Query text, unterminated, see query_len
+ char relations[PSCH_MAX_RELATIONS_LEN]; // See CollectRelations in hooks.c for layout.
} PschEvent;
// Ensure the struct has expected size characteristics
diff --git a/src/queue/ring_entry.h b/src/queue/ring_entry.h
index faf1c4c..72590fd 100644
--- a/src/queue/ring_entry.h
+++ b/src/queue/ring_entry.h
@@ -1,11 +1,11 @@
// Compact ring buffer entry for shared memory storage.
//
// PschRingEntry mirrors PschEvent's numeric fields identically but replaces
-// the two large inline char arrays (query[2048] and err_message[2048]) with
-// dsa_pointer values that reference variable-length strings allocated in a
-// DSA (Dynamic Shared Memory Area).
+// the large inline char arrays (query[2048], err_message[2048], and
+// relations[1024]) with dsa_pointer values that reference variable-length
+// strings allocated in a DSA (Dynamic Shared Memory Area).
//
-// This shrinks each ring buffer slot from ~4.5KB to ~500 bytes while keeping
+// This shrinks each ring buffer slot from ~5KB to ~510 bytes while keeping
// the public API type (PschEvent) unchanged. The conversion happens
// transparently inside PschEnqueueEvent / PschDequeueEvent.
#ifndef PG_STAT_CH_SRC_QUEUE_RING_ENTRY_H_
@@ -98,10 +98,13 @@ typedef struct PschRingEntry {
char client_addr[46];
uint8 client_addr_len;
uint16 query_len;
+ uint16 relations_len;
+ uint8 _padding4[6]; // Matches PschEvent's padding; see event.h for why.
- // --- DSA pointers replace the two trailing char arrays in PschEvent ---
+ // --- DSA pointers replace the three trailing char arrays in PschEvent ---
dsa_pointer err_message_dsa; // was: char err_message[PSCH_MAX_ERR_MSG_LEN]
dsa_pointer query_dsa; // was: char query[PSCH_MAX_QUERY_LEN]
+ dsa_pointer relations_dsa; // was: char relations[PSCH_MAX_RELATIONS_LEN]
} PschRingEntry;
// Verify that fixed prefix of PschRingEntry has same binary layout as
@@ -127,8 +130,10 @@ StaticAssertDecl(offsetof(PschEvent, application_name) == offsetof(PschRingEntry
"application_name offset mismatch");
StaticAssertDecl(offsetof(PschEvent, query_len) == offsetof(PschRingEntry, query_len),
"query_len offset mismatch");
-// Fields after query_len diverge: PschEvent has char arrays, PschRingEntry
-// has dsa_pointers. Intentional, fixed prefix up to query_len is
+StaticAssertDecl(offsetof(PschEvent, relations_len) == offsetof(PschRingEntry, relations_len),
+ "relations_len offset mismatch");
+// Fields after relations_len diverge: PschEvent has char arrays, PschRingEntry
+// has dsa_pointers. Intentional, fixed prefix up to relations_len is
// block-copied with single memcpy.
StaticAssertDecl(offsetof(PschEvent, err_message) == offsetof(PschRingEntry, err_message_dsa),
"err_message/err_message_dsa start offset mismatch");
diff --git a/src/queue/shmem.c b/src/queue/shmem.c
index 92b9a86..95ca5b8 100644
--- a/src/queue/shmem.c
+++ b/src/queue/shmem.c
@@ -40,6 +40,7 @@
#include "config/guc.h"
#include "hooks/hooks.h"
+#include "hooks/relations_budget.h"
#include "queue/local_batch.h"
#include "queue/psch_dsa.h"
#include "queue/query_intern.h"
@@ -112,15 +113,23 @@ static bool TryEnqueueLocked(const PschEvent* event, uint32 capacity) {
// client_addr, lengths — everything before the variable-length data).
memcpy(slot, event, kFixedPrefixSize);
- // 2. Allocate DSA for err_message and query text. Store pointers in slot
- // only right before head advances, so slots outside [tail, head) never
- // hold references
+ // 2. Allocate DSA for err_message, relations, and query text. Store
+ // pointers in slot only right before head advances, so slots outside
+ // [tail, head) never hold references
dsa_pointer err_message_dsa =
PschDsaAllocString(event->err_message, event->err_message_len, PSCH_MAX_ERR_MSG_LEN);
if (event->err_message_len > 0 && !DsaPointerIsValid(err_message_dsa)) {
slot->err_message_len = 0; // Lost string on OOM — numeric data preserved
}
+ // Relations: plain per-event DSA allocation, same as err_message (not
+ // interned, unlike the query text below).
+ dsa_pointer relations_dsa =
+ PschDsaAllocString(event->relations, event->relations_len, PSCH_MAX_RELATIONS_LEN);
+ if (event->relations_len > 0 && !DsaPointerIsValid(relations_dsa)) {
+ slot->relations_len = PSCH_RELATIONS_OOM_LEN;
+ }
+
// Query text goes through the shared interner so repeated identical
// normalized queries share a single DSA-allocated body. See query_intern.h
// for the design rationale. On miss + DSA OOM, miss + hash-full, or hash
@@ -139,6 +148,7 @@ static bool TryEnqueueLocked(const PschEvent* event, uint32 capacity) {
}
slot->err_message_dsa = err_message_dsa;
+ slot->relations_dsa = relations_dsa;
slot->query_dsa = query_dsa;
// CRITICAL: Memory barrier ensures the event data is written to shared memory
@@ -174,14 +184,14 @@ static Size PschSharedBlockSize(void) {
Size PschShmemSize(void) {
// Total shmem requested from the postmaster: the shared block plus the
- // interner HTAB (which ShmemInitHash carves out of the same pool).
+ // query-text interner HTAB (carved from the same pool by ShmemInitHash).
return add_size(PschSharedBlockSize(), PschQueryInternShmemSize());
}
static void RequestSharedResources(void) {
RequestAddinShmemSpace(PschShmemSize());
- // 1 main queue lock + N partition locks for the query-text interner, all
- // in the single "pg_stat_ch" named tranche so we read them as a contiguous
+ // 1 main queue lock + N query-text interner partition locks, all in the
+ // single "pg_stat_ch" named tranche so we read them as a contiguous
// LWLockPadded[] from GetNamedLWLockTranche().
RequestNamedLWLockTranche("pg_stat_ch", 1 + PschQueryInternLockCount());
}
@@ -257,7 +267,8 @@ static void PschShmemStartupHook(void) {
InitializeSharedState();
}
- // Initialize (or attach to) the query intern HTAB. All backends get same handle.
+ // Initialize (or attach to) the query intern HTAB. All backends get the
+ // same handle.
LWLockPadded* lwlocks = GetNamedLWLockTranche("pg_stat_ch");
PschQueryInternShmemInit(&lwlocks[1]);
@@ -443,6 +454,13 @@ bool PschDequeueEvent(PschEvent* event) {
PschDsaResolveString(err_message_dsa, event->err_message_len, event->err_message,
PSCH_MAX_ERR_MSG_LEN, &event->err_message_len);
+ dsa_pointer relations_dsa = slot->relations_dsa;
+ slot->relations_dsa = InvalidDsaPointer;
+ if (event->relations_len != PSCH_RELATIONS_OOM_LEN) {
+ PschDsaResolveString(relations_dsa, event->relations_len, event->relations,
+ PSCH_MAX_RELATIONS_LEN, &event->relations_len);
+ }
+
dsa_pointer query_dsa = slot->query_dsa;
slot->query_dsa = InvalidDsaPointer;
PschQueryInternResolveAndRelease(query_dsa, event->query_len, event->query, PSCH_MAX_QUERY_LEN,
diff --git a/t/036_unified_arrow_e2e.pl b/t/036_unified_arrow_e2e.pl
index c0e9cf8..a26e0c7 100644
--- a/t/036_unified_arrow_e2e.pl
+++ b/t/036_unified_arrow_e2e.pl
@@ -69,6 +69,7 @@
pg_stat_ch.otel_endpoint = 'localhost:14317'
pg_stat_ch.otel_arrow_passthrough = on
pg_stat_ch.use_unified_arrow_exporter = on
+pg_stat_ch.relations_enabled = on
pg_stat_ch.debug_arrow_dump_dir = '$dump_dir'
pg_stat_ch.hostname = 'unified-arrow-e2e-host'
pg_stat_ch.extra_attributes = 'instance_ubid:test-instance;server_role:primary;region:test-region;cell:test-cell;read_replica_type:none'
@@ -121,14 +122,11 @@
'http://localhost:18123/?query=' .
'INSERT%20INTO%20pg_stat_ch.events_raw%20FORMAT%20ArrowStream';
-my $total_posted = 0;
-for my $f (@ipc_files) {
+# --fail-with-body makes HTTP 4xx/5xx from CH surface as a non-zero curl exit
+# code (default curl returns 0 on any completed transfer regardless of status).
+sub post_ipc_file {
+ my ($f) = @_;
my $err_file = "$f.err";
- # --fail-with-body makes HTTP 4xx/5xx responses from CH surface as a
- # non-zero curl exit code (default curl returns 0 on any completed
- # HTTP transfer regardless of status). The subsequent SELECT count()
- # assertion would catch ingestion failure too, but failing here gives
- # a sharper error message at the point the bug actually happened.
my $rc = system("curl -sS --fail-with-body -X POST " .
"-H 'Content-Type: application/octet-stream' " .
"--data-binary \@$f '$insert_url' 2>$err_file >/dev/null");
@@ -137,6 +135,12 @@
} : '';
is($rc, 0, basename($f) . " accepted by CH ArrowStream parser" .
($stderr ? " (stderr: $stderr)" : ""));
+ return $rc == 0;
+}
+
+my $total_posted = 0;
+for my $f (@ipc_files) {
+ post_ipc_file($f);
++$total_posted;
}
cmp_ok($total_posted, '>=', 1, "Posted at least one IPC file to CH");
@@ -186,5 +190,47 @@
is($envelope, "test-instance\tprimary\ttest-region\ttest-cell\tnone",
"envelope columns populated from extra_attributes");
+# A second, separately-flushed batch: checks the Arrow list-builder resets
+# across flushes. Polls ClickHouse for the marker rather than local file state,
+# since the bgworker's dump is async and not pinned to one file per flush.
+my %posted = map { $_ => 1 } @ipc_files;
+
+$node->safe_psql('postgres', 'CREATE TABLE arrow_rel_t1 (id int)');
+$node->safe_psql('postgres', 'CREATE TABLE arrow_rel_t2 (id int)');
+$node->safe_psql('postgres',
+ 'SELECT arrow_rel_t1.id FROM arrow_rel_t1 JOIN arrow_rel_t2 ' .
+ 'ON arrow_rel_t1.id = arrow_rel_t2.id');
+$node->safe_psql('postgres', 'SELECT 99 AS arrow_rel_zero_marker');
+$node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+my $rel_two = '';
+my $rel_zero = '';
+$deadline = time() + 10;
+while (time() < $deadline) {
+ for my $f (glob("$dump_dir/*.ipc")) {
+ next if $posted{$f};
+ $posted{$f} = 1;
+ post_ipc_file($f);
+ }
+ $rel_two ||= psch_query_clickhouse(
+ "SELECT relation_names, relation_kinds, relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE '%FROM arrow_rel_t1 JOIN arrow_rel_t2%' ORDER BY ts DESC LIMIT 1 FORMAT TSV");
+ chomp $rel_two;
+ $rel_zero ||= psch_query_clickhouse(
+ "SELECT relation_names, relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE '%arrow_rel_zero_marker%' ORDER BY ts DESC LIMIT 1 FORMAT TSV");
+ chomp $rel_zero;
+ last if $rel_two ne '' && $rel_zero ne '';
+ select(undef, undef, undef, 0.2);
+}
+
+like($rel_two, qr/'arrow_rel_t1'/, "two-relation query exported relation_names (got: $rel_two)");
+like($rel_two, qr/'arrow_rel_t2'/, "two-relation query exported both tables (got: $rel_two)");
+like($rel_two, qr/'r','r'/, "relation_kinds has two ordinary tables (got: $rel_two)");
+like($rel_two, qr/false$/, "two-relation query not truncated (got: $rel_two)");
+
+is($rel_zero, "[]\tfalse",
+ "zero-relation query in the next batch shows an empty array, not leftover data");
+
$node->stop();
done_testing();
diff --git a/t/039_relations_export.pl b/t/039_relations_export.pl
new file mode 100644
index 0000000..381a76e
--- /dev/null
+++ b/t/039_relations_export.pl
@@ -0,0 +1,910 @@
+#!/usr/bin/env perl
+# Relations export: encoding correctness (identifiers, relkinds, truncation)
+# and hook robustness under nested invocations and schema changes.
+# Prerequisites: ClickHouse container must be running (docker compose -f
+# docker/docker-compose.test.yml up -d); postgres_fdw gates the foreign-table case.
+
+use strict;
+use warnings;
+use lib 't';
+
+use PostgreSQL::Test::Cluster;
+use PostgreSQL::Test::Utils;
+use Test::More;
+
+use psch;
+
+if (!psch_clickhouse_available()) {
+ plan skip_all => 'Docker not available, skipping ClickHouse tests';
+}
+
+my $ch_check = `curl -s 'http://localhost:18123/' --data 'SELECT 1' 2>/dev/null`;
+if ($ch_check !~ /^1/) {
+ plan skip_all => 'ClickHouse container not running. Start with: docker compose -f docker/docker-compose.test.yml up -d';
+}
+
+psch_query_clickhouse("TRUNCATE TABLE IF EXISTS pg_stat_ch.events_raw");
+
+my $node = psch_init_node_with_clickhouse('relations_export',
+ flush_interval_ms => 100,
+ batch_max => 100
+);
+
+# relations_enabled is off by default and PGC_POSTMASTER (restart to change);
+# this file's subtests assume it's on except the one that specifically tests
+# the off/unmigrated case.
+$node->append_conf('postgresql.conf', 'pg_stat_ch.relations_enabled = on');
+$node->restart();
+
+$node->safe_psql('postgres', 'CREATE TABLE foo1(a int)');
+$node->safe_psql('postgres', 'CREATE TABLE foo2(b int)');
+$node->safe_psql('postgres', 'CREATE SCHEMA sch1');
+$node->safe_psql('postgres', 'CREATE TABLE sch1.foo3(c int)');
+$node->safe_psql('postgres', 'CREATE VIEW v1 AS SELECT * FROM foo1');
+
+subtest 'plain table' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM foo1');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM foo1%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'foo1'/, "single table appears as foo1 (got: $names)");
+};
+
+subtest 'two plain tables' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM foo1, foo2');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM foo1, foo2%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'foo1'/, "includes foo1 (got: $names)");
+ like($names, qr/'foo2'/, "includes foo2 (got: $names)");
+};
+
+subtest 'schema-qualified table' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM sch1.foo3, foo1');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $namespaces = psch_wait_for_clickhouse_query(
+ "SELECT relation_namespaces FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM sch1.foo3%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ my $names = psch_query_clickhouse(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM sch1.foo3%' LIMIT 1"
+ );
+ like($namespaces, qr/'sch1'/, "sch1 namespace present (got: $namespaces)");
+ like($names, qr/'foo3'/, "foo3 present (got: $names)");
+ like($names, qr/'foo1'/, "foo1 also present (got: $names)");
+};
+
+subtest 'self-join deduplicates' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM foo1 AS a, foo1 AS b');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM foo1 AS a%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ my $count = () = $names =~ /'foo1'/g;
+ is($count, 1, "foo1 listed once, not twice (got: $names)");
+};
+
+subtest 'view reports relkind v' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM v1');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM v1%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ my $kinds = psch_query_clickhouse(
+ "SELECT relation_kinds FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM v1%' LIMIT 1"
+ );
+ like($names, qr/'v1'/, "v1 present (got: $names)");
+ like($kinds, qr/'v'/, "v1 reports relkind 'v' (got: $kinds)");
+ like($names, qr/'foo1'/, "underlying base table also present (got: $names)");
+};
+
+subtest 'UNION ALL view reports both branches alongside the view' => sub {
+ $node->safe_psql('postgres', 'CREATE TABLE ua1(a int)');
+ $node->safe_psql('postgres', 'CREATE TABLE ua2(a int)');
+ $node->safe_psql('postgres',
+ 'CREATE VIEW v_union_all AS SELECT * FROM ua1 UNION ALL SELECT * FROM ua2');
+
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM v_union_all');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM v_union_all%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'v_union_all'/, "view itself present (got: $names)");
+ like($names, qr/'ua1'/, "first UNION ALL branch's table present (got: $names)");
+ like($names, qr/'ua2'/, "second UNION ALL branch's table present (got: $names)");
+};
+
+subtest 'truncation over budget is flagged and does not error' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # SET/RESET are session-local; safe_psql opens a fresh connection per
+ # call, so SET and the query it affects must run in the same call.
+ $node->safe_psql('postgres',
+ 'SET pg_stat_ch.relations_max_len = 8; ' .
+ 'SELECT * FROM foo1, foo2, sch1.foo3; ' .
+ 'RESET pg_stat_ch.relations_max_len');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $stats = psch_get_stats($node);
+ cmp_ok($stats->{dsa_oom}, '==', 0, 'no DSA OOM from the tiny budget');
+
+ my $ch_count = psch_wait_for_clickhouse_query(
+ "SELECT count() FROM pg_stat_ch.events_raw",
+ sub { $_[0] >= 1 },
+ 10
+ );
+ cmp_ok($ch_count, '>=', 1, 'event still exported despite truncation');
+
+ my $truncated = psch_wait_for_clickhouse_query(
+ "SELECT relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1, foo2, sch1.foo3%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ is($truncated, 'true', "truncation is explicitly flagged (got: $truncated)");
+
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ $node->safe_psql('postgres', 'SELECT * FROM foo1, foo2, sch1.foo3');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $not_truncated = psch_wait_for_clickhouse_query(
+ "SELECT relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1, foo2, sch1.foo3%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ is($not_truncated, 'false', "complete list is explicitly not flagged (got: $not_truncated)");
+};
+
+subtest 'minimum budget (header-only) produces an empty, truncated list' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # 2 is the new GUC floor -- room for the header, none for any entry.
+ $node->safe_psql('postgres',
+ 'SET pg_stat_ch.relations_max_len = 2; ' .
+ 'SELECT * FROM foo1; ' .
+ 'RESET pg_stat_ch.relations_max_len');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $stats = psch_get_stats($node);
+ cmp_ok($stats->{dsa_oom}, '==', 0, 'no DSA OOM at the minimum budget');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ is($names, '[]', "relation list is genuinely empty, not just under-filled (got: $names)");
+
+ my $truncated = psch_query_clickhouse(
+ "SELECT relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1%' LIMIT 1"
+ );
+ is($truncated, 'true', "truncation is flagged even though zero entries fit (got: $truncated)");
+};
+
+subtest 'relations_enabled=off reports empty but not truncated' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'ALTER SYSTEM SET pg_stat_ch.relations_enabled = off');
+ $node->restart();
+
+ $node->safe_psql('postgres', 'SELECT * FROM foo1, foo2');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1, foo2%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ is($names, '[]', "relation list is empty while disabled (got: $names)");
+
+ my $truncated = psch_query_clickhouse(
+ "SELECT relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1, foo2%' LIMIT 1"
+ );
+ is($truncated, 'false', "opt-out is not reported as truncation (got: $truncated)");
+
+ $node->safe_psql('postgres', 'ALTER SYSTEM SET pg_stat_ch.relations_enabled = on');
+ $node->restart();
+};
+
+subtest 'failed query reports empty, non-truncated relations' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # Division by zero fails during planning (constant-folded), well before
+ # ExecutorEnd (where CopyRelations runs) is ever reached, so the error
+ # event must carry no relations. Error events carry no query_text (see
+ # CaptureLogEvent), so this is matched by SQLSTATE instead.
+ $node->psql('postgres', 'SELECT * FROM foo1 WHERE 1/0 = 1', on_error_stop => 0);
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE err_sqlstate = '22012' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ is($names, '[]', "failed query reports no relations (got: $names)");
+
+ my $truncated = psch_query_clickhouse(
+ "SELECT relations_truncated FROM pg_stat_ch.events_raw " .
+ "WHERE err_sqlstate = '22012' LIMIT 1"
+ );
+ is($truncated, 'false', "empty relations on error is not flagged as truncated (got: $truncated)");
+};
+
+# Encoding correctness: special characters, every relkind, the truncation
+# marker, and the exact byte-budget boundary.
+
+subtest 'identifiers with special characters stay unambiguous' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE TABLE "weird.name"(b int)');
+ $node->safe_psql('postgres', 'CREATE TABLE "has,comma"(c int)');
+ $node->safe_psql('postgres', 'CREATE TABLE "has""quote"(d int)');
+ $node->safe_psql('postgres',
+ 'SELECT * FROM "weird.name", "has,comma", "has""quote"');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE '%weird.name%has,comma%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+
+ # A comma or dot inside the name must not be treated as an element
+ # separator or namespace/name boundary.
+ like($names, qr/'has,comma'/, "has,comma survives as one element (got: $names)");
+ like($names, qr/'weird\.name'/, "weird.name survives as one element, dot intact (got: $names)");
+ like($names, qr/'has"quote'/, 'has"quote survives with embedded quote intact (got: ' . $names . ')');
+
+ # Let ClickHouse count array elements itself -- counting raw commas in
+ # the text form is wrong, since 'has,comma' has a literal comma inside
+ # its own quoted element, not just between elements.
+ my $count = psch_query_clickhouse(
+ "SELECT length(relation_names) FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE '%weird.name%has,comma%' LIMIT 1"
+ );
+ is($count, '3', "exactly 3 elements, no extra split from the embedded comma (got names: $names)");
+};
+
+subtest 'all relkinds are reported distinctly' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # postgres_fdw is a contrib module; CI's TAP-enabled PostgreSQL build
+ # (./configure --enable-tap-tests && make && make install, no
+ # `make -C contrib install`) does not build it, so foreign-table
+ # coverage degrades gracefully instead of hard-failing there.
+ my $has_fdw = $node->safe_psql('postgres',
+ "SELECT 1 FROM pg_available_extensions WHERE name = 'postgres_fdw'");
+
+ $node->safe_psql('postgres', 'CREATE TABLE rk_table(a int)');
+ $node->safe_psql('postgres', 'CREATE VIEW rk_view AS SELECT * FROM rk_table');
+ $node->safe_psql('postgres', 'CREATE MATERIALIZED VIEW rk_matview AS SELECT * FROM rk_table');
+ $node->safe_psql('postgres',
+ 'CREATE TABLE rk_part(id int, val text) PARTITION BY RANGE (id)');
+ $node->safe_psql('postgres',
+ 'CREATE TABLE rk_part_child PARTITION OF rk_part FOR VALUES FROM (0) TO (100)');
+
+ my $touch_tables = 'rk_table, rk_view, rk_matview, rk_part';
+ if ($has_fdw eq '1') {
+ $node->safe_psql('postgres', 'CREATE EXTENSION IF NOT EXISTS postgres_fdw');
+ $node->safe_psql('postgres',
+ "CREATE SERVER rk_loopback FOREIGN DATA WRAPPER postgres_fdw " .
+ "OPTIONS (host '" . $node->host . "', port '" . $node->port . "', dbname 'postgres')");
+ $node->safe_psql('postgres',
+ "CREATE USER MAPPING FOR CURRENT_USER SERVER rk_loopback");
+ $node->safe_psql('postgres',
+ "CREATE FOREIGN TABLE rk_ftable(a int) SERVER rk_loopback OPTIONS (table_name 'rk_table')");
+ $touch_tables .= ', rk_ftable';
+ }
+
+ $node->safe_psql('postgres', "SELECT * FROM $touch_tables");
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $kinds = psch_wait_for_clickhouse_query(
+ "SELECT relation_kinds FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE '%rk_table, rk_view%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+
+ like($kinds, qr/'r'/, "plain table reports relkind 'r' (got: $kinds)");
+ like($kinds, qr/'v'/, "view reports relkind 'v' (got: $kinds)");
+ like($kinds, qr/'m'/, "materialized view reports relkind 'm' (got: $kinds)");
+ like($kinds, qr/'p'/, "partitioned table reports relkind 'p' (got: $kinds)");
+
+ SKIP: {
+ skip 'postgres_fdw not available in this PostgreSQL build', 1
+ unless $has_fdw eq '1';
+ like($kinds, qr/'f'/, "foreign table reports relkind 'f' (got: $kinds)");
+ }
+};
+
+subtest 'runtime-pruned partition children collapse into the parent' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE TABLE gp_part(id int, val text) PARTITION BY RANGE (id)');
+ for my $i (0 .. 4) {
+ my $lo = $i * 100;
+ my $hi = $lo + 100;
+ $node->safe_psql('postgres',
+ "CREATE TABLE gp_part_$i PARTITION OF gp_part FOR VALUES FROM ($lo) TO ($hi)");
+ }
+ $node->safe_psql('postgres', 'CREATE TABLE gp_other(id int)');
+
+ $node->safe_psql('postgres', <<'SQL');
+SET plan_cache_mode = force_generic_plan;
+PREPARE gp_q(int) AS SELECT count(*) FROM gp_part JOIN gp_other USING (id) WHERE gp_part.id = $1;
+EXECUTE gp_q(5);
+SQL
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE '%gp_part%gp_other%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'gp_part'/, "parent reported (got: $names)");
+ like($names, qr/'gp_other'/, "unrelated joined table reported (got: $names)");
+ unlike($names, qr/'gp_part_\d'/, "pruned children not reported (got: $names)");
+};
+
+subtest 'multilevel (subpartitioned) hierarchy collapses leaves into the root' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE TABLE sp_root(id int, val text) PARTITION BY RANGE (id)');
+ $node->safe_psql('postgres',
+ 'CREATE TABLE sp_mid PARTITION OF sp_root FOR VALUES FROM (0) TO (1000) PARTITION BY RANGE (id)');
+ for my $i (0 .. 4) {
+ my $lo = $i * 100;
+ my $hi = $lo + 100;
+ $node->safe_psql('postgres',
+ "CREATE TABLE sp_leaf_$i PARTITION OF sp_mid FOR VALUES FROM ($lo) TO ($hi)");
+ }
+ $node->safe_psql('postgres', 'CREATE TABLE sp_other(id int)');
+
+ $node->safe_psql('postgres', <<'SQL');
+SET plan_cache_mode = force_generic_plan;
+PREPARE sp_q(int) AS SELECT count(*) FROM sp_root JOIN sp_other USING (id) WHERE sp_root.id = $1;
+EXECUTE sp_q(5);
+SQL
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE '%sp_root%sp_other%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'sp_root'/, "root reported (got: $names)");
+ like($names, qr/'sp_other'/, "unrelated joined table reported (got: $names)");
+ unlike($names, qr/'sp_mid'/, "subpartitioned intermediate not reported (got: $names)");
+ unlike($names, qr/'sp_leaf_\d'/, "leaves two levels down not reported (got: $names)");
+};
+
+subtest 'subpartitioned hierarchy with a large range table collapses correctly' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # 600 (mid, leaf) pairs plus the root: a large range table, to exercise
+ # the seen-set (a hash sized to the range table) well beyond a handful
+ # of entries.
+ $node->safe_psql('postgres', 'CREATE TABLE big_root(id int, val text) PARTITION BY RANGE (id)');
+ $node->safe_psql('postgres', <<'SQL');
+DO $do$
+DECLARE
+ i int;
+ lo int;
+ hi int;
+BEGIN
+ FOR i IN 0..599 LOOP
+ lo := i * 20;
+ hi := lo + 20;
+ EXECUTE format(
+ 'CREATE TABLE big_mid_%s PARTITION OF big_root FOR VALUES FROM (%s) TO (%s) PARTITION BY RANGE (id)',
+ i, lo, hi);
+ EXECUTE format(
+ 'CREATE TABLE big_leaf_%s PARTITION OF big_mid_%s FOR VALUES FROM (%s) TO (%s)',
+ i, i, lo, hi);
+ END LOOP;
+END
+$do$;
+SQL
+ $node->safe_psql('postgres', 'CREATE TABLE big_other(id int)');
+
+ $node->safe_psql('postgres', <<'SQL');
+SET plan_cache_mode = force_generic_plan;
+PREPARE big_q(int) AS SELECT count(*) FROM big_root JOIN big_other USING (id) WHERE big_root.id = $1;
+EXECUTE big_q(11999);
+SQL
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE '%big_root%big_other%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'big_root'/, "root reported (got: $names)");
+ like($names, qr/'big_other'/, "unrelated joined table reported (got: $names)");
+ unlike($names, qr/'big_mid_599'/, "subpartitioned intermediate past the old cap not reported (got: $names)");
+ unlike($names, qr/'big_leaf_599'/, "leaf past the old cap not reported (got: $names)");
+};
+
+subtest 'partition queried directly, with no parent in the range table, still reports' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM gp_part_0');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM gp_part_0%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'gp_part_0'/, "directly-queried partition still reported (got: $names)");
+};
+
+subtest 'inheritance children collapse into the parent' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE TABLE inh_parent(a int)');
+ $node->safe_psql('postgres', 'CREATE TABLE inh_child1() INHERITS (inh_parent)');
+ $node->safe_psql('postgres', 'CREATE TABLE inh_child2() INHERITS (inh_parent)');
+ $node->safe_psql('postgres', 'SELECT * FROM inh_parent');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE 'SELECT * FROM inh_parent%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'inh_parent'/, "inheritance parent reported (got: $names)");
+ unlike($names, qr/'inh_child/, "inheritance children collapsed into the parent (got: $names)");
+};
+
+subtest 'partition named explicitly alongside its parent is reported regardless of FROM order' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres',
+ 'SELECT * FROM ONLY gp_part CROSS JOIN gp_part_0 /* parent_first */');
+ $node->safe_psql('postgres',
+ 'SELECT * FROM gp_part_0 CROSS JOIN ONLY gp_part /* child_first */');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $parent_first = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE '%parent_first%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($parent_first, qr/'gp_part'/, "parent reported, parent-first order (got: $parent_first)");
+ like($parent_first, qr/'gp_part_0'/,
+ "explicit child reported, parent-first order (got: $parent_first)");
+
+ my $child_first = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE '%child_first%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($child_first, qr/'gp_part'/, "parent reported, child-first order (got: $child_first)");
+ like($child_first, qr/'gp_part_0'/,
+ "explicit child reported, child-first order (got: $child_first)");
+};
+
+subtest 'partition collapsed in one branch is still reported via an unflattened explicit reference' =>
+ sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # The OFFSET 0 subquery blocks flattening, so gp_part_0 gets its own
+ # real RTE here, distinct from the one the gp_part scan's partition
+ # expansion collapses into gp_part in the same range table.
+ $node->safe_psql('postgres',
+ 'SELECT * FROM gp_part CROSS JOIN (SELECT * FROM gp_part_0 OFFSET 0) c');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE query_text LIKE '%gp_part CROSS JOIN%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'gp_part'/, "parent reported (got: $names)");
+ like($names, qr/'gp_part_0'/, "explicitly-referenced partition still reported (got: $names)");
+};
+
+subtest 'maximum-length identifier round-trips intact' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # NAMEDATALEN-1 (63) is the real max a Postgres identifier can hold --
+ # anything longer is silently truncated by Postgres itself at parse time.
+ my $max_name = 'a' x 63;
+ $node->safe_psql('postgres', "CREATE TABLE $max_name(x int)");
+ $node->safe_psql('postgres', "SELECT * FROM $max_name");
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE length(relation_names) > 0 ORDER BY ts DESC LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/\Q$max_name\E/, "63-byte name round-trips without truncation or corruption (got: $names)");
+};
+
+subtest 'identifier made entirely of quote characters round-trips intact' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # Craig's example: a table name that is itself all double-quote
+ # characters. A length-prefixed field needs no escaping for this --
+ # it's just 63 raw 0x22 bytes with an explicit length prefix.
+ my $quote_name = '"' x 63; # the real, unquoted name
+ my $sql_literal = '"' . ('""' x 63) . '"'; # how to spell it in SQL
+ $node->safe_psql('postgres', "CREATE TABLE $sql_literal(x int)");
+ $node->safe_psql('postgres', "SELECT * FROM $sql_literal");
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw WHERE length(relation_names) > 0 ORDER BY ts DESC LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/\Q$quote_name\E/, "all-quote-character name survives intact, 63 raw bytes (got: $names)");
+};
+
+subtest 'exactly 7 max-length relations fit the 1023-byte budget, the 8th is dropped' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ # Worst-case per-relation cost: 1(ns_len) + 63(ns) + 1(name_len) +
+ # 63(name) + 1(relkind) = 129 bytes. (1023 - 2-byte header) / 129 = 7.9,
+ # so 7 fit and an 8th must be dropped with the truncated flag set.
+ my $ns63 = 'n' x 63;
+ $node->safe_psql('postgres', "CREATE SCHEMA $ns63");
+ my @tables;
+ for my $i (1 .. 8) {
+ my $tname = ('r' x 61) . sprintf('%02d', $i);
+ push @tables, "$ns63.$tname";
+ $node->safe_psql('postgres', "CREATE TABLE $ns63.$tname(x int)");
+ }
+ $node->safe_psql('postgres', 'SELECT * FROM ' . join(', ', @tables));
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $count = psch_wait_for_clickhouse_query(
+ "SELECT length(relation_names) FROM pg_stat_ch.events_raw WHERE length(relation_names) > 0 ORDER BY ts DESC LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ is($count, '7', "exactly 7 of 8 max-length relations fit the 1023-byte budget (got: $count)");
+
+ my $truncated = psch_query_clickhouse(
+ "SELECT relations_truncated FROM pg_stat_ch.events_raw WHERE length(relation_names) > 0 ORDER BY ts DESC LIMIT 1"
+ );
+ is($truncated, 'true', "the dropped 8th relation is explicitly flagged (got: $truncated)");
+};
+
+# Hook robustness: nested executor invocations (PL/pgSQL, dynamic EXECUTE,
+# nested PL/pgSQL) must not clobber the outer statement's relations.
+
+$node->safe_psql('postgres', 'CREATE TABLE outer_t(a int)');
+$node->safe_psql('postgres', 'CREATE TABLE inner_t(b int)');
+$node->safe_psql('postgres', q{
+ CREATE FUNCTION touches_inner(x int) RETURNS bigint AS $BODY$
+ SELECT count(*) FROM inner_t;
+ $BODY$ LANGUAGE sql STRICT;
+});
+# Must have real rows: the per-row function call -- and the nested executor
+# invocation it triggers -- never happens at all against an empty table.
+$node->safe_psql('postgres', 'INSERT INTO outer_t VALUES (1), (2)');
+$node->safe_psql('postgres', 'INSERT INTO inner_t VALUES (10)');
+
+subtest 'nested executor invocation does not clobber the outer statement relations' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT a, touches_inner(a) FROM outer_t');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT a, touches_inner(a) FROM outer_t%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'outer_t'/, "outer statement reports outer_t, not clobbered by the nested call (got: $names)");
+ unlike($names, qr/'inner_t'/, "outer statement's own relations do not include inner_t (got: $names)");
+};
+
+$node->safe_psql('postgres', q{
+ CREATE FUNCTION plpgsql_touches_inner(x int) RETURNS bigint AS $BODY$
+ DECLARE
+ cnt bigint;
+ BEGIN
+ SELECT count(*) INTO cnt FROM inner_t;
+ RETURN cnt;
+ END;
+ $BODY$ LANGUAGE plpgsql;
+});
+
+subtest 'PL/pgSQL function body does not clobber the caller relations' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT a, plpgsql_touches_inner(a) FROM outer_t');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT a, plpgsql_touches_inner(a) FROM outer_t%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'outer_t'/, "outer statement reports outer_t (got: $names)");
+ unlike($names, qr/'inner_t'/, "not clobbered by the PL/pgSQL function's own query (got: $names)");
+};
+
+$node->safe_psql('postgres', q{
+ CREATE FUNCTION plpgsql_touches_inner_dynamic(x int) RETURNS bigint AS $BODY$
+ DECLARE
+ cnt bigint;
+ BEGIN
+ EXECUTE 'SELECT count(*) FROM inner_t' INTO cnt;
+ RETURN cnt;
+ END;
+ $BODY$ LANGUAGE plpgsql;
+});
+
+subtest 'PL/pgSQL dynamic EXECUTE does not clobber the caller relations' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT a, plpgsql_touches_inner_dynamic(a) FROM outer_t');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT a, plpgsql_touches_inner_dynamic(a) FROM outer_t%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'outer_t'/, "outer statement reports outer_t (got: $names)");
+ unlike($names, qr/'inner_t'/, "not clobbered by the dynamic EXECUTE's query (got: $names)");
+};
+
+$node->safe_psql('postgres', 'CREATE TABLE inner_t2(c int)');
+$node->safe_psql('postgres', 'INSERT INTO inner_t2 VALUES (20)');
+$node->safe_psql('postgres', q{
+ CREATE FUNCTION plpgsql_level2() RETURNS bigint AS $BODY$
+ DECLARE
+ cnt bigint;
+ BEGIN
+ SELECT count(*) INTO cnt FROM inner_t2;
+ RETURN cnt;
+ END;
+ $BODY$ LANGUAGE plpgsql;
+});
+$node->safe_psql('postgres', q{
+ CREATE FUNCTION plpgsql_level1(x int) RETURNS bigint AS $BODY$
+ DECLARE
+ cnt bigint;
+ BEGIN
+ SELECT count(*) INTO cnt FROM inner_t;
+ RETURN cnt + plpgsql_level2();
+ END;
+ $BODY$ LANGUAGE plpgsql;
+});
+
+subtest 'nested PL/pgSQL calling PL/pgSQL does not clobber the caller relations' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT a, plpgsql_level1(a) FROM outer_t');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT a, plpgsql_level1(a) FROM outer_t%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'outer_t'/, "outer statement reports outer_t (got: $names)");
+ unlike($names, qr/'inner_t'/, "not clobbered by the first level of PL/pgSQL nesting (got: $names)");
+ unlike($names, qr/'inner_t2'/, "not clobbered by the second level of PL/pgSQL nesting (got: $names)");
+};
+
+subtest 'extension invoking SPI does not clobber the caller relations' => sub {
+ # tablefunc is a contrib module; CI's TAP-enabled PostgreSQL build
+ # (./configure --enable-tap-tests && make && make install, no
+ # `make -C contrib install`) does not build it, same gap as postgres_fdw
+ # above.
+ my $has_tablefunc = $node->safe_psql('postgres',
+ "SELECT 1 FROM pg_available_extensions WHERE name = 'tablefunc'");
+
+ SKIP: {
+ skip 'tablefunc not available in this PostgreSQL build', 2
+ unless $has_tablefunc eq '1';
+
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE EXTENSION IF NOT EXISTS tablefunc');
+ $node->safe_psql('postgres', q{
+ SELECT a FROM outer_t,
+ crosstab('SELECT 1, 1, b FROM inner_t') AS ct(row_name int, val int)
+ });
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT a FROM outer_t,%crosstab%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'outer_t'/, "outer statement reports outer_t (got: $names)");
+ unlike($names, qr/'inner_t'/, "not clobbered by crosstab's internal SPI query (got: $names)");
+ }
+};
+
+# Hook robustness: relation drop/recreate and rename must not leave stale
+# state behind in CollectRelations's catalog-lookup path.
+
+subtest 'table dropped and recreated with the same name reports cleanly' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE TABLE drtab(a int)');
+ $node->safe_psql('postgres', 'SELECT * FROM drtab');
+ $node->safe_psql('postgres', 'DROP TABLE drtab');
+ $node->safe_psql('postgres', 'CREATE TABLE drtab(b text)');
+ $node->safe_psql('postgres', 'SELECT * FROM drtab');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $stats = psch_get_stats($node);
+ cmp_ok($stats->{dsa_oom}, '==', 0, 'no crash/OOM across drop-and-recreate');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM drtab%' ORDER BY ts DESC LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'drtab'/, "post-recreate query still reports drtab cleanly (got: $names)");
+};
+
+subtest 'renamed table is reported under its new name' => sub {
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'CREATE TABLE old_name_tab(a int)');
+ $node->safe_psql('postgres', 'ALTER TABLE old_name_tab RENAME TO new_name_tab');
+ $node->safe_psql('postgres', 'SELECT * FROM new_name_tab');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $names = psch_wait_for_clickhouse_query(
+ "SELECT relation_names FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM new_name_tab%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ like($names, qr/'new_name_tab'/, "query by the new name reports new_name_tab (got: $names)");
+ unlike($names, qr/'old_name_tab'/, "no stale old name lingers anywhere (got: $names)");
+};
+
+subtest 'relation_* columns are omitted when disabled, so an unmigrated schema still accepts inserts' => sub {
+ # Simulate a destination that hasn't run the relation_* columns
+ # migration yet (the Down side of 20261104000003_*): the exporter must
+ # not mention these columns when relations_enabled is off, or the whole
+ # insert -- not just these fields -- would be rejected.
+ psch_query_clickhouse("DROP VIEW pg_stat_ch.events_recent_1h");
+ psch_query_clickhouse(
+ "ALTER TABLE pg_stat_ch.events_raw " .
+ "DROP COLUMN relation_namespaces, " .
+ "DROP COLUMN relation_names, " .
+ "DROP COLUMN relation_kinds, " .
+ "DROP COLUMN relations_truncated"
+ );
+ psch_query_clickhouse(
+ "CREATE MATERIALIZED VIEW pg_stat_ch.events_recent_1h " .
+ "ENGINE = MergeTree " .
+ "PARTITION BY toDate(ts) " .
+ "ORDER BY (instance_ubid, ts) " .
+ "TTL toDateTime(ts) + INTERVAL 1 HOUR DELETE " .
+ "POPULATE " .
+ "AS SELECT * FROM pg_stat_ch.events_raw WHERE ts > now() - INTERVAL 1 HOUR"
+ );
+
+ $node->safe_psql('postgres', 'ALTER SYSTEM SET pg_stat_ch.relations_enabled = off');
+ $node->restart();
+
+ psch_query_clickhouse("TRUNCATE TABLE pg_stat_ch.events_raw");
+ psch_reset_stats($node);
+
+ $node->safe_psql('postgres', 'SELECT * FROM foo1');
+ $node->safe_psql('postgres', 'SELECT pg_stat_ch_flush()');
+
+ my $duration = psch_wait_for_clickhouse_query(
+ "SELECT duration_us FROM pg_stat_ch.events_raw " .
+ "WHERE query_text LIKE 'SELECT * FROM foo1%' LIMIT 1",
+ sub { $_[0] ne '' },
+ 10
+ );
+ isnt($duration, '',
+ "row still inserted against a schema missing the relation_* columns (got duration_us: $duration)");
+
+ # Restore the schema and re-enable, leaving the shared CH container
+ # clean for whatever test file runs after this one.
+ psch_query_clickhouse("DROP VIEW pg_stat_ch.events_recent_1h");
+ psch_query_clickhouse(
+ "ALTER TABLE pg_stat_ch.events_raw " .
+ "ADD COLUMN relation_namespaces Array(LowCardinality(String)), " .
+ "ADD COLUMN relation_names Array(LowCardinality(String)), " .
+ "ADD COLUMN relation_kinds Array(FixedString(1)), " .
+ "ADD COLUMN relations_truncated Bool DEFAULT false"
+ );
+ psch_query_clickhouse(
+ "CREATE MATERIALIZED VIEW pg_stat_ch.events_recent_1h " .
+ "ENGINE = MergeTree " .
+ "PARTITION BY toDate(ts) " .
+ "ORDER BY (instance_ubid, ts) " .
+ "TTL toDateTime(ts) + INTERVAL 1 HOUR DELETE " .
+ "POPULATE " .
+ "AS SELECT * FROM pg_stat_ch.events_raw WHERE ts > now() - INTERVAL 1 HOUR"
+ );
+
+ $node->safe_psql('postgres', 'ALTER SYSTEM SET pg_stat_ch.relations_enabled = on');
+ $node->restart();
+};
+
+$node->stop();
+done_testing();
diff --git a/test/regression/expected/guc.out b/test/regression/expected/guc.out
index 1a09997..c81ea70 100644
--- a/test/regression/expected/guc.out
+++ b/test/regression/expected/guc.out
@@ -29,12 +29,14 @@ SELECT name FROM pg_settings WHERE name LIKE 'pg_stat_ch.%' ORDER BY name COLLAT
pg_stat_ch.otel_max_block_bytes
pg_stat_ch.otel_metric_interval_ms
pg_stat_ch.queue_capacity
+ pg_stat_ch.relations_enabled
+ pg_stat_ch.relations_max_len
pg_stat_ch.sample_rate
pg_stat_ch.string_area_size
pg_stat_ch.track_labels
pg_stat_ch.use_otel
pg_stat_ch.use_unified_arrow_exporter
-(31 rows)
+(33 rows)
SHOW pg_stat_ch.enabled;
pg_stat_ch.enabled
diff --git a/test/regression/expected/relations.out b/test/regression/expected/relations.out
new file mode 100644
index 0000000..9686f10
--- /dev/null
+++ b/test/regression/expected/relations.out
@@ -0,0 +1,117 @@
+-- Relations array collection.
+-- Actual captured VALUES (which relations landed in the array) can only be
+-- verified against ClickHouse -- see t/039_relations_export.pl. This
+-- regression test covers what pg_regress *can* check synchronously: the GUC,
+-- and that collection at ExecutorEnd doesn't crash/error across the basic
+-- shapes a per-query relations capture needs to handle (plain tables,
+-- schema-qualified tables, self-joins, views).
+CREATE EXTENSION pg_stat_ch;
+SELECT pg_stat_ch_reset();
+ pg_stat_ch_reset
+------------------
+
+(1 row)
+
+-- GUC: registered, default, and settable within its bounds.
+SHOW pg_stat_ch.relations_max_len;
+ pg_stat_ch.relations_max_len
+------------------------------
+ 1023
+(1 row)
+
+SET pg_stat_ch.relations_max_len = 64;
+SHOW pg_stat_ch.relations_max_len;
+ pg_stat_ch.relations_max_len
+------------------------------
+ 64
+(1 row)
+
+RESET pg_stat_ch.relations_max_len;
+-- The minimum (2 bytes -- just enough for the header) must still work
+-- without error; see PSCH_RELATIONS_HEADER_LEN.
+SET pg_stat_ch.relations_max_len = 2;
+SHOW pg_stat_ch.relations_max_len;
+ pg_stat_ch.relations_max_len
+------------------------------
+ 2
+(1 row)
+
+RESET pg_stat_ch.relations_max_len;
+CREATE TABLE rel_foo1(a int);
+CREATE TABLE rel_foo2(b int);
+CREATE SCHEMA rel_sch1;
+CREATE TABLE rel_sch1.foo3(c int);
+CREATE VIEW rel_v1 AS SELECT * FROM rel_foo1;
+-- Plain tables, schema-qualified table, self-join, view. Only checking
+-- these execute without error; see the TAP test for the actual captured
+-- relations values.
+SELECT * FROM rel_foo1;
+ a
+---
+(0 rows)
+
+SELECT * FROM rel_foo1, rel_foo2;
+ a | b
+---+---
+(0 rows)
+
+SELECT * FROM rel_sch1.foo3, rel_foo1;
+ c | a
+---+---
+(0 rows)
+
+SELECT * FROM rel_foo1 AS a, rel_foo1 AS b;
+ a | a
+---+---
+(0 rows)
+
+SELECT * FROM rel_v1;
+ a
+---
+(0 rows)
+
+-- A query touching more relations than a tiny budget allows must not error --
+-- truncation, not failure.
+SET pg_stat_ch.relations_max_len = 8;
+SELECT * FROM rel_foo1, rel_foo2, rel_sch1.foo3;
+ a | b | c
+---+---+---
+(0 rows)
+
+RESET pg_stat_ch.relations_max_len;
+-- A FETCH that fails before the executor runs (backward fetch on a NO
+-- SCROLL cursor, declared before an aborting savepoint) must not crash or
+-- break relations tracking for the rest of the session.
+BEGIN;
+DECLARE rel_cur NO SCROLL CURSOR FOR SELECT * FROM rel_foo1;
+SAVEPOINT rel_sp1;
+FETCH BACKWARD FROM rel_cur;
+ERROR: cursor can only scan forward
+HINT: Declare it with SCROLL option to enable backward scan.
+ROLLBACK TO SAVEPOINT rel_sp1;
+CLOSE rel_cur;
+COMMIT;
+-- Relations tracking still works for a normal query afterward.
+SELECT * FROM rel_foo1, rel_foo2;
+ a | b
+---+---
+(0 rows)
+
+-- relations_enabled is PGC_POSTMASTER (see t/039_relations_export.pl for the
+-- disabled-collection behavior, which needs a restart to toggle).
+SELECT enqueued_events > 0 AS has_enqueued_events FROM pg_stat_ch_stats();
+ has_enqueued_events
+---------------------
+ t
+(1 row)
+
+SELECT dsa_oom_count = 0 AS has_no_dsa_ooms FROM pg_stat_ch_stats();
+ has_no_dsa_ooms
+-----------------
+ t
+(1 row)
+
+DROP VIEW rel_v1;
+DROP TABLE rel_foo1, rel_foo2, rel_sch1.foo3;
+DROP SCHEMA rel_sch1;
+DROP EXTENSION pg_stat_ch;
diff --git a/test/regression/pg_stat_ch.conf b/test/regression/pg_stat_ch.conf
index 8b3d654..2480caa 100644
--- a/test/regression/pg_stat_ch.conf
+++ b/test/regression/pg_stat_ch.conf
@@ -1,2 +1,3 @@
shared_preload_libraries = 'pg_stat_ch'
pg_stat_ch.enabled = on
+pg_stat_ch.relations_enabled = on
diff --git a/test/regression/sql/relations.sql b/test/regression/sql/relations.sql
new file mode 100644
index 0000000..4458ebe
--- /dev/null
+++ b/test/regression/sql/relations.sql
@@ -0,0 +1,67 @@
+-- Relations array collection.
+-- Actual captured VALUES (which relations landed in the array) can only be
+-- verified against ClickHouse -- see t/039_relations_export.pl. This
+-- regression test covers what pg_regress *can* check synchronously: the GUC,
+-- and that collection at ExecutorEnd doesn't crash/error across the basic
+-- shapes a per-query relations capture needs to handle (plain tables,
+-- schema-qualified tables, self-joins, views).
+CREATE EXTENSION pg_stat_ch;
+SELECT pg_stat_ch_reset();
+
+-- GUC: registered, default, and settable within its bounds.
+SHOW pg_stat_ch.relations_max_len;
+SET pg_stat_ch.relations_max_len = 64;
+SHOW pg_stat_ch.relations_max_len;
+RESET pg_stat_ch.relations_max_len;
+
+-- The minimum (2 bytes -- just enough for the header) must still work
+-- without error; see PSCH_RELATIONS_HEADER_LEN.
+SET pg_stat_ch.relations_max_len = 2;
+SHOW pg_stat_ch.relations_max_len;
+RESET pg_stat_ch.relations_max_len;
+
+CREATE TABLE rel_foo1(a int);
+CREATE TABLE rel_foo2(b int);
+CREATE SCHEMA rel_sch1;
+CREATE TABLE rel_sch1.foo3(c int);
+CREATE VIEW rel_v1 AS SELECT * FROM rel_foo1;
+
+-- Plain tables, schema-qualified table, self-join, view. Only checking
+-- these execute without error; see the TAP test for the actual captured
+-- relations values.
+SELECT * FROM rel_foo1;
+SELECT * FROM rel_foo1, rel_foo2;
+SELECT * FROM rel_sch1.foo3, rel_foo1;
+SELECT * FROM rel_foo1 AS a, rel_foo1 AS b;
+SELECT * FROM rel_v1;
+
+-- A query touching more relations than a tiny budget allows must not error --
+-- truncation, not failure.
+SET pg_stat_ch.relations_max_len = 8;
+SELECT * FROM rel_foo1, rel_foo2, rel_sch1.foo3;
+RESET pg_stat_ch.relations_max_len;
+
+-- A FETCH that fails before the executor runs (backward fetch on a NO
+-- SCROLL cursor, declared before an aborting savepoint) must not crash or
+-- break relations tracking for the rest of the session.
+BEGIN;
+DECLARE rel_cur NO SCROLL CURSOR FOR SELECT * FROM rel_foo1;
+SAVEPOINT rel_sp1;
+FETCH BACKWARD FROM rel_cur;
+ROLLBACK TO SAVEPOINT rel_sp1;
+CLOSE rel_cur;
+COMMIT;
+
+-- Relations tracking still works for a normal query afterward.
+SELECT * FROM rel_foo1, rel_foo2;
+
+-- relations_enabled is PGC_POSTMASTER (see t/039_relations_export.pl for the
+-- disabled-collection behavior, which needs a restart to toggle).
+
+SELECT enqueued_events > 0 AS has_enqueued_events FROM pg_stat_ch_stats();
+SELECT dsa_oom_count = 0 AS has_no_dsa_ooms FROM pg_stat_ch_stats();
+
+DROP VIEW rel_v1;
+DROP TABLE rel_foo1, rel_foo2, rel_sch1.foo3;
+DROP SCHEMA rel_sch1;
+DROP EXTENSION pg_stat_ch;