PgRelationWriter

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Writes rows to one table as PostgreSQL’s logical replication apply worker does, through the executor’s own replication helpers, so constraints, indexes and row triggers behave as they do for the built-in subscriber.

public sealed class PgRelationWriter : IDisposable

A writer locks the table in ROW EXCLUSIVE mode and keeps its executor state for the rest of the transaction or until it is disposed. Dispose it before the transaction commits; a transaction that commits with a writer still open fails. Rows use the table's own columns, from [Descriptor](/api/ankus.pgrelationwriter/#member-73d13a827c335765).

Updates, deletes and lookups find a row by the table's replica identity index, or else its primary key, using the key's columns; a table with neither matches every column. The row found is locked until the transaction ends. Triggers fire as session_replication_role selects; a change's AFTER triggers fire when it completes, as the apply worker fires them. Each operation needs the matching table privilege, and, as for the built-in apply worker, a table whose row-level security applies to the user is refused, because these helpers do not apply policies. Each change is visible to the next. Only ordinary tables can be written.

Inheritance: object

Implements: IDisposable

Methods

CreateReplicatedRow()

Creates a row for values in logical replication’s text or binary form, with no column sent yet.

public PgReplicatedRow CreateReplicatedRow()

Returns: PgReplicatedRow

The row.

CreateRow()

Creates an empty row with the table’s columns, all SQL NULL until set.

public PgHeapTuple CreateRow()

Returns: PgHeapTuple

The row.

Delete(PgHeapTuple)

Deletes the row that matches key.

public bool Delete(PgHeapTuple key)

Parameters:

key — PgHeapTuple

A row whose key columns identify the row to delete.

Returns: bool

Whether a matching row was found and deleted.

Exceptions:

• PgException: A trigger or foreign key rejects the delete.

Delete(PgReplicatedRow)

Deletes the row that matches key.

public bool Delete(PgReplicatedRow key)

Parameters:

key — PgReplicatedRow

A row whose key columns identify the row to delete.

Returns: bool

Whether a matching row was found and deleted.

Exceptions:

• PgException: A key value is not valid for its type, or a trigger or foreign key rejects the delete.

Dispose()

Closes the writer and releases its executor state. The table stays locked until the transaction ends.

public void Dispose()

Find(PgHeapTuple)

Finds and locks the row that matches key, as a conflict check before applying a change would.

public PgFoundRow? Find(PgHeapTuple key)

Parameters:

key — PgHeapTuple

A row whose key columns identify the row to find.

Returns: PgFoundRow

The row and the transaction that wrote it, or null when no row matches.

Find(PgReplicatedRow)

Finds and locks the row that matches key, as a conflict check before applying a change would.

public PgFoundRow? Find(PgReplicatedRow key)

Parameters:

key — PgReplicatedRow

A row whose key columns identify the row to find.

Returns: PgFoundRow

The row and the transaction that wrote it, or null when no row matches.

Insert(PgHeapTuple)

Inserts a row, checking constraints, adding index entries and firing row triggers.

public void Insert(PgHeapTuple row)

Parameters:

row — PgHeapTuple

The row, with the table’s columns.

Exceptions:

• PgException: A constraint or unique index rejects the row, or a trigger fails.

Insert(PgReplicatedRow)

Inserts a row whose values are in logical replication’s form; columns not sent take their defaults.

public void Insert(PgReplicatedRow row)

Parameters:

row — PgReplicatedRow

The row.

Exceptions:

• PgException: A value is not valid for its type, a constraint or unique index rejects the row, or a trigger fails.

Open(uint)

Opens a writer for a table in the current transaction.

public static PgRelationWriter Open(uint relationOid)

Parameters:

relationOid — uint

The table’s OID.

Returns: PgRelationWriter

The writer.

Exceptions:

• PgException: There is no transaction, the table does not exist or is not an ordinary table.

Update(PgHeapTuple, PgHeapTuple)

Replaces the row that matches key with row.

public bool Update(PgHeapTuple key, PgHeapTuple row)

Parameters:

key — PgHeapTuple

A row whose key columns identify the row to change.

row — PgHeapTuple

The new row, with every column.

Returns: bool

Whether a matching row was found and updated.

Exceptions:

• PgException: A constraint or unique index rejects the new row, or a trigger fails.

Update(PgReplicatedRow, PgReplicatedRow)

Replaces the row that matches key, keeping the values of columns row does not send, as an update with unchanged TOAST values does.

public bool Update(PgReplicatedRow key, PgReplicatedRow row)

Parameters:

key — PgReplicatedRow

A row whose key columns identify the row to change.

row — PgReplicatedRow

The new values.

Returns: bool

Whether a matching row was found and updated.

Exceptions:

• PgException: A value is not valid for its type, a constraint or unique index rejects the new row, or a trigger fails.

Properties

Descriptor

Gets the table’s columns, including dropped columns, in the order rows hold them.

public PgTupleDescriptor Descriptor { get; }

Value: PgTupleDescriptor

Writers for a table share one descriptor instance until the table’s definition changes, so a caller can keep data it derives from the columns, such as a column map, while the instance stays the same.

KeyIndexOid

Gets the OID of the index that identifies rows, the replica identity index or else the primary key, or zero when lookups compare every column.

public uint KeyIndexOid { get; }

Value: uint

RelationOid

Gets the table’s OID.

public uint RelationOid { get; }

Value: uint