fix(historian): QuestDB modification trail gets an applied marker and a dedup key (lmxopcua#746)
QuestDB has no multi-table transaction, so a HistoryUpdate writes its trail row before the sample change. A failed or crashed change left an orphan trail row that modified reads served as a change that happened, and a trail INSERT re-sent after a client timeout duplicated (the table had no key). - sample_modified gains `pending` and DEDUP UPSERT KEYS(ts, tag, modified_id). The trail row is written pending; after the change lands the same row is re-upserted pending = false (the applied marker). - A transient trail INSERT failure is re-sent once with the same ids; a first attempt that did apply converges on the key. - ReadModifiedAsync serves a pending row only when it is the latest trail row at its time and the sample there was written at or after the modification (a crash between change and marker). The orphan of a change that never landed, typically followed by the client's retry, is dropped. ASOF JOIN over the window's samples of one tag; the resume filter sits outside the window function so it never cuts a time's partition. - The bootstrapper migrates an older trail (ADD COLUMN pending, DEDUP ENABLE) and waits for it to apply (bounded 10 s); old rows read pending = false and stay visible. Until applied, or with AutoCreateSchema=false, the old format is used. Rebased from the unpushed remed/lane-H2 branch (originally authored 2026-10-22 in session_01Ub9hGmYLQvn9XETzw7CMsT) onto current master. Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
+154
@@ -0,0 +1,154 @@
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb.IntegrationTests;
|
||||
|
||||
/// <summary>
|
||||
/// The QuestDB modification trail's applied marker and dedup key. QuestDB has no multi-table transaction, so the trail
|
||||
/// row is written BEFORE its change: a failed change left an orphan row that modified reads served as a change that
|
||||
/// happened, and a trail INSERT re-sent after a client timeout duplicated. Now the row is written <c>pending</c>,
|
||||
/// marked applied after the change, keyed <c>(ts, tag, modified_id)</c>; a modified read drops a pending row unless the
|
||||
/// sample shows the change landed.
|
||||
/// </summary>
|
||||
[Collection(QuestDbCollection.Name)]
|
||||
public sealed class TrailMarkerTests(QuestDbFixture fx)
|
||||
{
|
||||
private static readonly DateTime T0 = new(2026, 3, 1, 12, 0, 0, DateTimeKind.Utc);
|
||||
private static readonly CancellationToken Ct = CancellationToken.None;
|
||||
|
||||
private static QuestDbHistorianDataSource Source(UpdateTests.Rig rig) => new(rig.Conn, rig.Tags.Bootstrap, rig.Tags);
|
||||
|
||||
private static async Task<IReadOnlyList<HistoryModifiedValue>> ModifiedAsync(UpdateTests.Rig rig, string tag) =>
|
||||
(await Source(rig).ReadModifiedAsync(tag, T0.AddMinutes(-1), T0.AddMinutes(10), 0, null, Ct)).Values;
|
||||
|
||||
private static async Task<long> TrailRowsAsync(UpdateTests.Rig rig, string tag)
|
||||
{
|
||||
await using var conn = await rig.Conn.OpenAsync(Ct);
|
||||
await using var cmd = rig.Conn.CreateCommand(conn, $"SELECT count() FROM {rig.Conn.SampleModifiedTable} WHERE tag = $1");
|
||||
QuestDbConnection.BindText(cmd, tag);
|
||||
return Convert.ToInt64(await cmd.ExecuteScalarAsync());
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task A_new_trail_table_has_the_marker_format_and_an_applied_change_reads_back()
|
||||
{
|
||||
fx.SkipIfUnavailable();
|
||||
var rig = UpdateTests.MakeRig(fx);
|
||||
(await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Insert, [UpdateTests.V(T0, 1)], UpdateTests.Who, Ct))
|
||||
.ShouldBe([HistorianStatusCodes.GoodEntryInserted]);
|
||||
rig.Tags.Bootstrap.SupportsTrailMarker.ShouldBeTrue();
|
||||
|
||||
var trail = await ModifiedAsync(rig, "t");
|
||||
trail.ShouldHaveSingleItem().UpdateType.ShouldBe(HistoryModificationType.Insert);
|
||||
(await TrailRowsAsync(rig, "t")).ShouldBe(1, "the applied marker re-upserts the row, it does not add one");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task The_orphan_of_a_change_that_never_landed_is_not_served()
|
||||
{
|
||||
fx.SkipIfUnavailable();
|
||||
var rig = UpdateTests.MakeRig(fx);
|
||||
await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Insert, [UpdateTests.V(T0, 1)], UpdateTests.Who, Ct);
|
||||
|
||||
rig.Updater.BeforeSampleWrite = () => throw new InvalidOperationException("the sample INSERT failed");
|
||||
await Should.ThrowAsync<InvalidOperationException>(
|
||||
() => rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Replace, [UpdateTests.V(T0, 2)], UpdateTests.Who, Ct));
|
||||
(await TrailRowsAsync(rig, "t")).ShouldBe(2, "precondition: the orphan trail row is stored");
|
||||
|
||||
var trail = await ModifiedAsync(rig, "t");
|
||||
trail.ShouldHaveSingleItem("only the insert that happened").UpdateType.ShouldBe(HistoryModificationType.Insert);
|
||||
|
||||
// Positive control: the same replace, landing, is served.
|
||||
rig.Updater.BeforeSampleWrite = null;
|
||||
await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Replace, [UpdateTests.V(T0, 2)], UpdateTests.Who, Ct);
|
||||
(await ModifiedAsync(rig, "t")).Select(v => v.UpdateType)
|
||||
.ShouldBe([HistoryModificationType.Insert, HistoryModificationType.Replace]);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData(false)]
|
||||
[InlineData(true)]
|
||||
public async Task A_change_that_landed_without_its_marker_is_still_served(bool delete)
|
||||
{
|
||||
// A crash between the sample change and the marker: the row stays pending, but the sample shows the change.
|
||||
fx.SkipIfUnavailable();
|
||||
var rig = UpdateTests.MakeRig(fx);
|
||||
await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Insert, [UpdateTests.V(T0, 1)], UpdateTests.Who, Ct);
|
||||
rig.Updater.SkipAppliedMarker = true;
|
||||
|
||||
if (delete)
|
||||
(await rig.Updater.DeleteAtTimeAsync("t", [T0], UpdateTests.Who, Ct)).ShouldBe([HistorianStatusCodes.Good]);
|
||||
else
|
||||
await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Replace, [UpdateTests.V(T0, 2)], UpdateTests.Who, Ct);
|
||||
|
||||
(await ModifiedAsync(rig, "t")).Select(v => v.UpdateType).ShouldBe(
|
||||
[HistoryModificationType.Insert, delete ? HistoryModificationType.Delete : HistoryModificationType.Replace]);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task A_trail_insert_re_sent_after_a_transient_failure_does_not_duplicate()
|
||||
{
|
||||
fx.SkipIfUnavailable();
|
||||
var rig = UpdateTests.MakeRig(fx);
|
||||
await rig.Tags.Bootstrap.EnsureAsync(Ct);
|
||||
var failedOnce = false;
|
||||
// The first attempt APPLIES and then fails as a client timeout would: the re-send carries the same ids.
|
||||
rig.Updater.AfterTrailInsert = attempt =>
|
||||
{
|
||||
if (attempt == 0 && !failedOnce) { failedOnce = true; throw new TimeoutException("client timeout"); }
|
||||
return Task.CompletedTask;
|
||||
};
|
||||
|
||||
(await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Insert,
|
||||
[UpdateTests.V(T0, 1), UpdateTests.V(T0.AddSeconds(1), 2), UpdateTests.V(T0.AddSeconds(2), 3)], UpdateTests.Who, Ct))
|
||||
.ShouldAllBe(s => s == HistorianStatusCodes.GoodEntryInserted);
|
||||
|
||||
failedOnce.ShouldBeTrue();
|
||||
rig.Updater.TrailInserts.ShouldBeGreaterThanOrEqualTo(3, "pending, the re-send, then the marker");
|
||||
(await TrailRowsAsync(rig, "t")).ShouldBe(3, "the re-sent rows converge on their dedup key");
|
||||
(await ModifiedAsync(rig, "t")).Count.ShouldBe(3);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task A_pre_marker_trail_table_is_migrated_on_boot_and_its_old_rows_stay_visible()
|
||||
{
|
||||
fx.SkipIfUnavailable();
|
||||
var p = fx.UniquePrefix();
|
||||
var o = fx.Options(p);
|
||||
var c = new QuestDbConnection(o);
|
||||
await using (var conn = await c.OpenAsync(Ct))
|
||||
{
|
||||
foreach (var ddl in QuestDbTables.CreateAll(p, null))
|
||||
{
|
||||
// The trail as it was: no pending column, no dedup key.
|
||||
var old = ddl.Replace(", pending BOOLEAN", "", StringComparison.Ordinal)
|
||||
.Replace(" DEDUP UPSERT KEYS(ts, tag, modified_id)", "", StringComparison.Ordinal);
|
||||
await using var cmd = c.CreateCommand(conn, old);
|
||||
await cmd.ExecuteNonQueryAsync(Ct);
|
||||
}
|
||||
}
|
||||
|
||||
// An old-format update first (the bootstrap with AutoCreateSchema=false keeps the old format).
|
||||
var legacyOptions = fx.Options(p, autoCreate: false);
|
||||
var legacyConn = new QuestDbConnection(legacyOptions);
|
||||
var legacyWal = new QuestDbWalVisibility(legacyConn, legacyOptions.VisibilityTimeout);
|
||||
var legacyTags = new QuestDbTagCatalog(legacyConn, new QuestDbSchemaBootstrapper(legacyConn, legacyOptions), legacyWal);
|
||||
var legacy = new UpdateTests.Rig(legacyConn, new QuestDbHistorianDataUpdater(legacyConn, legacyTags, legacyWal), legacyTags);
|
||||
(await legacy.Updater.UpdateDataAsync("t", HistoryUpdateMode.Insert, [UpdateTests.V(T0, 1)], UpdateTests.Who, Ct))
|
||||
.ShouldBe([HistorianStatusCodes.GoodEntryInserted]);
|
||||
legacyTags.Bootstrap.SupportsTrailMarker.ShouldBeFalse();
|
||||
(await ModifiedAsync(legacy, "t")).Count.ShouldBe(1);
|
||||
|
||||
// A boot with AutoCreateSchema=true migrates; the old row (pending reads false) is still served, a new one too.
|
||||
var wal = new QuestDbWalVisibility(c, o.VisibilityTimeout);
|
||||
var tags = new QuestDbTagCatalog(c, new QuestDbSchemaBootstrapper(c, o), wal);
|
||||
var rig = new UpdateTests.Rig(c, new QuestDbHistorianDataUpdater(c, tags, wal), tags);
|
||||
await tags.Bootstrap.EnsureAsync(Ct);
|
||||
tags.Bootstrap.SupportsTrailMarker.ShouldBeTrue();
|
||||
await rig.Updater.UpdateDataAsync("t", HistoryUpdateMode.Replace, [UpdateTests.V(T0, 2)], UpdateTests.Who, Ct);
|
||||
(await ModifiedAsync(rig, "t")).Select(v => v.UpdateType)
|
||||
.ShouldBe([HistoryModificationType.Insert, HistoryModificationType.Replace]);
|
||||
}
|
||||
}
|
||||
+7
-4
@@ -69,14 +69,17 @@ public sealed class QuestDbTablesTests
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Sample_modified_ddl_is_pinned_append_only_and_carries_the_ttl()
|
||||
public void Sample_modified_ddl_is_pinned_with_its_applied_marker_and_dedup_key_and_carries_the_ttl()
|
||||
{
|
||||
QuestDbTables.CreateSampleModified("hist_", null).ShouldBe(
|
||||
"CREATE TABLE IF NOT EXISTS hist_sample_modified (ts TIMESTAMP, tag SYMBOL INDEX, modified_id LONG, " +
|
||||
"modification_ts TIMESTAMP, update_type BYTE, principal VARCHAR, api_key_id VARCHAR, kind BYTE, num_value DOUBLE, " +
|
||||
"int_value LONG, str_value VARCHAR, status LONG, server_ts TIMESTAMP) TIMESTAMP(ts) PARTITION BY DAY WAL");
|
||||
QuestDbTables.CreateSampleModified("hist_", 30).ShouldEndWith("PARTITION BY DAY TTL 30 DAYS WAL");
|
||||
QuestDbTables.CreateSampleModified("hist_", null).ShouldNotContain("DEDUP");
|
||||
"int_value LONG, str_value VARCHAR, status LONG, server_ts TIMESTAMP, pending BOOLEAN) TIMESTAMP(ts) PARTITION BY DAY " +
|
||||
"WAL DEDUP UPSERT KEYS(ts, tag, modified_id)");
|
||||
QuestDbTables.CreateSampleModified("hist_", 30).ShouldEndWith("PARTITION BY DAY TTL 30 DAYS WAL DEDUP UPSERT KEYS(ts, tag, modified_id)");
|
||||
QuestDbTables.AddTrailPendingColumn("hist_sample_modified").ShouldBe("ALTER TABLE hist_sample_modified ADD COLUMN pending BOOLEAN");
|
||||
QuestDbTables.EnableTrailDedup("hist_sample_modified")
|
||||
.ShouldBe("ALTER TABLE hist_sample_modified DEDUP ENABLE UPSERT KEYS(ts, tag, modified_id)");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
|
||||
Reference in New Issue
Block a user