TdsCdc.Lsn (tds_cdc v0.1.0)

Utilities for working with SQL Server Log Sequence Numbers (LSNs).

LSNs are used by CDC to track the position in the transaction log. They are represented as binary(10) values in SQL Server and are typically displayed as hexadecimal strings like "0x00000028:00000120:0001".

Summary

Functions

all_changes_query(capture_instance, from_lsn, to_lsn)

Builds the SQL query to get all changes for a capture instance between two LSN values (inclusive endpoints).

compare(lsn_a, lsn_b)

Compares two LSN binary values.

from_hex(hex)

Converts a hex string representation back to a binary LSN.

increment_lsn_query(lsn_binary)

Returns the SQL query to increment an LSN value.

lsn_to_time_query(lsn_binary)

Returns the SQL query to get the LSN from a binary value.

max_lsn_query()

Returns the SQL query to get the maximum LSN from the transaction log.

min_lsn_query(capture_instance)

Returns the SQL query to get the minimum LSN for a given capture instance.

to_hex(binary)

Converts a binary LSN from SQL Server to a hex string representation.

Functions

all_changes_query(capture_instance, from_lsn, to_lsn)

@spec all_changes_query(String.t(), binary(), binary()) :: String.t()

Builds the SQL query to get all changes for a capture instance between two LSN values (inclusive endpoints).

compare(lsn_a, lsn_b)

@spec compare(binary(), binary()) :: :lt | :eq | :gt

Compares two LSN binary values.

Returns :lt, :eq, or :gt similar to Enum.sort/2.

SQL Server LSNs are binary(10) values that sort lexicographically, which corresponds to their chronological order in the transaction log.

Examples

iex> TdsCdc.Lsn.compare(<<0,0,0,1,0,0,0,0,0,1>>, <<0,0,0,2,0,0,0,0,0,1>>)
:lt

iex> TdsCdc.Lsn.compare(<<0,0,0,2,0,0,0,0,0,1>>, <<0,0,0,1,0,0,0,0,0,1>>)
:gt

iex> TdsCdc.Lsn.compare(<<0,0,0,1,0,0,0,0,0,1>>, <<0,0,0,1,0,0,0,0,0,1>>)
:eq

from_hex(hex)

@spec from_hex(String.t()) :: binary()

Converts a hex string representation back to a binary LSN.

Accepts both the colon-separated format ("0x00000028:00000120:0001") and the plain hex format ("0x00000028000001200001").

Examples

iex> TdsCdc.Lsn.from_hex("0x00000028:00000120:0001")
<<0, 0, 0, 40, 0, 0, 1, 32, 0, 1>>

iex> TdsCdc.Lsn.from_hex("0x00000028000001200001")
<<0, 0, 0, 40, 0, 0, 1, 32, 0, 1>>

increment_lsn_query(lsn_binary)

@spec increment_lsn_query(binary()) :: String.t()

Returns the SQL query to increment an LSN value.

Used with the sys.fn_cdc_increment_lsn function to get the next LSN after a given position.

lsn_to_time_query(lsn_binary)

@spec lsn_to_time_query(binary()) :: String.t()

Returns the SQL query to get the LSN from a binary value.

This wraps the sys.fn_cdc_map_lsn_to_time function.

max_lsn_query()

@spec max_lsn_query() :: String.t()

Returns the SQL query to get the maximum LSN from the transaction log.

min_lsn_query(capture_instance)

@spec min_lsn_query(String.t()) :: String.t()

Returns the SQL query to get the minimum LSN for a given capture instance.

This is used to start reading changes from the beginning of available CDC data.

to_hex(binary)

@spec to_hex(binary()) :: String.t()

Converts a binary LSN from SQL Server to a hex string representation.

SQL Server stores LSNs as binary(10), which is 10 bytes. This function converts those bytes into the standard LSN display format: three groups of hex digits separated by colons.

Examples

iex> TdsCdc.Lsn.to_hex(<<0, 0, 0, 40, 0, 0, 1, 32, 0, 1>>)
"0x00000028:00000120:0001"