SpiSession
Namespace: Ankus
Assembly: Ankus.Runtime.dll
Provides a scoped SPI connection during a synchronous Spi.Connect callback. Operations require the owning backend callback and the innermost active session.
public sealed class SpiSessionInheritance: object
Methods
Section titled “Methods”Execute(SpiCommand)
Section titled “Execute(SpiCommand)”Executes a parameterized command on this active scoped session.
public long Execute(SpiCommand command)Parameters:
command — SpiCommand
SQL and its declared bindings.
Returns: long
The final statement’s processed row count.
Execute(string, params ReadOnlySpan<SpiParameter>)
Section titled “Execute(string, params ReadOnlySpan<SpiParameter>)”Executes commands within this session and returns the final command’s processed-row count.
public long Execute(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL command text.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: long
The processed-row count.
ExecuteScalar<T>(SpiCommand)
Section titled “ExecuteScalar<T>(SpiCommand)”Reads the first parameterized result cell without implicit conversion or limiting command effects.
public T ExecuteScalar<T>(SpiCommand command)Type parameters:
T
The expected managed result type.
Parameters:
command — SpiCommand
SQL and its declared bindings.
Returns: T
The scalar value with the existing SQL NULL and empty-result rules.
ExecuteScalar<T>(string, params ReadOnlySpan<SpiParameter>)
Section titled “ExecuteScalar<T>(string, params ReadOnlySpan<SpiParameter>)”Reads the first result cell without limiting a command’s write effects.
public T ExecuteScalar<T>(string commandText, params ReadOnlySpan<SpiParameter> parameters)Type parameters:
T
The expected managed result type.
Parameters:
commandText — string
The SQL command.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: T
The scalar value.
ExecuteScalars<TFirst, TSecond>(SpiCommand)
Section titled “ExecuteScalars<TFirst, TSecond>(SpiCommand)”Reads two parameterized result cells without implicit conversion or limiting command effects.
public (TFirst First, TSecond Second) ExecuteScalars<TFirst, TSecond>(SpiCommand command)Type parameters:
TFirst
The first column’s managed type.
TSecond
The second column’s managed type.
Parameters:
command — SpiCommand
SQL and its declared bindings.
Returns: (TFirst First, TSecond Second)
The first row’s two values with the existing SQL NULL and empty-result rules.
ExecuteScalars<TFirst, TSecond>(string, params ReadOnlySpan<SpiParameter>)
Section titled “ExecuteScalars<TFirst, TSecond>(string, 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>(string commandText, params ReadOnlySpan<SpiParameter> parameters)Type parameters:
TFirst
The first column’s managed type.
TSecond
The second column’s managed type.
Parameters:
commandText — string
The SQL commands to execute.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
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>(SpiCommand)
Section titled “ExecuteScalars<TFirst, TSecond, TThird>(SpiCommand)”Reads three parameterized result cells without implicit conversion or limiting command effects.
public (TFirst First, TSecond Second, TThird Third) ExecuteScalars<TFirst, TSecond, TThird>(SpiCommand command)Type parameters:
TFirst
The first column’s managed type.
TSecond
The second column’s managed type.
TThird
The third column’s managed type.
Parameters:
command — SpiCommand
SQL and its declared bindings.
Returns: (TFirst First, TSecond Second, TThird Third)
The first row’s three values with the existing SQL NULL and empty-result rules.
ExecuteScalars<TFirst, TSecond, TThird>(string, params ReadOnlySpan<SpiParameter>)
Section titled “ExecuteScalars<TFirst, TSecond, TThird>(string, 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>(string commandText, 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:
commandText — string
The SQL commands to execute.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
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.
Explain(SpiCommand)
Section titled “Explain(SpiCommand)”Plans a parameterized statement without executing EXPLAIN ANALYZE.
public PgJson Explain(SpiCommand command)Parameters:
command — SpiCommand
One SQL statement and its declared bindings.
Returns: PgJson
The owned JSON query plan.
Explain(string, params ReadOnlySpan<SpiParameter>)
Section titled “Explain(string, params ReadOnlySpan<SpiParameter>)”Plans one SQL statement within this session and returns its owned JSON EXPLAIN output.
public PgJson Explain(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL statement.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: PgJson
The JSON query plan.
OpenCursor(SpiCommand)
Section titled “OpenCursor(SpiCommand)”Opens a parameterized cursor using PostgreSQL’s transaction-aware snapshot policy.
public SpiCursor OpenCursor(SpiCommand command)Parameters:
command — SpiCommand
One row-producing statement and its declared bindings.
Returns: SpiCursor
An owned transaction-bound cursor.
OpenCursor(SpiCommand, bool)
Section titled “OpenCursor(SpiCommand, bool)”Opens a parameterized cursor with explicit read-only SPI execution mode.
public SpiCursor OpenCursor(SpiCommand command, bool readOnly)Parameters:
command — SpiCommand
One row-producing statement and its declared bindings.
readOnly — bool
Whether to enforce read-only SPI execution.
Returns: SpiCursor
An owned transaction-bound cursor.
OpenCursor(string, bool, params ReadOnlySpan<SpiParameter>)
Section titled “OpenCursor(string, bool, params ReadOnlySpan<SpiParameter>)”Opens a cursor with explicit read-only execution mode.
public SpiCursor OpenCursor(string commandText, bool readOnly, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
readOnly — bool
Whether to use read-only execution.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: SpiCursor
An owned transaction-bound cursor.
OpenCursor(string, params ReadOnlySpan<SpiParameter>)
Section titled “OpenCursor(string, params ReadOnlySpan<SpiParameter>)”Opens a transaction-bound cursor whose portal remains valid after this session ends. Uses a read-only snapshot until the transaction becomes writable, then uses a fresh writable snapshot.
public SpiCursor OpenCursor(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: SpiCursor
An owned cursor.
Prepare(string, params ReadOnlySpan<Type>)
Section titled “Prepare(string, params ReadOnlySpan<Type>)”Prepares a statement owned by this session. Call Keep on the statement to retain it beyond the callback.
public SpiPreparedStatement Prepare(string commandText, params ReadOnlySpan<Type> parameterTypes)Parameters:
commandText — string
The SQL command text.
parameterTypes — ReadOnlySpan<Type>
The declared CLR parameter types.
Returns: SpiPreparedStatement
A session-bound prepared statement.
PrepareWithTypeOids(string, params ReadOnlySpan<uint>)
Section titled “PrepareWithTypeOids(string, params ReadOnlySpan<uint>)”Prepares a session-owned statement with explicit PostgreSQL parameter identities, including named composites and domains.
public SpiPreparedStatement PrepareWithTypeOids(string commandText, params ReadOnlySpan<uint> parameterTypeOids)Parameters:
commandText — string
The SQL command text.
parameterTypeOids — ReadOnlySpan<uint>
The nonzero catalog type OIDs for positional parameters.
Returns: SpiPreparedStatement
A session-bound statement; Keep transfers it to independent ownership.
Query(SpiCommand, bool, int)
Section titled “Query(SpiCommand, bool, int)”Executes a parameterized command with explicit snapshot mode and a row limit.
public SpiResult Query(SpiCommand command, bool readOnly = false, int limit = 0)Parameters:
command — SpiCommand
SQL and its declared bindings.
readOnly — bool
Whether to enforce read-only SPI execution.
limit — int
The maximum returned rows, or zero for unlimited.
Returns: SpiResult
Owned managed rows and column metadata.
Query(string, bool, int, params ReadOnlySpan<SpiParameter>)
Section titled “Query(string, bool, int, params ReadOnlySpan<SpiParameter>)”Executes a query with explicit read-only mode and row limit.
public SpiResult Query(string commandText, bool readOnly, int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
readOnly — bool
Whether to use PostgreSQL’s read-only SPI execution mode.
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: SpiResult
The independently owned managed result.
Query(string, params ReadOnlySpan<SpiParameter>)
Section titled “Query(string, params ReadOnlySpan<SpiParameter>)”Executes a query and returns owned rows and metadata that remain valid after the session ends.
public SpiResult Query(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
parameters — ReadOnlySpan<SpiParameter>
The typed positional parameters.
Returns: SpiResult
The independently owned managed result.
QueryRaw(SpiCommand, bool, int)
Section titled “QueryRaw(SpiCommand, bool, int)”Executes a parameterized command with owned native results and explicit snapshot mode.
public SpiRawResult QueryRaw(SpiCommand command, bool readOnly = false, int limit = 0)Parameters:
command — SpiCommand
SQL and its declared bindings.
readOnly — bool
Whether to enforce read-only SPI execution.
limit — int
The maximum returned rows, or zero for unlimited.
Returns: SpiRawResult
An owned native result to dispose before leaving the backend callback.
QueryRaw(string, bool, int, params ReadOnlySpan<SpiParameter>)
Section titled “QueryRaw(string, bool, int, params ReadOnlySpan<SpiParameter>)”Copies raw native results with explicit snapshot mode and row limit.
public SpiRawResult QueryRaw(string commandText, bool readOnly, int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL command.
readOnly — bool
Whether PostgreSQL should use read-only SPI execution.
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
Returns: SpiRawResult
A result to dispose before leaving the backend callback.
QueryRaw(string, params ReadOnlySpan<SpiParameter>)
Section titled “QueryRaw(string, params ReadOnlySpan<SpiParameter>)”Copies native result values without requiring a managed mapping for their PostgreSQL types.
public SpiRawResult QueryRaw(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL command.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
Returns: SpiRawResult
An owned result that survives this session and expires on disposal or callback-context cleanup.
Select(SpiCommand, int)
Section titled “Select(SpiCommand, int)”Selects a parameterized command using PostgreSQL’s transaction-aware snapshot policy.
public SpiResult Select(SpiCommand command, int limit = 0)Parameters:
command — SpiCommand
SQL and its declared bindings.
limit — int
The maximum returned rows, or zero for unlimited.
Returns: SpiResult
Owned managed rows and column metadata.
Select(string, int, params ReadOnlySpan<SpiParameter>)
Section titled “Select(string, int, params ReadOnlySpan<SpiParameter>)”Selects rows using PostgreSQL’s transaction state and an explicit row limit.
public SpiResult Select(string commandText, int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
Returns: SpiResult
The independently owned managed result.
Select(string, params ReadOnlySpan<SpiParameter>)
Section titled “Select(string, params ReadOnlySpan<SpiParameter>)”Selects rows with a read-only snapshot until the transaction becomes writable, then uses fresh writable snapshots.
public SpiResult Select(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
Returns: SpiResult
Owned rows and metadata that remain valid after the session ends.
SelectRaw(SpiCommand, int)
Section titled “SelectRaw(SpiCommand, int)”Selects parameterized native values using PostgreSQL’s transaction-aware snapshot policy.
public SpiRawResult SelectRaw(SpiCommand command, int limit = 0)Parameters:
command — SpiCommand
SQL and its declared bindings.
limit — int
The maximum returned rows, or zero for unlimited.
Returns: SpiRawResult
An owned native result to dispose before leaving the backend callback.
SelectRaw(string, int, params ReadOnlySpan<SpiParameter>)
Section titled “SelectRaw(string, int, params ReadOnlySpan<SpiParameter>)”Selects native values using transaction-aware snapshots and an explicit row limit.
public SpiRawResult SelectRaw(string commandText, int limit, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
limit — int
The maximum returned rows, or zero for no limit.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
Returns: SpiRawResult
An owned result to dispose before leaving the backend callback.
SelectRaw(string, params ReadOnlySpan<SpiParameter>)
Section titled “SelectRaw(string, params ReadOnlySpan<SpiParameter>)”Selects native values using PostgreSQL’s transaction state without requiring managed type mappings.
public SpiRawResult SelectRaw(string commandText, params ReadOnlySpan<SpiParameter> parameters)Parameters:
commandText — string
The SQL query.
parameters — ReadOnlySpan<SpiParameter>
Typed positional parameters.
Returns: SpiRawResult
An owned result that survives this session and expires on disposal or callback-context cleanup.