SpiPreparedStatement
Namespace: Ankus
Assembly: Ankus.Runtime.dll
Owns a reusable PostgreSQL SPI plan. Execution and disposal require the owning backend thread. Use a using declaration for local statements; explicitly dispose cached statements when replacing them. Statements created by SpiSession expire with that session unless Keep transfers ownership out of the scope.
public sealed class SpiPreparedStatement : IDisposableInheritance: object
Implements: IDisposable
Properties
Section titled “Properties”CommandText
Section titled “CommandText”Gets the SQL text used to prepare this statement.
public string CommandText { get; }Value: string
ParameterCount
Section titled “ParameterCount”Gets the number of positional parameters required by this statement.
public int ParameterCount { get; }Value: int
Methods
Section titled “Methods”Dispose()
Section titled “Dispose()”Frees the native plan through a guarded backend call. Repeated disposal is harmless. PostgreSQL APIs cannot run on the finalizer thread. Independent plans require explicit disposal; session-owned plans are also released when their session ends.
public void Dispose()Execute(params ReadOnlySpan<SpiParameter>)
Section titled “Execute(params ReadOnlySpan<SpiParameter>)”Executes the statement and returns the final command’s processed-row count.
public long Execute(params ReadOnlySpan<SpiParameter> parameters)Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values whose PostgreSQL types must match the declared parameter types.
Returns: long
The processed-row count.
ExecuteScalar<T>(params ReadOnlySpan<SpiParameter>)
Section titled “ExecuteScalar<T>(params ReadOnlySpan<SpiParameter>)”Reads the first cell without limiting command execution or applying implicit type conversions. SQL NULL or an absent cell requires a nullable value type or reference type.
public T ExecuteScalar<T>(params ReadOnlySpan<SpiParameter> parameters)Type parameters:
T
The expected managed result type.
Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: T
The scalar value.
ExecuteScalars<TFirst, TSecond>(params ReadOnlySpan<SpiParameter>)
Section titled “ExecuteScalars<TFirst, TSecond>(params ReadOnlySpan<SpiParameter>)”Reads the first two columns of the first row without limiting command execution. SQL NULL or an empty result requires nullable value types or reference types.
public (TFirst First, TSecond Second) ExecuteScalars<TFirst, TSecond>(params ReadOnlySpan<SpiParameter> parameters)Type parameters:
TFirst
The first column’s managed type.
TSecond
The second column’s managed type.
Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: (TFirst First, TSecond Second)
The first two values from the final statement, without implicit type conversions.
Exceptions:
- InvalidOperationException: A returned row has fewer than two columns, or SQL NULL is read as a non-nullable value type.
- InvalidCastException: A column cannot be read as its requested managed type.
ExecuteScalars<TFirst, TSecond, TThird>(params ReadOnlySpan<SpiParameter>)
Section titled “ExecuteScalars<TFirst, TSecond, TThird>(params ReadOnlySpan<SpiParameter>)”Reads the first three columns of the first row without limiting command execution. SQL NULL or an empty result requires nullable value types or reference types.
public (TFirst First, TSecond Second, TThird Third) ExecuteScalars<TFirst, TSecond, TThird>(params ReadOnlySpan<SpiParameter> parameters)Type parameters:
TFirst
The first column’s managed type.
TSecond
The second column’s managed type.
TThird
The third column’s managed type.
Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: (TFirst First, TSecond Second, TThird Third)
The first three values from the final statement, without implicit type conversions.
Exceptions:
- InvalidOperationException: A returned row has fewer than three columns, or SQL NULL is read as a non-nullable value type.
- InvalidCastException: A column cannot be read as its requested managed type.
Keep()
Section titled “Keep()”Retains this statement beyond its session’s lifetime and returns the same explicitly disposable owner. Calling Keep on an already retained statement is harmless.
public SpiPreparedStatement Keep()Returns: SpiPreparedStatement
This statement, now independent of its original session.
OpenCursor(bool, params ReadOnlySpan<SpiParameter>)
Section titled “OpenCursor(bool, params ReadOnlySpan<SpiParameter>)”Opens a cursor from this plan with explicit read-only execution mode.
public SpiCursor OpenCursor(bool readOnly, params ReadOnlySpan<SpiParameter> parameters)Parameters:
readOnly — bool
Whether PostgreSQL should use read-only execution.
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiCursor
An owned cursor independent of the prepared statement’s lifetime.
OpenCursor(params ReadOnlySpan<SpiParameter>)
Section titled “OpenCursor(params ReadOnlySpan<SpiParameter>)”Opens a transaction-bound cursor from this plan. The cursor remains valid after the plan is disposed. Uses a read-only snapshot until the transaction becomes writable, then uses a fresh writable snapshot.
public SpiCursor OpenCursor(params ReadOnlySpan<SpiParameter> parameters)Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiCursor
An owned cursor.
Query(bool, int, params ReadOnlySpan<SpiParameter>)
Section titled “Query(bool, int, params ReadOnlySpan<SpiParameter>)”Executes the statement with explicit read-only mode and row limit.
public SpiResult Query(bool readOnly, int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
readOnly — bool
Whether PostgreSQL should use read-only SPI execution.
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiResult
The managed result.
Query(params ReadOnlySpan<SpiParameter>)
Section titled “Query(params ReadOnlySpan<SpiParameter>)”Executes the statement and materializes its result rows and metadata.
public SpiResult Query(params ReadOnlySpan<SpiParameter> parameters)Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiResult
The managed result.
QueryRaw(bool, int, params ReadOnlySpan<SpiParameter>)
Section titled “QueryRaw(bool, int, params ReadOnlySpan<SpiParameter>)”Copies raw native results with explicit snapshot mode and row limit.
public SpiRawResult QueryRaw(bool readOnly, int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
readOnly — bool
Whether PostgreSQL should use read-only SPI execution.
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiRawResult
A result to dispose before leaving the backend callback.
QueryRaw(params ReadOnlySpan<SpiParameter>)
Section titled “QueryRaw(params ReadOnlySpan<SpiParameter>)”Copies native result values without requiring a managed mapping for their PostgreSQL types.
public SpiRawResult QueryRaw(params ReadOnlySpan<SpiParameter> parameters)Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiRawResult
An owned result that survives this plan and expires on disposal or callback-context cleanup.
Select(int, params ReadOnlySpan<SpiParameter>)
Section titled “Select(int, params ReadOnlySpan<SpiParameter>)”Selects rows from this plan using PostgreSQL’s transaction state and an explicit row limit.
public SpiResult Select(int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiResult
The independently owned managed result.
Select(params ReadOnlySpan<SpiParameter>)
Section titled “Select(params ReadOnlySpan<SpiParameter>)”Selects rows with a read-only snapshot until the transaction becomes writable, then uses fresh writable snapshots.
public SpiResult Select(params ReadOnlySpan<SpiParameter> parameters)Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiResult
The independently owned managed result.
SelectRaw(int, params ReadOnlySpan<SpiParameter>)
Section titled “SelectRaw(int, params ReadOnlySpan<SpiParameter>)”Selects native values from this plan using transaction-aware snapshots and an explicit row limit.
public SpiRawResult SelectRaw(int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiRawResult
An owned result to dispose before leaving the backend callback.
SelectRaw(params ReadOnlySpan<SpiParameter>)
Section titled “SelectRaw(params ReadOnlySpan<SpiParameter>)”Selects native values from this plan using PostgreSQL’s transaction state without requiring managed type mappings.
public SpiRawResult SelectRaw(params ReadOnlySpan<SpiParameter> parameters)Parameters:
parameters — ReadOnlySpan<SpiParameter>
Values matching the declared parameter types.
Returns: SpiRawResult
An owned result that survives this plan and expires on disposal or callback-context cleanup.