provsql_error.h File Reference

Uniform error-reporting macros for ProvSQL. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	provsql_error(fmt, ...)
	Report a fatal ProvSQL error and abort the current transaction.
#define	PROVSQL_DELIBERATE   "deliberate"
	What kind of limit a refusal or a freezing is.
#define	PROVSQL_GAP   "gap"
#define	PROVSQL_OUT_OF_SCOPE   "out-of-scope"
#define	provsql_unsupported(scope, tag, fmt, ...)
	Refuse a query ProvSQL cannot track, and abort the transaction.
#define	provsql_warning(fmt, ...)
	Emit a ProvSQL warning message (execution continues).
#define	provsql_warning_tagged(scope, tag, fmt, ...)
	Emit a ProvSQL warning that names its cause by a stable tag.
#define	provsql_notice(fmt, ...)
	Emit a ProvSQL informational notice (execution continues).
#define	provsql_log(fmt, ...)
	Write a ProvSQL message to the server log only.

Detailed Description

Uniform error-reporting macros for ProvSQL.

Defines four convenience macros that wrap PostgreSQL's elog() and always prefix the user-visible message with "ProvSQL: ", giving every diagnostic a consistent origin tag regardless of which source file emits it.

The prefix is inserted by compile-time string-literal concatenation, so fmt must be a string literal (not a runtime char* variable).

Availability of elog()

This header intentionally contains no #include directives. The caller is responsible for making elog() visible before including this header:

• In normal PostgreSQL extension code, elog() comes from <utils/elog.h>, pulled in transitively through postgres.h or provsql_utils.h (which already includes this file at its end).
• In the standalone tdkc binary, BooleanCircuit.cpp defines a lightweight #define elog stub that writes to stderr and calls exit() on ERROR; provsql_error.h is included after that stub.

Definition in file provsql_error.h.

Macro Definition Documentation

PROVSQL_DELIBERATE

#define PROVSQL_DELIBERATE   "deliberate"

What kind of limit a refusal or a freezing is.

PROVSQL_DELIBERATE: the shape has no provenance to give, so refusing it is the answer and not a shortcoming – EXCEPT ALL and INTERSECT ALL, whose kept copies have no provenance of their own; IN read as a value, whose unknown truth no count of matches tells from false; two subquery conditions in one Boolean combination, whose two counts do not meet on one row. No rewriting will remove these.

PROVSQL_GAP: the query has a provenance and the rewriting does not reach it yet. Every one of these is a candidate for work.

PROVSQL_OUT_OF_SCOPE: the feature lies outside what the provenance of the supported query fragment covers – random variables and continuous distributions, where-provenance, conditioning, and ProvSQL's own surfaces (a provenance() call in an expression, an INSERT into an untracked table) – so neither of the two above applies to it.

The kind reaches tooling on the DETAIL line, next to the tag, so that a survey of what is covered can tell a deliberate refusal from a gap without keeping a table of its own.

Definition at line 63 of file provsql_error.h.

provsql_error

#define provsql_error	(		fmt,
			... )

Value:

elog(ERROR,   "ProvSQL: " fmt, ##__VA_ARGS__)

Report a fatal ProvSQL error and abort the current transaction.

Expands to elog(ERROR, "ProvSQL: " fmt, ...). In PostgreSQL, ERROR performs a non-local exit via longjmp; the call never returns. In the standalone tdkc build the elog stub calls exit(EXIT_FAILURE).

Parameters

fmt	A string literal format string (printf-style).
...	Optional format arguments.

Definition at line 38 of file provsql_error.h.

PROVSQL_GAP

#define PROVSQL_GAP   "gap"

Definition at line 64 of file provsql_error.h.

provsql_log

#define provsql_log	(		fmt,
			... )

Value:

elog(LOG,      "ProvSQL: " fmt, ##__VA_ARGS__)

Write a ProvSQL message to the server log only.

Expands to elog(LOG, "ProvSQL: " fmt, ...). LOG messages go to the PostgreSQL server log and are not forwarded to the client. Suitable for background-worker lifecycle events (e.g. worker startup).

Parameters

fmt	A string literal format string (printf-style).
...	Optional format arguments.

Definition at line 153 of file provsql_error.h.

provsql_notice

#define provsql_notice	(		fmt,
			... )

Value:

elog(NOTICE,   "ProvSQL: " fmt, ##__VA_ARGS__)

Emit a ProvSQL informational notice (execution continues).

Expands to elog(NOTICE, "ProvSQL: " fmt, ...). Typically used for progress messages gated on provsql.verbose_level.

Parameters

fmt	A string literal format string (printf-style).
...	Optional format arguments.

Definition at line 141 of file provsql_error.h.

PROVSQL_OUT_OF_SCOPE

#define PROVSQL_OUT_OF_SCOPE   "out-of-scope"

Definition at line 65 of file provsql_error.h.

provsql_unsupported

#define provsql_unsupported	(		scope,
			tag,
			fmt,
			... )

Value:

ereport(ERROR, (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),                     \
                errmsg("ProvSQL: " fmt, ##__VA_ARGS__),                     \
                errdetail("provsql-reason: %s; scope: %s", tag, scope)))

Refuse a query ProvSQL cannot track, and abort the transaction.

Like provsql_error, with SQLSTATE 0A000 (feature_not_supported) rather than XX000 (internal_error), so that clients can tell a deliberate refusal from a bug.

Every refusal carries a stable short tag, reported on the DETAIL line as "provsql-reason: @c <tag>". The message is what a user reads and may be reworded freely; the tag is what tooling keys on – the differential-testing harness groups its refusals by it, and the study of what the fragment covers joins on it – so a tag changes only with a reason. It is the first argument, so that no refusal can be added without one.

Parameters

scope	PROVSQL_DELIBERATE, PROVSQL_GAP or PROVSQL_OUT_OF_SCOPE.
tag	Stable kebab-case identifier of the cause.
fmt	A string literal format string (printf-style).
...	Optional format arguments.

Definition at line 91 of file provsql_error.h.

provsql_warning

#define provsql_warning	(		fmt,
			... )

Value:

elog(WARNING,  "ProvSQL: " fmt, ##__VA_ARGS__)

Emit a ProvSQL warning message (execution continues).

Expands to elog(WARNING, "ProvSQL: " fmt, ...). The message is sent to the client and server log according to the PostgreSQL log_min_messages / client_min_messages settings.

Parameters

fmt	A string literal format string (printf-style).
...	Optional format arguments.

Definition at line 107 of file provsql_error.h.

provsql_warning_tagged

#define provsql_warning_tagged	(		scope,
			tag,
			fmt,
			... )

Value:

ereport(WARNING, (errmsg("ProvSQL: " fmt, ##__VA_ARGS__),                   \
                  errdetail("provsql-reason: %s; scope: %s", tag, scope)))

Emit a ProvSQL warning that names its cause by a stable tag.

The warning counterpart of provsql_unsupported: a freezing is reported as a warning or, under provsql.implicit_freeze = 'error', as a refusal, and both carry the same tag on their DETAIL line so that tooling reads one key whichever the setting.

Parameters

scope	PROVSQL_DELIBERATE, PROVSQL_GAP or PROVSQL_OUT_OF_SCOPE.
tag	Stable kebab-case identifier of the cause.
fmt	A string literal format string (printf-style).
...	Optional format arguments.

Definition at line 127 of file provsql_error.h.