Interface SecureParameter

@ThreadSafe public interface SecureParameter
Wraps a bound parameter value so Pyranid can mask it in diagnostics while still binding the underlying value normally.

This is display-only: it does not change what is bound to the database. Pyranid's own diagnostic rendering reads getMask() directly and does not rely on an implementation's Object.toString() method.

Scope and limits. Because the real value is bound to the PreparedStatement, the database driver may echo it back in its own error text (for example, PostgreSQL constraint violations include Key (email)=(...) already exists). As of 4.5.0, Pyranid additionally performs a best-effort scrub of verbatim occurrences of secure values from the DatabaseException message, its DBMS metadata fields, and StatementLog diagnostics. The scrub is verbatim-only: values the driver transforms before echoing (re-formatted numbers or temporals, truncated strings, encoded bytes) are not caught, and very short values are skipped to avoid corrupting unrelated diagnostics. The scrub applies to exceptions raised during statement execution; exceptions raised outside a statement context - commit/rollback time (e.g. deferred constraint violations), connection acquisition, raw-connection operations - are not scrubbed. The raw driver exception is deliberately preserved as the cause and is never sanitized - any sink that renders the stack trace or walks the cause chain (log appenders, error trackers such as Sentry, OpenTelemetry exception events) can still observe the raw value. Treat the cause chain as sensitive.

Implementations should be threadsafe.

Since:
4.4.0
Author:
Mark Allen

  • Method Summary

    Modifier and Type
    Method
    Description
    @NonNull String
    getMask()
    Gets the safe display value Pyranid should render in diagnostics.
    @NonNull Optional<Object>
    getValue()
    Gets the value to bind.

  • Method Details

    • getValue

      @NonNull Optional<Object> getValue()
      Gets the value to bind.
      Returns:
      the value to bind, or Optional.empty() if the value is null

    • getMask

      @NonNull String getMask()
      Gets the safe display value Pyranid should render in diagnostics.
      Returns:
      the safe display value