Tracking LiteFS replication position

Each database created in LiteFS maintains a position in their replication log. The position is a combination of a monotonically incrementing transaction ID (TXID) and a rolling checksum of the database contents.

You can view the position for any database by reading the -pos suffixed file next to the database file. For example, if you have a database named db then you can read from a file called db-pos:

$ cat /path/to/mnt/db-pos
00000000002df417/ce552e44f23fbbdd

The TXID is represented a 16-character hex-encoded uint64. The checksum is encoded as a 16-character hex-encoded uint64. These are concatenated using a slash and a newline is appended at the end.

You can also use the LiteFS event stream to receive replication position updates in real time.

Using TXID to handle consistency

Clients can use the TXID if they wish to ensure that the database state is consistent across requests to different nodes. For example, a write to the primary may occur at TXID 100. If a subsequent request to a replica is performed, then the client can pass the TXID to the application and have it wait until it reaches or surpasses transaction ID 100.

Using a time-delay to handle consistency

Another approach is to redirect subsequent reads from a client to the primary for a few seconds after a write occurs. This is typically enough time to ensure that changes from the write are copied to the replica before it begins serving read requests to the client again. However, this provides weaker consistency guarantees over checking with the TXID in the position file since replication is not guaranteed to occur within a specified time frame.