org.postgresql.replication

Interface PGReplicationStream

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

V3PGReplicationStream

public interface PGReplicationStream
extends AutoCloseable

Not tread safe replication stream (though certain methods can be safely called by different threads). After complete streaming should be close, for free resource on backend. Periodical status update work only when use read() method. It means that process wal record should be fast as possible, because during process wal record lead to disconnect by timeout from server.

Method Summary

Modifier and Type	Method and Description
void	close() Stop replication changes from server and free resources.
void	forceUpdateStatus() Force send last received, flushed and applied LSN status to backend.
LogSequenceNumber	getLastAppliedLSN() Last applied lsn sent in update message to backed.
LogSequenceNumber	getLastFlushedLSN() Last flushed LSN sent in update message to backend.
LogSequenceNumber	getLastReceiveLSN() Parameter updates by execute read() method.
boolean	isClosed()
@Nullable ByteBuffer	read() Read next wal record from backend.
@Nullable ByteBuffer	readPending() Read next WAL record from backend.
void	setAppliedLSN(LogSequenceNumber applied) Inform backend which LSN has been applied on standby.
void	setFlushedLSN(LogSequenceNumber flushed) Set flushed LSN.

Method Detail

read

@Nullable ByteBuffer read()
                   throws SQLException

Read next wal record from backend. It method can be block until new message will not get from server.

A single WAL record is never split across two XLogData messages. When a WAL record crosses a WAL page boundary, and is therefore already split using continuation records, it can be split at the page boundary. In other words, the first main WAL record and its continuation records can be sent in different XLogData messages.

Returns:

not null byte array received by replication protocol, return ByteBuffer wrap around received byte array with use offset, so, use ByteBuffer.array() carefully

Throws:

SQLException - when some internal exception occurs during read from stream

readPending

@Nullable ByteBuffer readPending()
                          throws SQLException

Read next WAL record from backend. This method does not block and in contrast to read(). If message from backend absent return null. It allow periodically check message in stream and if they absent sleep some time, but it time should be less than CommonOptions.getStatusInterval() to avoid disconnect from the server.

A single WAL record is never split across two XLogData messages. When a WAL record crosses a WAL page boundary, and is therefore already split using continuation records, it can be split at the page boundary. In other words, the first main WAL record and its continuation records can be sent in different XLogData messages.

Returns:

byte array received by replication protocol or NULL if pending message from server absent. Returns ByteBuffer wrap around received byte array with use offset, so, use ByteBuffer.array() carefully.

Throws:

SQLException - when some internal exception occurs during read from stream

getLastReceiveLSN

LogSequenceNumber getLastReceiveLSN()

Parameter updates by execute read() method.

It is safe to call this method in a thread different than the main thread. However, usually this method is called in the main thread after a successful read() or readPending(), to get the LSN corresponding to the received record.

Returns:

NOT NULL LSN position that was receive last time via read() method

getLastFlushedLSN

LogSequenceNumber getLastFlushedLSN()

Last flushed LSN sent in update message to backend. Parameter updates only via setFlushedLSN(LogSequenceNumber)

It is safe to call this method in a thread different than the main thread.

Returns:

NOT NULL location of the last WAL flushed to disk in the standby.

getLastAppliedLSN

LogSequenceNumber getLastAppliedLSN()

Last applied lsn sent in update message to backed. Parameter updates only via setAppliedLSN(LogSequenceNumber)

It is safe to call this method in a thread different than the main thread.

Returns:

not null location of the last WAL applied in the standby.

setFlushedLSN

void setFlushedLSN(LogSequenceNumber flushed)

Set flushed LSN. This parameter will be sent to backend on next update status iteration. Flushed LSN position help backend define which WAL can be recycled.

It is safe to call this method in a thread different than the main thread. The updated value will be sent to the backend in the next status update run.

Parameters:

flushed - NOT NULL location of the last WAL flushed to disk in the standby.

See Also:

forceUpdateStatus()

setAppliedLSN

void setAppliedLSN(LogSequenceNumber applied)

Inform backend which LSN has been applied on standby. Feedback will send to backend on next update status iteration.

It is safe to call this method in a thread different than the main thread. The updated value will be sent to the backend in the next status update run.

Parameters:

applied - NOT NULL location of the last WAL applied in the standby.

See Also:

forceUpdateStatus()

forceUpdateStatus

void forceUpdateStatus()
                throws SQLException

Force send last received, flushed and applied LSN status to backend. You cannot send LSN status explicitly because PGReplicationStream sends the status to backend periodically by configured interval via CommonOptions.getStatusInterval()

Throws:

SQLException - when some internal exception occurs during read from stream

See Also:

CommonOptions.getStatusInterval()

isClosed

boolean isClosed()

Returns:

true if replication stream was already close, otherwise return false

close

void close()
    throws SQLException

Stop replication changes from server and free resources. After that connection can be reuse to another queries. Also after close current stream they cannot be used anymore.

Note: This method can spend much time for logical replication stream on postgresql version 9.6 and lower, because postgresql have bug - during decode big transaction to logical form and during wait new changes postgresql ignore messages from client. As workaround you can close replication connection instead of close replication stream. For more information about it problem see mailing list thread Stopping logical replication protocol

Specified by:

close in interface AutoCloseable

Throws:

SQLException - when some internal exception occurs during end streaming