Core Concepts
Logging and Diagnostics
Pyranid provides tooling for runtime insight into SQL execution.
For many applications, it's important to understand exactly what queries are being run to keep on top of potential performance problems.
Further, it's often useful to mark specific queries for special processing - for example, you might want to log particularly slow or "special" SQL, or you might want to flag a query as needing Custom ResultSet Mapping.
Statement Logging
You may customize your Database with a StatementLogger.
Reasons you might do this include:
- Writing queries and timing information to your logging system
- Picking out slow queries for special logging/reporting
- Collecting a set of queries executed across a unit of work for bulk analysis (e.g. a
ThreadLocal<T>orScopedValue<T>scoped to a single web request)
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.statementLogger(new StatementLogger() {
Duration SLOW_QUERY_THRESHOLD = Duration.ofMillis(500);
@Override
public void log(@NonNull StatementLog statementLog) {
if(statementLog.getTotalDuration().compareTo(SLOW_QUERY_THRESHOLD) > 0)
out.printf("Slow query: %s\n", statementLog);
}
}).build();
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.statementLogger(new StatementLogger() {
Duration SLOW_QUERY_THRESHOLD = Duration.ofMillis(500);
@Override
public void log(@NonNull StatementLog statementLog) {
if(statementLog.getTotalDuration().compareTo(SLOW_QUERY_THRESHOLD) > 0)
out.printf("Slow query: %s\n", statementLog);
}
}).build();
StatementLogger failures are intentionally fail-fast. If your logger throws after a statement otherwise succeeds, that exception propagates to the caller. Inside a Pyranid transaction, logger failures participate in normal transaction failure handling and cause rollback. If the statement itself failed, the logger failure is attached as a suppressed exception to the primary failure.
Keep logger implementations lightweight and failure-safe. If logging must never affect database writes, catch and handle exceptions inside your logger implementation, or use MetricsCollector for best-effort observability.
StatementContext::toString() and StatementLog::toString() use StatementContext::getRedactedParameters(). Values wrapped with Parameters::secure(...) render as their mask:
// Configure a simple StatementLogger that writes to stdout
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.statementLogger(statementLog -> System.out.println(statementLog))
.build();
database.query("INSERT INTO api_credential (account_id, token_hash) VALUES (:accountId, :tokenHash)")
.bind("accountId", "acct_123")
.bind("tokenHash", Parameters.secure("token_hash_abc123"))
.execute();
// Configure a simple StatementLogger that writes to stdout
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.statementLogger(statementLog -> System.out.println(statementLog))
.build();
database.query("INSERT INTO api_credential (account_id, token_hash) VALUES (:accountId, :tokenHash)")
.bind("accountId", "acct_123")
.bind("tokenHash", Parameters.secure("token_hash_abc123"))
.execute();
The logged StatementLog includes a redacted parameter display:
parameters=[acct_123, <redacted>]
parameters=[acct_123, <redacted>]
Redact By Binding Name
StatementContext.getParameterNames() exposes an immutable list of original binding names in expanded JDBC-slot order. A repeated parameter repeats its name; every IN-list slot uses the original list name. Unknown names are null. The single three-argument ParameterRedactor.redactParameter(context, index, value) method returns non-null Optional<Object> in 4.9.0. Existing custom implementations/lambdas and direct callers must be updated and recompiled: this is a deliberate source and binary compatibility break from 4.8.0.
An implementation or lambda compiled against 4.8.0 can load successfully and then throw AbstractMethodError when parameter diagnostics invoke it. An old direct call targeting the removed Object return descriptor can throw NoSuchMethodError. Recompile all affected consumers, including libraries that supply a redactor. A source caller such as Object shown = redactor.redactParameter(context, index, value) still compiles after the upgrade but now receives an Optional, so update direct callers as well as implementations. Built-in none() and redactAll() configuration calls retain their existing shape.
Read the binding name from the context inside the three-argument policy. Use null-safe matching because a name can be unknown. This example also masks unknown names:
ParameterRedactor redactor = (context, index, value) -> {
String name = context.getParameterNames().get(index);
return name == null || "passwordHash".equals(name) || "token".equals(name)
? Optional.of("<redacted>")
: Optional.ofNullable(value);
};
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.parameterRedactor(redactor)
.build();
ParameterRedactor redactor = (context, index, value) -> {
String name = context.getParameterNames().get(index);
return name == null || "passwordHash".equals(name) || "token".equals(name)
? Optional.of("<redacted>")
: Optional.ofNullable(value);
};
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.parameterRedactor(redactor)
.build();
Pyranid diagnostics, direct callers and lambda decorators invoke this same method. Keep the complete masking policy in it; a decorator can call redactor.redactParameter(context, index, value) before transforming the returned display value.
Wrap display values in an Optional:
ParameterRedactor unchangedDisplay = (context, index, value) -> Optional.ofNullable(value);
ParameterRedactor maskEveryValue = (context, index, value) -> Optional.of("<redacted>");
ParameterRedactor displayNull = (context, index, value) -> Optional.empty();
ParameterRedactor unchangedDisplay = (context, index, value) -> Optional.ofNullable(value);
ParameterRedactor maskEveryValue = (context, index, value) -> Optional.of("<redacted>");
ParameterRedactor displayNull = (context, index, value) -> Optional.empty();
Import java.util.Optional. Optional.empty() produces a null display entry and retains the parameter's position; it does not omit the parameter. A redactor must return an Optional instance. Returning null violates the contract and fails direct diagnostic rendering. If rendering fails while Pyranid is reporting a SQL error, its existing fail-closed fallback omits the parameter display and preserves the original SQL failure with the rendering failure suppressed. Original bound values and the separate driver-text scrub are unaffected.
Indices remain zero-based. Manually built contexts can supply Builder.parameterNames(...); explicit lists must match the parameter-slot count. Reusing a captured statement without compatible parameter values falls back to unknown names. In batch contexts, getParameters() contains groups while names describe their shared JDBC slots. Conflicting names from different expansions of the same SQL become null; that conservative metadata remains operation-wide across chunks. Batch diagnostics still use a bounded summary and never call a redactor for individual group values.
Secure parameter masks always take precedence and bypass the redactor. Name-aware redaction remains display-only: it masks Pyranid's parameter list, not arbitrary driver-echoed text. Continue to bind sensitive values with Parameters.secure(...) when the best-effort DBMS text scrub is also required. Original values still reach JDBC, and getParameters() remains a raw trusted-code API.
Custom loggers can choose raw or display-safe parameters explicitly:
// Raw values, trusted code only
statementLog.getStatementContext().getParameters();
// Safe display values
statementLog.getStatementContext().getRedactedParameters();
// Raw values, trusted code only
statementLog.getStatementContext().getParameters();
// Safe display values
statementLog.getStatementContext().getRedactedParameters();
Pyranid exception messages use the same bounded parameter display. Under the default ParameterRedactor::none(), non-secure, non-batch values render verbatim; wrap sensitive bind values with Parameters::secure(...) or configure Database.Builder::parameterRedactor(...) when exception text may leave a trusted boundary.
Pyranid also makes a best-effort attempt to scrub verbatim occurrences of Parameters::secure(...) values from DatabaseException messages and DBMS metadata fields when the database driver echoed them into its own error text (for example, PostgreSQL constraint-violation detail). SQLState codes are preserved verbatim for error-handling policies, even when their text matches a secure value. The raw driver exception is deliberately preserved as the getCause() and is never sanitized - treat the cause chain as sensitive. See What Redaction Does and Does Not Cover for the full coverage table.
On driver-failure paths, the StatementLog carries Pyranid's wrapped DatabaseException - so logged diagnostics render scrubbed, redaction-aware text - with the raw driver exception available via its getCause().
Automatic DatabaseException.toString() rendering omits server detail, hint, internal query and context fields. Their explicit accessors remain available for trusted diagnostics. Record-construction failures report component names and types without printing fetched row values. Parameter redaction governs bound-parameter display; it does not generally redact fetched rows or arbitrary application/driver messages and cause chains.
StatementLog instances give you access to the following for each SQL statement executed:
statementContextconnectionAcquisitionDuration(optional)preparationDuration(optional)executionDuration(optional)resultSetMappingDuration(optional)elapsedDuration(optional, since 4.8.0)batchSize(optional)exception(optional)
The getTotalDuration() method returns the sum of active acquisition, preparation, execution, and mapping phases. The getElapsedDuration() method reports time measured independently from executor entry to resource cleanup, before terminal statement metrics and logging. It includes time spent in a stream consumer while resources remain open, but ends at EOF or explicit stream closure. Manually built logs leave elapsed duration absent unless explicitly supplied.
References:
Statement Identifiers
Use Query::id(Object) to tag statements.
This is useful for tagging queries that should be handled specially. Why might you do this?
- To mark a query as "hot" so we don't pollute logs with it
- To mark a query as "known to be slow" so we don't flag slow query alerts for it
- Your
InstanceProvidermight key on it to provide custom instances (e.g. during resultset mapping)
For example:
// This query fires every 3 seconds -
// let's give it a special identifier so we know not to log it.
Executors.newScheduledThreadPool(1).scheduleAtFixedRate(() -> {
// Safely "claim" some messages off the queue
List<Message> messages = database.transaction(() ->
Optional.of(database.query("""
UPDATE message_queue
SET message_status_id = :processing
WHERE id IN (
SELECT id
FROM message_queue
WHERE message_status_id = :unprocessed
ORDER BY created_at
LIMIT :limit
FOR UPDATE
SKIP LOCKED
)
RETURNING *
""")
.id("message-queue-claim")
.bind("unprocessed", MessageStatusId.UNPROCESSED)
.bind("processing", MessageStatusId.PROCESSING)
.bind("limit", BATCH_SIZE)
.fetchList(Message.class)))
.orElseThrow();
// Implementation not shown
processMessages(messages);
}, 0, 3, TimeUnit.SECONDS);
// This query fires every 3 seconds -
// let's give it a special identifier so we know not to log it.
Executors.newScheduledThreadPool(1).scheduleAtFixedRate(() -> {
// Safely "claim" some messages off the queue
List<Message> messages = database.transaction(() ->
Optional.of(database.query("""
UPDATE message_queue
SET message_status_id = :processing
WHERE id IN (
SELECT id
FROM message_queue
WHERE message_status_id = :unprocessed
ORDER BY created_at
LIMIT :limit
FOR UPDATE
SKIP LOCKED
)
RETURNING *
""")
.id("message-queue-claim")
.bind("unprocessed", MessageStatusId.UNPROCESSED)
.bind("processing", MessageStatusId.PROCESSING)
.bind("limit", BATCH_SIZE)
.fetchList(Message.class)))
.orElseThrow();
// Implementation not shown
processMessages(messages);
}, 0, 3, TimeUnit.SECONDS);
A corresponding Database setup:
// Ensure our StatementLogger implementation takes HOT_QUERY into account
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.statementLogger(new StatementLogger() {
@Override
public void log(@NonNull StatementLog statementLog) {
// Log everything except "message-queue-claim"
Statement statement = statementLog.getStatementContext().getStatement();
if(!statement.getId().equals("message-queue-claim"))
out.println(statementLog);
}
}).build();
// Ensure our StatementLogger implementation takes HOT_QUERY into account
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL)
.statementLogger(new StatementLogger() {
@Override
public void log(@NonNull StatementLog statementLog) {
// Log everything except "message-queue-claim"
Statement statement = statementLog.getStatementContext().getStatement();
if(!statement.getId().equals("message-queue-claim"))
out.println(statementLog);
}
}).build();
References:
Database Metadata
The JDBC standard defines a DatabaseMetaData type, which provides comprehensive vendor-specific information about a database as a whole.
Pyranid exposes a Database::readDatabaseMetaData(DatabaseMetaDataReader) method which acquires a transient DatabaseMetaData instance on its own newly-borrowed JDBC Connection (managed by Pyranid internally).
The Connection does not participate in the active transaction, if one exists.
The Connection is automatically closed as soon as the closure completes.
Failures carrying interruption evidence restore the thread's interrupt flag when no Pyranid transaction is open on the calling thread. If a transaction is open, transaction completion restores the flag only if the failure escapes the closure, even though metadata access uses a separate connection. A caller that handles the failure inside the closure decides whether to re-interrupt; see Interruption and Cancelation.
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL).build();
database.readDatabaseMetaData(databaseMetaData -> {
// e.g. "PostgreSQL"
out.println(databaseMetaData.getDatabaseProductName());
});
Database database = Database.with(dataSource, DatabaseType.POSTGRESQL).build();
database.readDatabaseMetaData(databaseMetaData -> {
// e.g. "PostgreSQL"
out.println(databaseMetaData.getDatabaseProductName());
});
Caution!
Your code should not retain a reference to the DatabaseMetaData instance outside the scope of the closure.

