sqlcommenter

func AppendLabels ¶ added in v1.11.0

func AppendLabels(ctx context.Context, labels map[string]string, dbSystemName string, sourceOverride *bool) map[string]string

AppendLabels is the job-label counterpart to PrependComment for sources that attach metadata to jobs natively instead of embedding SQL comments (e.g. BigQuery). It merges the SQLCommenter attributes into the given job labels and returns the result; labels already present always win on key collisions, so tool-supplied labels are never overwritten. Labels surface in the source's own job metadata (for BigQuery: INFORMATION_SCHEMA.JOBS and billing exports), so no query text parsing is needed to recover them.

The attribute set matches PrependComment exactly. Attribute keys and values are machine-derived (e.g. client "name/version", model "gemini-2.5-flash") and routinely contain characters BigQuery rejects with an invalid-label error, so both are sanitized to the label constraints: only lowercase letters, digits, underscores, and dashes, at most 63 characters each, and keys must begin with a letter. Attribute names map punctuation to underscores, e.g. tool.name becomes tool_name. The 64-labels-per-job limit is deliberately left to the API, which rejects excess labels with a clear error rather than silently dropping telemetry.

Sanitization is lossy: values longer than 63 characters are silently truncated, so two values sharing a long prefix can become indistinguishable, and in principle two attribute names could sanitize to the same label key. Attributes are applied in sorted name order, so any such collision resolves deterministically.

sourceOverride behaves as in PrependComment: when non-nil it takes priority over the global sql-commenter flag from the context. Returns the input labels unchanged (including nil) when the commenter is disabled or no attributes are available.

func PrependComment ¶ added in v1.5.0

func PrependComment(ctx context.Context, statement string, dbSystemName string, sourceOverride *bool) string

PrependComment prepends a SQLCommenter-format comment to the given SQL statement. It gathers attributes from the context (trace, server, client, tool metadata) and the provided dbSystemName, then prepends them as key='value' pairs sorted alphabetically.

sourceOverride is the per-source `sqlCommenter` setting from tools.yaml. When non-nil it takes priority over the global sql-commenter flag; when nil the global flag (from context) is used.