feat(sql): authored write block — Update/Insert/Upsert/Procedure + timestamp stamp; ODBC scope + login docs (lmxopcua#781)
v2-ci / unit-tests (push) Has been cancelled

Item 2: a tag's optional `write` block picks the statement the driver builds from its own
catalog-validated identifiers (no authored SQL; values always bound):
- Update (default, unchanged back-compat UPDATE ... WHERE key; 0 rows = BadNoData)
- Insert (key+value[+stamp]; append for a WideRow topByTimestamp tag)
- Upsert: SQL Server MERGE WITH (HOLDLOCK), PostgreSQL INSERT ... ON CONFLICT, MySQL
  ON DUPLICATE KEY UPDATE (1-or-2 rows), Oracle MERGE from DUAL
- Procedure: named stored procedure resolved against the routine catalog by the catalog gate
  (INFORMATION_SCHEMA.ROUTINES / ALL_PROCEDURES), value/key/timestamp params by name (MySQL positional)
- stampTimestamp sets the tag's timestamp column to the write time (UTC)
Odbc serves Update/Insert only (shared SqlWriteSupport table). Constraint failures map to
BadEntryExists (unique) / BadOutOfRange (other integrity, data exception); everything else,
permission denied included, stays BadCommunicationError. WriteIdempotent stays false.
The parser refuses malformed blocks (strict keys/enums/param charset); DraftValidator emits
blocking SqlWriteBlockInvalid / SqlWriteModeUnsupported from the driver's own parse; the AdminUI
editor surfaces the same message.

Items 1 + 4 (docs/drivers/Sql.md): ODBC stays the ANSI SQL:2008 profile (native providers for
SQL Server/MySQL, DB2 unsupported) with an ops note on driver manager + vendor driver on every
Odbc and AdminUI host; read-only drivers require a SELECT-only login, writable drivers a login
limited to their write targets.

Tests: SqlWriteModeTests (parse, every dialect's SQL, gate, status map, SQLite end-to-end),
DraftValidatorSqlWriteBlockTests, AdminUI round-trip; live SqlWriteModesLiveTests on SQL Server,
PostgreSQL, MySQL, Oracle (seeds gain write_targets + set_target) and an Odbc write leg.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 22:56:21 -05:00
parent 2da58d0360
commit f5c30ed0ef
33 changed files with 2361 additions and 132 deletions
@@ -78,10 +78,34 @@ INSERT INTO setpoints (tag_name, sp_value) VALUES
('dup', 1.0),
('dup', 2.0);
-- Write-mode targets (lmxopcua#781, SqlWriteModesLiveTests): a primary-keyed setpoint table — the key ON DUPLICATE
-- KEY UPDATE fires on — and a DEFINER procedure that journals its arguments (MySQL CALL is positional: value, key,
-- write time, the order the driver passes them).
CREATE TABLE write_targets (
tag_name varchar(128) NOT NULL PRIMARY KEY,
sp_value double NOT NULL,
stamp_ts datetime(3) NULL
) ENGINE = InnoDB;
INSERT INTO write_targets (tag_name, sp_value, stamp_ts) VALUES ('Present', 1.0, NULL);
CREATE TABLE proc_calls (
tag_name varchar(128) NOT NULL,
sp_value double NULL,
stamp_ts datetime(3) NULL
) ENGINE = InnoDB;
DELIMITER //
CREATE PROCEDURE set_target(IN p_value double, IN p_key varchar(128), IN p_ts datetime(3))
MODIFIES SQL DATA SQL SECURITY DEFINER
BEGIN
INSERT INTO proc_calls (tag_name, sp_value, stamp_ts) VALUES (p_key, p_value, p_ts);
END//
DELIMITER ;
-- ── the read-only login ──────────────────────────────────────────────────────────────────────
DROP USER IF EXISTS 'otopcua'@'%';
CREATE USER 'otopcua'@'%' IDENTIFIED BY '__APP_PASSWORD__';
GRANT SELECT ON sqlpoll.* TO 'otopcua'@'%';
GRANT EXECUTE ON FUNCTION sqlpoll.bump_counter TO 'otopcua'@'%';
GRANT UPDATE ON sqlpoll.setpoints TO 'otopcua'@'%';
GRANT INSERT, UPDATE ON sqlpoll.write_targets TO 'otopcua'@'%';
GRANT EXECUTE ON PROCEDURE sqlpoll.set_target TO 'otopcua'@'%';
FLUSH PRIVILEGES;
@@ -29,6 +29,8 @@ docker network create "$NET" >/dev/null
docker run -d --name "$PG" --network "$NET" --label project=lmxopcua \
-e POSTGRES_PASSWORD="$PW" -e POSTGRES_DB=sqlpollfixture postgres:17-alpine >/dev/null
# a fresh postgres restarts once after initdb; probing too early can catch the shutdown (seen 2026-11-09)
sleep 8
for _ in $(seq 1 60); do docker exec "$PG" pg_isready -U postgres -d sqlpollfixture >/dev/null 2>&1 && break; sleep 1; done
docker exec -i "$PG" psql -q -v ON_ERROR_STOP=1 -v app_password="$PW" -U postgres -d sqlpollfixture \
< "$PROJECT/Docker/postgres/seed-pg.sql"
@@ -72,5 +72,41 @@ VALUES (9, NULL, 1.6, TIMESTAMP '2026-07-24 10:00:01');
INSERT INTO latest_status (station_id, oven_temp, pressure, sample_ts)
VALUES (8, 210.25, 1.4, TIMESTAMP '2026-07-24 10:00:02');
-- Write-mode targets (lmxopcua#781, SqlWriteModesLiveTests): a primary-keyed setpoint table for Update / Insert /
-- MERGE, and a procedure that journals its arguments (named notation: P_VALUE / P_KEY / P_TS).
BEGIN
EXECUTE IMMEDIATE 'DROP TABLE write_targets PURGE';
EXCEPTION
WHEN OTHERS THEN IF SQLCODE != -942 THEN RAISE; END IF;
END;
/
BEGIN
EXECUTE IMMEDIATE 'DROP TABLE proc_calls PURGE';
EXCEPTION
WHEN OTHERS THEN IF SQLCODE != -942 THEN RAISE; END IF;
END;
/
CREATE TABLE write_targets (
tag_name VARCHAR2(128) NOT NULL PRIMARY KEY,
sp_value NUMBER NOT NULL,
stamp_ts TIMESTAMP(3)
);
INSERT INTO write_targets (tag_name, sp_value, stamp_ts) VALUES ('Present', 1, NULL);
CREATE TABLE proc_calls (
tag_name VARCHAR2(128) NOT NULL,
sp_value NUMBER,
stamp_ts TIMESTAMP(3)
);
CREATE OR REPLACE PROCEDURE set_target(p_value IN NUMBER, p_key IN VARCHAR2, p_ts IN TIMESTAMP) AS
BEGIN
INSERT INTO proc_calls (tag_name, sp_value, stamp_ts) VALUES (p_key, p_value, p_ts);
END;
/
COMMIT;
EXIT;
@@ -94,8 +94,36 @@ INSERT INTO sqlpoll.int_tag_values (tag_id, num_value, sample_ts)
VALUES (101, 77.5, TIMESTAMP '2026-07-24 10:00:00'),
(102, 12.0, TIMESTAMP '2026-07-24 10:00:01');
-- Write-mode targets (lmxopcua#781, SqlWriteModesLiveTests): a primary-keyed setpoint table — the unique key is
-- what INSERT … ON CONFLICT (tag_name) needs — and a SECURITY DEFINER procedure that journals its arguments, so the
-- login needs only EXECUTE on it. p_ts is timestamptz because a procedure argument resolves by IMPLICIT cast and the
-- driver binds the write time as timestamptz.
CREATE TABLE sqlpoll.write_targets (
tag_name varchar(128) NOT NULL PRIMARY KEY,
sp_value double precision NOT NULL,
stamp_ts timestamp(3) NULL
);
INSERT INTO sqlpoll.write_targets (tag_name, sp_value, stamp_ts) VALUES ('Present', 1.0, NULL);
CREATE TABLE sqlpoll.proc_calls (
tag_name varchar(128) NOT NULL,
sp_value double precision NULL,
stamp_ts timestamptz NULL
);
CREATE PROCEDURE sqlpoll.set_target(p_value double precision, p_key varchar, p_ts timestamptz)
LANGUAGE sql SECURITY DEFINER
AS $$ INSERT INTO sqlpoll.proc_calls (tag_name, sp_value, stamp_ts) VALUES (p_key, p_value, p_ts) $$;
RESET ROLE;
-- ── grants: USAGE + SELECT and nothing else ───────────────────────────────────────────────────
GRANT USAGE ON SCHEMA sqlpoll TO otopcua;
GRANT SELECT ON ALL TABLES IN SCHEMA sqlpoll TO otopcua;
-- …except the write-mode targets (lmxopcua#781): INSERT + UPDATE on the one setpoint table, EXECUTE on the one
-- procedure. Every other table stays SELECT-only, so a write pointed there is refused by the server's own grant.
GRANT INSERT, UPDATE ON sqlpoll.write_targets TO otopcua;
REVOKE EXECUTE ON PROCEDURE sqlpoll.set_target FROM PUBLIC;
GRANT EXECUTE ON PROCEDURE sqlpoll.set_target TO otopcua;
@@ -111,6 +111,43 @@ public sealed class OdbcReadTests
columns.Select(c => c.DisplayName).ShouldBe(["tag_name", "num_value", "sample_ts"]);
}
/// <summary>
/// lmxopcua#781: the two write modes Odbc serves, through positional <c>?</c> binding — an Update that also
/// stamps (value, stamp, key in marker order), an Insert (key, value), and its duplicate surfacing the
/// backend's SQLSTATE 23505 through the driver manager as BadEntryExists. Upsert is refused, not attempted.
/// </summary>
[Fact]
public async Task Write_overOdbc_updateWithStamp_insert_andDuplicateKey()
{
SkipUnlessLive();
var key = "O-" + Guid.NewGuid().ToString("N")[..12];
static JsonObject Target(string keyValue, JsonObject write) => new()
{
["model"] = "KeyValue", ["table"] = "sqlpoll.write_targets", ["keyColumn"] = "tag_name",
["keyValue"] = keyValue, ["valueColumn"] = "sp_value", ["timestampColumn"] = "stamp_ts",
["type"] = "Float64", ["writable"] = true, ["write"] = write,
};
await using var driver = await StartAsync(null, allowWrites: true,
Tag("W/Update", Target("Present", new JsonObject { ["mode"] = "Update", ["stampTimestamp"] = true })),
Tag("W/Insert", Target(key, new JsonObject { ["mode"] = "Insert" })),
Tag("W/Upsert", Target(key, new JsonObject { ["mode"] = "Upsert" })));
var value = 500.0 + Random.Shared.Next(1, 1000);
(await WriteAsync(driver, "W/Update", value)).ShouldBe(SqlStatusCodes.Good);
Number((await driver.ReadAsync(["W/Update"], TestContext.Current.CancellationToken))[0]).ShouldBe(value);
(await WriteAsync(driver, "W/Insert", 1.25)).ShouldBe(SqlStatusCodes.Good);
Number((await driver.ReadAsync(["W/Insert"], TestContext.Current.CancellationToken))[0]).ShouldBe(1.25);
(await WriteAsync(driver, "W/Insert", 2.25)).ShouldBe(SqlStatusCodes.BadEntryExists);
(await WriteAsync(driver, "W/Upsert", 3.25)).ShouldBe(SqlStatusCodes.BadNotSupported);
}
private static async Task<uint> WriteAsync(SqlDriver driver, string reference, object? value)
=> (await ((IWritable)driver).WriteAsync([new WriteRequest(reference, value)], TestContext.Current.CancellationToken))
.ShouldHaveSingleItem().StatusCode;
private static double Number(DataValueSnapshot snapshot) => Convert.ToDouble(snapshot.Value, CultureInfo.InvariantCulture);
private static void SkipUnlessLive()
@@ -121,7 +158,11 @@ public sealed class OdbcReadTests
}
/// <summary>Builds the driver through the production factory with <c>provider: Odbc</c>.</summary>
private static async Task<SqlDriver> StartAsync(string? queriesJson, params RawTagEntry[] tags)
private static Task<SqlDriver> StartAsync(string? queriesJson, params RawTagEntry[] tags)
=> StartAsync(queriesJson, allowWrites: false, tags);
/// <summary>Builds the driver through the production factory with <c>provider: Odbc</c>.</summary>
private static async Task<SqlDriver> StartAsync(string? queriesJson, bool allowWrites, params RawTagEntry[] tags)
{
var reference = $"OdbcIt{Guid.NewGuid():N}";
Environment.SetEnvironmentVariable(SqlConnectionStringResolver.EnvironmentVariableFor(reference), ConnectionString);
@@ -137,6 +178,7 @@ public sealed class OdbcReadTests
["rawTags"] = rawTags,
};
if (queriesJson is not null) config["queries"] = JsonNode.Parse(queriesJson);
if (allowWrites) config["allowWrites"] = true;
var json = config.ToJsonString();
var driver = SqlDriverFactoryExtensions.CreateInstance("sql-odbc-integration", json);
@@ -363,7 +363,7 @@ public sealed class SqlPollServerFixture : IAsyncLifetime
{
// Views first: a view over a dropped table blocks nothing, but dropping the table under a live
// view leaves the catalog reporting a column set that no longer resolves.
foreach (var statement in SeedStatements())
foreach (var statement in SeedStatements().Concat(WriteTargetStatements()))
await ExecuteAsync(connection, statement).ConfigureAwait(false);
}
}
@@ -378,6 +378,11 @@ public sealed class SqlPollServerFixture : IAsyncLifetime
private static IEnumerable<string> SeedStatements()
{
yield return $"DROP VIEW IF EXISTS [{Schema}].[{WideRowView}];";
// lmxopcua#781 write-mode targets (SqlWriteModesLiveTests): a primary-keyed setpoint table for
// Update / Insert / Upsert and a procedure that journals its arguments into proc_calls.
yield return $"DROP PROCEDURE IF EXISTS [{Schema}].[set_target];";
yield return $"DROP TABLE IF EXISTS [{Schema}].[write_targets];";
yield return $"DROP TABLE IF EXISTS [{Schema}].[proc_calls];";
yield return $"DROP TABLE IF EXISTS [{Schema}].[{KeyValueTable}];";
yield return $"DROP TABLE IF EXISTS [{Schema}].[{WideRowTable}];";
yield return $"DROP TABLE IF EXISTS [{Schema}].[{TypeProbeTable}];";
@@ -446,6 +451,29 @@ public sealed class SqlPollServerFixture : IAsyncLifetime
}
/// <summary>Runs one non-query batch.</summary>
private static IEnumerable<string> WriteTargetStatements()
{
yield return $"""
CREATE TABLE [{Schema}].[write_targets] (
[tag_name] nvarchar(128) NOT NULL PRIMARY KEY,
[sp_value] float NOT NULL,
[stamp_ts] datetime2(3) NULL
);
""";
yield return $"INSERT INTO [{Schema}].[write_targets] ([tag_name], [sp_value], [stamp_ts]) VALUES (N'Present', 1.0, NULL);";
yield return $"""
CREATE TABLE [{Schema}].[proc_calls] (
[tag_name] nvarchar(128) NOT NULL,
[sp_value] float NULL,
[stamp_ts] datetime2(3) NULL
);
""";
yield return $"""
CREATE PROCEDURE [{Schema}].[set_target] @p_value float, @p_key nvarchar(128), @p_ts datetime2(3) AS
INSERT INTO [{Schema}].[proc_calls] ([tag_name], [sp_value], [stamp_ts]) VALUES (@p_key, @p_value, @p_ts);
""";
}
private static async Task ExecuteAsync(SqlConnection connection, string sql)
{
var command = connection.CreateCommand();
@@ -0,0 +1,273 @@
using System.Globalization;
using System.Text.Json.Nodes;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.Sql.Contracts;
namespace ZB.MOM.WW.OtOpcUa.Driver.Sql.IntegrationTests;
/// <summary>
/// The authored <c>write</c> block (lmxopcua#781 item 2) against real servers: Update with a stamp, Insert (and
/// the duplicate-key / NOT NULL failure mapping), the dialect's Upsert, and a stored-procedure call — one suite,
/// run per backend by the sealed subclasses below, each in its backend's existing collection and env gate.
/// <para>Every seed carries the same shape (<c>Docker/*/seed-*.sql</c>, and <see cref="SqlPollServerFixture"/>
/// for SQL Server): <c>write_targets(tag_name PK, sp_value NOT NULL, stamp_ts)</c> holding one <c>Present</c>
/// row, and <c>set_target(p_value, p_key, p_ts)</c>, which journals its arguments into <c>proc_calls</c>. Each
/// test writes a key of its own, so the suite needs no cleanup grant and tolerates re-runs.</para>
/// </summary>
public abstract class SqlWriteModesLiveSuite
{
/// <summary>Why the backend is unavailable, or null.</summary>
protected abstract string? SkipReason { get; }
/// <summary>The suite login's connection string.</summary>
protected abstract string ConnectionString { get; }
/// <summary>The backend's dialect.</summary>
protected abstract ISqlDialect Dialect { get; }
/// <summary>The schema the seed lives in, as authored (the catalog gate folds its case).</summary>
protected abstract string Schema { get; }
/// <summary>The procedure as authored — deliberately in the case the backend does NOT store, so the gate's spelling substitution is exercised.</summary>
protected abstract string AuthoredProcedure { get; }
// ---- Update ----
[Fact]
public async Task Update_withStamp_setsTheValueAndTheWriteTime_onThePresentRow()
{
SkipUnlessLive();
await using var driver = await StartAsync(Target("Sp", "Present", new JsonObject { ["stampTimestamp"] = true }));
var value = 100.0 + Random.Shared.Next(1, 1000);
var before = DateTime.UtcNow.AddMinutes(-2);
(await WriteAsync(driver, "Sp", value)).ShouldBe(SqlStatusCodes.Good);
Convert.ToDouble(await ScalarAsync("SELECT sp_value FROM {0} WHERE tag_name = 'Present'", "write_targets"),
CultureInfo.InvariantCulture).ShouldBe(value);
var stamped = Convert.ToDateTime(
await ScalarAsync("SELECT stamp_ts FROM {0} WHERE tag_name = 'Present'", "write_targets"), CultureInfo.InvariantCulture);
stamped.ShouldBeGreaterThan(before);
stamped.ShouldBeLessThan(DateTime.UtcNow.AddMinutes(2));
}
[Fact]
public async Task Update_toAnAbsentKey_isBadNoData_andInsertsNothing()
{
SkipUnlessLive();
var key = NewKey();
await using var driver = await StartAsync(Target("Sp", key, new JsonObject { ["mode"] = "Update" }));
(await WriteAsync(driver, "Sp", 1.0)).ShouldBe(SqlStatusCodes.BadNoData);
(await CountAsync("write_targets", key)).ShouldBe(0);
}
// ---- Insert ----
[Fact]
public async Task Insert_addsTheRow_andASecondInsertOfTheKey_isBadEntryExists()
{
SkipUnlessLive();
var key = NewKey();
await using var driver = await StartAsync(Target("Sp", key, new JsonObject { ["mode"] = "Insert" }));
(await WriteAsync(driver, "Sp", 5.25)).ShouldBe(SqlStatusCodes.Good);
(await WriteAsync(driver, "Sp", 6.25)).ShouldBe(SqlStatusCodes.BadEntryExists);
(await CountAsync("write_targets", key)).ShouldBe(1);
Convert.ToDouble(await ScalarAsync($"SELECT sp_value FROM {{0}} WHERE tag_name = '{key}'", "write_targets"),
CultureInfo.InvariantCulture).ShouldBe(5.25);
}
[Fact]
public async Task Insert_ofNull_intoANotNullColumn_isBadOutOfRange()
{
SkipUnlessLive();
var key = NewKey();
await using var driver = await StartAsync(Target("Sp", key, new JsonObject { ["mode"] = "Insert" }));
(await WriteAsync(driver, "Sp", null)).ShouldBe(SqlStatusCodes.BadOutOfRange);
(await CountAsync("write_targets", key)).ShouldBe(0);
}
// ---- Upsert ----
[Fact]
public async Task Upsert_insertsAnAbsentKey_thenUpdatesIt_andRepeatingTheSameValueStillSucceeds()
{
SkipUnlessLive();
var key = NewKey();
await using var driver = await StartAsync(Target("Sp", key, new JsonObject { ["mode"] = "Upsert", ["stampTimestamp"] = true }));
(await WriteAsync(driver, "Sp", 1.5)).ShouldBe(SqlStatusCodes.Good);
(await WriteAsync(driver, "Sp", 2.5)).ShouldBe(SqlStatusCodes.Good);
(await WriteAsync(driver, "Sp", 2.5)).ShouldBe(SqlStatusCodes.Good); // MySQL: unchanged row, found-rows = 1
(await CountAsync("write_targets", key)).ShouldBe(1);
Convert.ToDouble(await ScalarAsync($"SELECT sp_value FROM {{0}} WHERE tag_name = '{key}'", "write_targets"),
CultureInfo.InvariantCulture).ShouldBe(2.5);
Convert.ToDouble((await driver.ReadAsync(["Sp"], TestContext.Current.CancellationToken))[0].Value,
CultureInfo.InvariantCulture).ShouldBe(2.5);
}
// ---- Procedure ----
[Fact]
public async Task Procedure_isCalled_withTheValueKeyAndWriteTime()
{
SkipUnlessLive();
var key = NewKey();
await using var driver = await StartAsync(Target("Sp", "Present", new JsonObject
{
["mode"] = "Procedure", ["procedure"] = AuthoredProcedure,
["valueParam"] = "p_value", ["keyParam"] = "p_key", ["timestampParam"] = "p_ts",
}, keyValue: key));
var before = DateTime.UtcNow.AddMinutes(-2);
(await WriteAsync(driver, "Sp", 7.75)).ShouldBe(SqlStatusCodes.Good);
(await CountAsync("proc_calls", key)).ShouldBe(1);
Convert.ToDouble(await ScalarAsync($"SELECT sp_value FROM {{0}} WHERE tag_name = '{key}'", "proc_calls"),
CultureInfo.InvariantCulture).ShouldBe(7.75);
var stamp = await ScalarAsync($"SELECT stamp_ts FROM {{0}} WHERE tag_name = '{key}'", "proc_calls");
(stamp is DateTimeOffset dto ? dto.UtcDateTime : Convert.ToDateTime(stamp, CultureInfo.InvariantCulture))
.ShouldBeGreaterThan(before);
}
[Fact]
public async Task Procedure_thatDoesNotExist_isRejectedByTheCatalogGate()
{
SkipUnlessLive();
await using var driver = await StartAsync(Target("Sp", "Present", new JsonObject
{
["mode"] = "Procedure", ["procedure"] = Schema + ".no_such_proc",
}));
(await WriteAsync(driver, "Sp", 1.0)).ShouldBe(SqlStatusCodes.BadNodeIdUnknown);
}
// ---- helpers ----
private void SkipUnlessLive()
{
if (SkipReason is { } reason) Assert.Skip(reason);
}
private static string NewKey() => "W-" + Guid.NewGuid().ToString("N")[..12];
private RawTagEntry Target(string rawPath, string key, JsonObject write, string? keyValue = null)
{
var config = new JsonObject
{
["driver"] = "Sql",
["model"] = "KeyValue",
["table"] = Schema + ".write_targets",
["keyColumn"] = "tag_name",
["keyValue"] = keyValue ?? key,
["valueColumn"] = "sp_value",
["timestampColumn"] = "stamp_ts",
["type"] = "Float64",
["writable"] = true,
["write"] = write,
};
return new RawTagEntry(rawPath, config.ToJsonString(), WriteIdempotent: false);
}
private async Task<SqlDriver> StartAsync(params RawTagEntry[] tags)
{
var driver = new SqlDriver(
new SqlDriverOptions
{
RawTags = tags,
CommandTimeout = TimeSpan.FromSeconds(10),
OperationTimeout = TimeSpan.FromSeconds(15),
AllowWrites = true,
},
driverInstanceId: "sql-write-modes-" + Dialect.Provider,
dialect: Dialect,
connectionString: ConnectionString);
try
{
await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
}
catch
{
await driver.DisposeAsync();
throw;
}
return driver;
}
private static async Task<uint> WriteAsync(SqlDriver driver, string reference, object? value)
=> (await ((IWritable)driver).WriteAsync([new WriteRequest(reference, value)], TestContext.Current.CancellationToken))
.ShouldHaveSingleItem().StatusCode;
private async Task<long> CountAsync(string table, string key)
=> Convert.ToInt64(await ScalarAsync($"SELECT COUNT(*) FROM {{0}} WHERE tag_name = '{key}'", table),
CultureInfo.InvariantCulture);
/// <summary>Runs a scalar as the suite login; <c>{0}</c> is replaced by the schema-qualified table.</summary>
private async Task<object?> ScalarAsync(string sqlFormat, string table)
{
var connection = Dialect.Factory.CreateConnection()!;
await using (connection.ConfigureAwait(false))
{
connection.ConnectionString = ConnectionString;
await connection.OpenAsync(TestContext.Current.CancellationToken).ConfigureAwait(false);
var command = connection.CreateCommand();
await using (command.ConfigureAwait(false))
{
command.CommandText = string.Format(CultureInfo.InvariantCulture, sqlFormat, Schema + "." + table);
var value = await command.ExecuteScalarAsync(TestContext.Current.CancellationToken).ConfigureAwait(false);
return value is DBNull ? null : value;
}
}
}
}
/// <summary>SQL Server leg — the seeding fixture on the shared central server (its own database).</summary>
[Collection(SqlPollServerCollection.Name)]
public sealed class SqlServerWriteModesTests(SqlPollServerFixture fixture) : SqlWriteModesLiveSuite
{
protected override string? SkipReason => fixture.SkipReason;
protected override string ConnectionString => fixture.ConnectionString;
protected override ISqlDialect Dialect { get; } = new SqlServerDialect();
protected override string Schema => SqlPollServerFixture.Schema;
protected override string AuthoredProcedure => "SQLPOLL.SET_TARGET";
}
/// <summary>PostgreSQL leg — the granted-not-owning login; upper-case authoring folds to the stored lower case.</summary>
[Collection(PostgresCollection.Name)]
public sealed class PostgresWriteModesTests(PostgresFixture fixture) : SqlWriteModesLiveSuite
{
protected override string? SkipReason => fixture.SkipReason;
protected override string ConnectionString => fixture.ConnectionString;
protected override ISqlDialect Dialect { get; } = new PostgresDialect();
protected override string Schema => PostgresFixture.Schema;
protected override string AuthoredProcedure => "SQLPOLL.SET_TARGET";
}
/// <summary>MySQL leg — positional CALL, ON DUPLICATE KEY UPDATE's 1-or-2 row count.</summary>
[Collection(MySqlCollection.Name)]
public sealed class MySqlWriteModesTests(MySqlFixture fixture) : SqlWriteModesLiveSuite
{
protected override string? SkipReason => fixture.SkipReason;
protected override string ConnectionString => fixture.ConnectionString;
protected override ISqlDialect Dialect { get; } = new MySqlDialect();
protected override string Schema => MySqlFixture.Schema;
protected override string AuthoredProcedure => "SQLPOLL.SET_TARGET";
}
/// <summary>Oracle leg — MERGE from DUAL, an anonymous PL/SQL block; lower-case authoring folds to the stored upper case.</summary>
[Collection(OracleCollection.Name)]
public sealed class OracleWriteModesTests(OracleFixture fixture) : SqlWriteModesLiveSuite
{
protected override string? SkipReason => fixture.SkipReason;
protected override string ConnectionString => fixture.ConnectionString;
protected override ISqlDialect Dialect { get; } = new OracleDialect();
protected override string Schema => OracleFixture.Schema;
protected override string AuthoredProcedure => "otopcua.set_target";
}
@@ -0,0 +1,532 @@
using System.Globalization;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.Sql.Contracts;
namespace ZB.MOM.WW.OtOpcUa.Driver.Sql.Tests;
/// <summary>
/// The authored <c>write</c> block (lmxopcua#781 item 2): Update (default) / Insert / Upsert / Procedure, the
/// timestamp stamp, the parser's refusals, every dialect's statement, the routine catalog gate, constraint-failure
/// status mapping, and — over SQLite — the end-to-end Insert / Upsert / stamp paths.
/// </summary>
public sealed class SqlWriteModeTests
{
private static readonly DateTime Now = new(2026, 11, 9, 12, 0, 0, DateTimeKind.Utc);
private const string KvBase =
"\"model\":\"KeyValue\",\"table\":\"plant.sp\",\"keyColumn\":\"tag\",\"keyValue\":\"L1\",\"valueColumn\":\"val\"";
private static string Kv(string write, string extra = "") =>
"{" + KvBase + extra + ",\"writable\":true,\"write\":" + write + "}";
private static SqlTagDefinition Parse(string json)
{
SqlEquipmentTagParser.TryParse(json, "T", out var def).ShouldBeTrue();
return def;
}
// ---- parse ----
[Fact]
public void NoWriteBlock_isTheDefaultUpdate()
{
var def = Parse("{" + KvBase + ",\"writable\":true}");
def.Write.ShouldBeNull();
def.EffectiveWrite.ShouldBe(SqlWriteSpec.Default);
}
[Theory]
[InlineData("Update", SqlWriteMode.Update)]
[InlineData("insert", SqlWriteMode.Insert)]
[InlineData("UPSERT", SqlWriteMode.Upsert)]
public void Mode_parses_caseInsensitively(string mode, SqlWriteMode expected)
=> Parse(Kv($$"""{"mode":"{{mode}}"}""")).Write!.Mode.ShouldBe(expected);
[Fact]
public void ModeAbsent_inABlock_isUpdate_andStampIsRead()
{
var w = Parse(Kv("""{"stampTimestamp":true}""", ",\"timestampColumn\":\"ts\"")).Write!;
w.Mode.ShouldBe(SqlWriteMode.Update);
w.StampTimestamp.ShouldBeTrue();
}
[Fact]
public void Procedure_parsesNames_stripsAMarkerPrefix_andDefaultsTheValueParam()
{
var w = Parse(Kv("""{"mode":"Procedure","procedure":"dbo.SetSp","keyParam":"@TagName","timestampParam":":ts"}""")).Write!;
w.ShouldBe(new SqlWriteSpec(SqlWriteMode.Procedure, false, "dbo.SetSp", "value", "TagName", "ts"));
}
[Fact]
public void Procedure_isTheOneModeAQueryTagMayWrite()
{
const string query = """{"model":"Query","query":"q","column":"c","rowKey":{"column":"line","value":"L1"},"writable":true,"write":""";
Parse(query + """{"mode":"Procedure","procedure":"p","keyParam":"line"}}""").Write!.KeyParameter.ShouldBe("line");
SqlEquipmentTagParser.TryParse(query + """{"mode":"Update"}}""", "T", out _).ShouldBeFalse();
SqlEquipmentTagParser.TryParse(query + """{"mode":"Insert"}}""", "T", out _).ShouldBeFalse();
}
[Theory]
[InlineData("[]", "must be a JSON object")]
[InlineData("""{"mode":"Merge"}""", "'write.mode' must be one of")]
[InlineData("""{"mode":1}""", "'write.mode' must be one of")]
[InlineData("""{"mode":"Update","stampTimestmp":true}""", "unknown key 'stampTimestmp'")]
[InlineData("""{"stampTimestamp":"yes"}""", "must be a JSON boolean")]
[InlineData("""{"stampTimestamp":true}""", "no timestamp column")]
[InlineData("""{"mode":"Update","procedure":"p"}""", "applies only to mode Procedure")]
[InlineData("""{"mode":"Procedure"}""", "needs 'write.procedure'")]
[InlineData("""{"mode":"Procedure","procedure":" "}""", "needs 'write.procedure'")]
[InlineData("""{"mode":"Procedure","procedure":"db.dbo.p"}""", "'schema.procedure' only")]
[InlineData("""{"mode":"Procedure","procedure":"p","valueParam":"v; DROP"}""", "plain parameter name")]
[InlineData("""{"mode":"Procedure","procedure":"p","keyParam":"1abc"}""", "plain parameter name")]
[InlineData("""{"mode":"Procedure","procedure":"p","keyParam":5}""", "must be a string")]
[InlineData("""{"mode":"Procedure","procedure":"p","keyParam":"Value"}""", "same procedure parameter")]
[InlineData("""{"mode":"Procedure","procedure":"p","stampTimestamp":true}""", "does not apply to mode Procedure")]
public void MalformedBlocks_refuseTheTag_andInspectGivesTheParsersReason(string write, string reason)
{
var json = Kv(write);
SqlEquipmentTagParser.TryParse(json, "T", out _).ShouldBeFalse();
SqlEquipmentTagParser.TryParseDetailed(json, "T", out _, out var writeError).ShouldBeFalse();
writeError.ShouldNotBeNull().ShouldContain(reason);
SqlTagDefinitionFactory.DescribeWriteBlock(json).ShouldNotBeNull().ShouldContain(reason);
SqlTagDefinitionFactory.Inspect(json).ShouldHaveSingleItem().ShouldContain(reason);
}
[Fact]
public void UpdateAndUpsert_needARowKey_butInsertAppendsToANewestRowTag()
{
static string Newest(string mode) =>
$$$"""{"model":"WideRow","table":"t","columnName":"c","rowSelector":{"topByTimestamp":"ts"},"writable":true,"write":{"mode":"{{{mode}}}","stampTimestamp":true}}""";
SqlTagDefinitionFactory.DescribeWriteBlock(Newest("Update")).ShouldNotBeNull().ShouldContain("needs a row key");
SqlTagDefinitionFactory.DescribeWriteBlock(Newest("Upsert")).ShouldNotBeNull().ShouldContain("needs a row key");
SqlTagDefinitionFactory.DescribeWriteBlock(Newest("Insert")).ShouldBeNull(); // positive control
}
[Fact]
public void KeyParam_onAModelWithNoKey_isRefused()
=> SqlTagDefinitionFactory.DescribeWriteBlock(
"""{"model":"Query","query":"q","column":"c","write":{"mode":"Procedure","procedure":"p","keyParam":"k"}}""")
.ShouldNotBeNull().ShouldContain("no key to bind");
[Fact]
public void DescribeWriteBlock_isQuiet_forAValidBlock_noBlock_orABlobBrokenElsewhere()
{
SqlTagDefinitionFactory.DescribeWriteBlock(Kv("""{"mode":"Upsert"}""")).ShouldBeNull();
SqlTagDefinitionFactory.DescribeWriteBlock("{" + KvBase + "}").ShouldBeNull();
// The tag's own fields are what fail (no table) — Inspect reports that, not the write block.
SqlTagDefinitionFactory.DescribeWriteBlock("""{"model":"KeyValue","write":{"mode":"Nope"}}""").ShouldBeNull();
}
// ---- shared support table ----
[Theory]
[InlineData(SqlProvider.Odbc, SqlWriteMode.Update, true)]
[InlineData(SqlProvider.Odbc, SqlWriteMode.Insert, true)]
[InlineData(SqlProvider.Odbc, SqlWriteMode.Upsert, false)]
[InlineData(SqlProvider.Odbc, SqlWriteMode.Procedure, false)]
[InlineData(SqlProvider.SqlServer, SqlWriteMode.Upsert, true)]
[InlineData(SqlProvider.Oracle, SqlWriteMode.Procedure, true)]
public void SupportTable(SqlProvider provider, SqlWriteMode mode, bool supported)
=> SqlWriteSupport.IsSupported(provider, mode).ShouldBe(supported);
/// <summary>
/// The shared table (deploy's verdict) and each real dialect's statements (runtime's) must agree: a mode the
/// table says is served has a statement, and one it refuses has none — so deploy can never accept a mode the
/// driver then refuses, or refuse one it would serve.
/// </summary>
[Fact]
public void EveryRealDialect_buildsAStatement_exactlyForTheModesTheSharedTableServes()
{
foreach (var provider in Enum.GetValues<SqlProvider>())
{
var dialect = SqlDialects.TryCreate(provider).ShouldNotBeNull();
dialect.SupportsWriteMode(SqlWriteMode.Upsert).ShouldBe(SqlWriteSupport.IsSupported(provider, SqlWriteMode.Upsert));
(dialect.UpsertSql("t", "k", "m", [("v", "n")]) is not null)
.ShouldBe(SqlWriteSupport.IsSupported(provider, SqlWriteMode.Upsert), provider.ToString());
(dialect.ProcedureCallSql("p", [("value", "m")]) is not null && dialect.ListRoutinesSql is not null)
.ShouldBe(SqlWriteSupport.IsSupported(provider, SqlWriteMode.Procedure), provider.ToString());
}
}
// ---- planner: per mode, per dialect ----
private static SqlTagDefinition KvTag(SqlWriteSpec? write, string? ts = null) =>
new("A", SqlTagModel.KeyValue, "plant.sp", KeyColumn: "tag", KeyValue: "L1", ValueColumn: "val",
TimestampColumn: ts, Writable: true, Write: write);
private static SqlWritePlan Plan(SqlTagDefinition tag, ISqlDialect dialect, object? value = null)
{
SqlWritePlanner.TryPlan(tag, value ?? 5.5, dialect, Now, out var plan).ShouldBe(SqlStatusCodes.Good);
return plan!;
}
[Fact]
public void Update_withStamp_setsValueThenStamp_thenTheKey_inMarkerOrder()
{
var plan = Plan(KvTag(new SqlWriteSpec(SqlWriteMode.Update, StampTimestamp: true), ts: "ts"), new OdbcDialect());
plan.SqlText.ShouldBe("UPDATE \"plant\".\"sp\" SET \"val\" = ?, \"ts\" = ? WHERE \"tag\" = ?");
plan.Parameters.ShouldBe([5.5, Now, "L1"]);
plan.Mode.ShouldBe(SqlWriteMode.Update);
}
[Fact]
public void Update_withoutStamp_isByteIdenticalToTheOriginalStatement()
=> Plan(KvTag(null, ts: "ts"), new SqlServerDialect()).SqlText
.ShouldBe("UPDATE [plant].[sp] SET [val] = @v WHERE [tag] = @k");
[Fact]
public void Insert_keyValue_insertsKeyValueAndStamp_inColumnOrder()
{
var plan = Plan(KvTag(new SqlWriteSpec(SqlWriteMode.Insert, StampTimestamp: true), ts: "ts"), new OdbcDialect());
plan.SqlText.ShouldBe("INSERT INTO \"plant\".\"sp\" (\"tag\", \"val\", \"ts\") VALUES (?, ?, ?)");
plan.Parameters.ShouldBe(["L1", 5.5, Now]);
}
[Fact]
public void Insert_onANewestRowTag_appendsTheValueAndItsOrderingColumn_withNoKey()
{
var tag = new SqlTagDefinition("A", SqlTagModel.WideRow, "hist", ColumnName: "temp",
RowSelectorTopByTimestamp: "sample_ts", Writable: true, Write: new SqlWriteSpec(SqlWriteMode.Insert, true));
var plan = Plan(tag, new SqlServerDialect());
plan.SqlText.ShouldBe("INSERT INTO [hist] ([temp], [sample_ts]) VALUES (@v, @t)");
plan.ParameterBindNames.ShouldBe(["@v", "@t"]);
}
[Fact]
public void Upsert_sqlServer_isAHoldlockMerge()
{
var plan = Plan(KvTag(new SqlWriteSpec(SqlWriteMode.Upsert, true), ts: "ts"), new SqlServerDialect());
plan.SqlText.ShouldBe(
"MERGE INTO [plant].[sp] WITH (HOLDLOCK) AS tgt USING (SELECT 1 AS one) AS src ON tgt.[tag] = @k " +
"WHEN MATCHED THEN UPDATE SET [val] = @v, [ts] = @t " +
"WHEN NOT MATCHED THEN INSERT ([tag], [val], [ts]) VALUES (@k, @v, @t);");
plan.ParameterBindNames.ShouldBe(["@k", "@v", "@t"]);
plan.Parameters.ShouldBe(["L1", 5.5, Now]);
plan.MaxRowsAffected.ShouldBe(1);
}
[Fact]
public void Upsert_postgres_isInsertOnConflict()
=> Plan(KvTag(new SqlWriteSpec(SqlWriteMode.Upsert)), new PostgresDialect()).SqlText.ShouldBe(
"INSERT INTO \"plant\".\"sp\" (\"tag\", \"val\") VALUES (@k, @v) ON CONFLICT (\"tag\") DO UPDATE SET \"val\" = EXCLUDED.\"val\"");
[Fact]
public void Upsert_mySql_isOnDuplicateKeyUpdate_andAllowsTwoRows()
{
var plan = Plan(KvTag(new SqlWriteSpec(SqlWriteMode.Upsert)), new MySqlDialect());
plan.SqlText.ShouldBe("INSERT INTO `plant`.`sp` (`tag`, `val`) VALUES (@k, @v) ON DUPLICATE KEY UPDATE `val` = @v");
plan.MaxRowsAffected.ShouldBe(2);
}
[Fact]
public void Upsert_oracle_isAMergeFromDual_withNamespacedBinds()
{
var plan = Plan(KvTag(new SqlWriteSpec(SqlWriteMode.Upsert)), new OracleDialect());
plan.SqlText.ShouldBe(
"MERGE INTO \"plant\".\"sp\" tgt USING (SELECT 1 AS one FROM dual) src ON (tgt.\"tag\" = :p_k) " +
"WHEN MATCHED THEN UPDATE SET tgt.\"val\" = :p_v WHEN NOT MATCHED THEN INSERT (\"tag\", \"val\") VALUES (:p_k, :p_v)");
plan.ParameterBindNames.ShouldBe(["p_k", "p_v"]);
}
[Fact]
public void Upsert_andProcedure_onOdbc_areNotSupported()
{
SqlWritePlanner.TryPlan(KvTag(new SqlWriteSpec(SqlWriteMode.Upsert)), 1.0, new OdbcDialect(), Now, out _)
.ShouldBe(SqlStatusCodes.BadNotSupported);
SqlWritePlanner.TryPlan(KvTag(new SqlWriteSpec(SqlWriteMode.Procedure, Procedure: "p", ValueParameter: "value")),
1.0, new OdbcDialect(), Now, out _).ShouldBe(SqlStatusCodes.BadNotSupported);
}
private static SqlTagDefinition ProcTag(string? key = "TagName", string? ts = "Ts") =>
KvTag(new SqlWriteSpec(SqlWriteMode.Procedure, false, "dbo.SetSp", "Value", key, ts));
[Theory]
[InlineData(SqlProvider.SqlServer, "EXEC [dbo].[SetSp] @Value = @v, @TagName = @k, @Ts = @t")]
[InlineData(SqlProvider.Postgres, "CALL \"dbo\".\"SetSp\"(Value => @v, TagName => @k, Ts => @t)")]
[InlineData(SqlProvider.MySql, "CALL `dbo`.`SetSp`(@v, @k, @t)")]
[InlineData(SqlProvider.Oracle, "BEGIN \"dbo\".\"SetSp\"(Value => :p_v, TagName => :p_k, Ts => :p_t); END;")]
public void Procedure_callsByName_orPositionallyOnMySql_valueKeyStampInThatOrder(SqlProvider provider, string sql)
{
var plan = Plan(ProcTag(), SqlDialects.TryCreate(provider)!);
plan.SqlText.ShouldBe(sql);
plan.Parameters.ShouldBe([5.5, "L1", Now]);
plan.Mode.ShouldBe(SqlWriteMode.Procedure);
}
[Fact]
public void Procedure_bindsOnlyWhatTheBlockNames()
{
var plan = Plan(ProcTag(key: null, ts: null), new SqlServerDialect());
plan.SqlText.ShouldBe("EXEC [dbo].[SetSp] @Value = @v");
plan.Parameters.ShouldBe([5.5]);
}
[Fact]
public void AHostileValue_isBound_inEveryMode()
{
const string hostile = "x'); DROP TABLE sp; --";
foreach (var write in new[]
{
new SqlWriteSpec(SqlWriteMode.Insert), new SqlWriteSpec(SqlWriteMode.Upsert),
new SqlWriteSpec(SqlWriteMode.Procedure, false, "p", "value"),
})
{
var plan = Plan(KvTag(write) with { DeclaredType = DriverDataType.String }, new SqlServerDialect(), hostile);
plan.SqlText.ShouldNotContain("DROP");
plan.Parameters.ShouldContain(hostile);
}
}
// ---- catalog gate: the procedure is an identifier like any other ----
private static SqlCatalog Catalog(params string[] procedures) => new(
"dbo", ["dbo"],
new Dictionary<string, IReadOnlyList<string>>(StringComparer.Ordinal) { ["dbo"] = ["sp"] },
new Dictionary<string, IReadOnlyList<string>>(StringComparer.Ordinal) { ["dbo.sp"] = ["tag", "val"] },
new Dictionary<string, IReadOnlyList<string>>(StringComparer.Ordinal) { ["dbo"] = procedures });
private static SqlTagDefinition GateTag(string procedure) =>
new("A", SqlTagModel.KeyValue, "sp", KeyColumn: "tag", KeyValue: "L1", ValueColumn: "val", Writable: true,
Write: new SqlWriteSpec(SqlWriteMode.Procedure, false, procedure, "value"));
[Fact]
public void Gate_resolvesTheProcedure_toTheCatalogSpelling()
{
var result = SqlCatalogGate.Apply([GateTag("setsp")], Catalog("SetSp"), new SqlServerDialect());
result.Rejected.ShouldBeEmpty();
result.Accepted.ShouldHaveSingleItem().Write!.Procedure.ShouldBe("dbo.SetSp");
}
[Fact]
public void Gate_rejectsAnUnknownProcedure_byField()
{
var result = SqlCatalogGate.Apply([GateTag("Nope")], Catalog("SetSp"), new SqlServerDialect());
result.Accepted.ShouldBeEmpty();
var rejection = result.Rejected.ShouldHaveSingleItem();
rejection.Field.ShouldBe(SqlCatalogGate.ProcedureField);
rejection.Reason.ShouldContain("'Nope' does not exist");
}
[Fact]
public void Gate_checksAQueryTagsProcedure_too()
{
var query = new SqlTagDefinition("Q", SqlTagModel.Query, string.Empty, ColumnName: "c", QueryName: "q",
Writable: true, Write: new SqlWriteSpec(SqlWriteMode.Procedure, false, "Missing", "value"));
SqlCatalogGate.Apply([query], Catalog("SetSp"), new SqlServerDialect()).Rejected.ShouldHaveSingleItem();
SqlCatalogGate.Apply([query with { Write = query.Write! with { Procedure = "SetSp" } }], Catalog("SetSp"),
new SqlServerDialect()).Accepted.ShouldHaveSingleItem().Write!.Procedure.ShouldBe("dbo.SetSp");
}
[Fact]
public void Gate_refusesAProcedure_onADialectWithNoRoutineCatalog()
=> SqlCatalogGate.Apply([GateTag("SetSp")], Catalog("SetSp"), new OdbcDialect())
.Rejected.ShouldHaveSingleItem().Reason.ShouldContain("no stored-procedure catalog");
// ---- failure classification → status ----
[Theory]
[InlineData("23505", SqlWriteFailure.UniqueViolation)]
[InlineData("23502", SqlWriteFailure.IntegrityViolation)]
[InlineData("23000", SqlWriteFailure.IntegrityViolation)]
[InlineData("22003", SqlWriteFailure.DataException)]
[InlineData("42501", SqlWriteFailure.Other)] // insufficient privilege stays a communication error
[InlineData(null, SqlWriteFailure.Other)]
public void SqlState_classification(string? sqlState, SqlWriteFailure expected)
=> SqlWriteFailures.FromSqlState(sqlState).ShouldBe(expected);
[Theory]
[InlineData(SqlWriteFailure.UniqueViolation, 0x809F0000u)] // BadEntryExists
[InlineData(SqlWriteFailure.IntegrityViolation, 0x803C0000u)] // BadOutOfRange
[InlineData(SqlWriteFailure.DataException, 0x803C0000u)]
[InlineData(SqlWriteFailure.Other, 0x80050000u)] // BadCommunicationError
public void Failure_mapsToTheDocumentedStatus(SqlWriteFailure failure, uint status)
=> SqlDriver.MapWriteFailure(failure).ShouldBe(status);
[Fact]
public void AnUnrelatedException_isNeverAConstraint_onAnyDialect()
{
foreach (var provider in Enum.GetValues<SqlProvider>())
SqlDialects.TryCreate(provider)!.ClassifyWriteFailure(new InvalidOperationException()).ShouldBe(SqlWriteFailure.Other);
}
// ---- end to end over SQLite ----
private const string Setpoints = "Setpoints";
private static SqlitePollFixture SetpointFixture()
{
var fixture = new SqlitePollFixture();
fixture.Execute($"CREATE TABLE {Setpoints} (tag TEXT NOT NULL PRIMARY KEY, sp REAL NOT NULL, ts TEXT NULL)");
fixture.Execute($"INSERT INTO {Setpoints} VALUES ('Present', 1.0, NULL)");
return fixture;
}
private static string SpTag(string key, string write) => $$$"""
{"model":"KeyValue","table":"{{{Setpoints}}}","keyColumn":"tag","keyValue":"{{{key}}}","valueColumn":"sp",
"timestampColumn":"ts","type":"Float64","writable":true,"write":{{{write}}}}
""";
[Fact]
public async Task Insert_addsANewRow_andASecondInsertOfTheKey_isBadEntryExists()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture, Entry("New", SpTag("New", """{"mode":"Insert"}""")));
(await WriteAsync(driver, "New", 7.5)).ShouldBe(SqlStatusCodes.Good);
Scalar(fixture, "SELECT sp FROM Setpoints WHERE tag = 'New'").ShouldBe(7.5);
(await WriteAsync(driver, "New", 8.5)).ShouldBe(SqlStatusCodes.BadEntryExists);
Scalar(fixture, "SELECT sp FROM Setpoints WHERE tag = 'New'").ShouldBe(7.5);
}
[Fact]
public async Task Insert_violatingNotNull_isBadOutOfRange_andCommitsNothing()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture, Entry("New", SpTag("New", """{"mode":"Insert"}""")));
(await WriteAsync(driver, "New", null)).ShouldBe(SqlStatusCodes.BadOutOfRange);
Scalar(fixture, "SELECT COUNT(*) FROM Setpoints").ShouldBe(1.0);
}
[Fact]
public async Task Upsert_insertsAnAbsentKey_andUpdatesAPresentOne()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture,
Entry("Absent", SpTag("Absent", """{"mode":"Upsert"}""")),
Entry("Present", SpTag("Present", """{"mode":"Upsert"}""")));
(await WriteAsync(driver, "Absent", 3.0)).ShouldBe(SqlStatusCodes.Good);
(await WriteAsync(driver, "Present", 4.0)).ShouldBe(SqlStatusCodes.Good);
Scalar(fixture, "SELECT sp FROM Setpoints WHERE tag = 'Absent'").ShouldBe(3.0);
Scalar(fixture, "SELECT sp FROM Setpoints WHERE tag = 'Present'").ShouldBe(4.0);
Scalar(fixture, "SELECT COUNT(*) FROM Setpoints").ShouldBe(2.0);
}
/// <summary>The same absent key under the default Update is BadNoData and inserts nothing — the back-compat pin.</summary>
[Fact]
public async Task Update_toAnAbsentKey_isStillBadNoData()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture, Entry("Absent", SpTag("Absent", """{"mode":"Update"}""")));
(await WriteAsync(driver, "Absent", 3.0)).ShouldBe(SqlStatusCodes.BadNoData);
Scalar(fixture, "SELECT COUNT(*) FROM Setpoints").ShouldBe(1.0);
}
[Fact]
public async Task StampTimestamp_setsTheTimestampColumn_toTheWriteTime_andWithoutItTheColumnIsUntouched()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture,
Entry("Stamped", SpTag("Present", """{"mode":"Update","stampTimestamp":true}""")));
var before = DateTime.UtcNow.AddSeconds(-1);
(await WriteAsync(driver, "Stamped", 9.0)).ShouldBe(SqlStatusCodes.Good);
using var command = fixture.Connection.CreateCommand();
command.CommandText = "SELECT ts FROM Setpoints WHERE tag = 'Present'";
var stamped = DateTime.Parse((string)command.ExecuteScalar()!, CultureInfo.InvariantCulture,
DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal);
stamped.ShouldBeGreaterThan(before);
stamped.ShouldBeLessThan(DateTime.UtcNow.AddSeconds(1));
}
[Fact]
public async Task Procedure_onADialectWithNoRoutineCatalog_isRejectedByTheGate_notExecuted()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture,
Entry("Proc", SpTag("Present", """{"mode":"Procedure","procedure":"SetSp"}""")));
(await WriteAsync(driver, "Proc", 2.0)).ShouldBe(SqlStatusCodes.BadNodeIdUnknown);
Scalar(fixture, "SELECT sp FROM Setpoints WHERE tag = 'Present'").ShouldBe(1.0);
}
[Fact]
public async Task Discover_advertisesOperate_forAnInsertOnANewestRowTag()
{
using var fixture = SetpointFixture();
await using var driver = await StartAsync(fixture, Entry("Append", $$$"""
{"model":"WideRow","table":"{{{SqlitePollFixture.WideRowTable}}}","columnName":"oven_temp",
"rowSelector":{"topByTimestamp":"sample_ts"},"writable":true,"write":{"mode":"Insert","stampTimestamp":true}}
"""));
var builder = new Capture();
await driver.DiscoverAsync(builder, CancellationToken.None);
builder.Classes["Append"].ShouldBe(SecurityClassification.Operate);
}
// ---- helpers ----
private static RawTagEntry Entry(string rawPath, string json) => new(rawPath, json, WriteIdempotent: false);
private static async Task<uint> WriteAsync(SqlDriver driver, string reference, object? value)
=> (await ((IWritable)driver).WriteAsync([new WriteRequest(reference, value)], CancellationToken.None))
.ShouldHaveSingleItem().StatusCode;
private static double Scalar(SqlitePollFixture fixture, string sql)
{
using var command = fixture.Connection.CreateCommand();
command.CommandText = sql;
return Convert.ToDouble(command.ExecuteScalar(), CultureInfo.InvariantCulture);
}
private static async Task<SqlDriver> StartAsync(SqlitePollFixture fixture, params RawTagEntry[] tags)
{
var driver = new SqlDriver(
new SqlDriverOptions
{
RawTags = tags,
OperationTimeout = TimeSpan.FromSeconds(15),
CommandTimeout = TimeSpan.FromSeconds(10),
AllowWrites = true,
},
"sql-write-modes", new SqliteDialect(), fixture.ConnectionString, fixture.Factory);
await driver.InitializeAsync("{}", CancellationToken.None);
return driver;
}
private sealed class Capture : IAddressSpaceBuilder
{
public Dictionary<string, SecurityClassification> Classes { get; } = [];
public IAddressSpaceBuilder Folder(string browseName, string displayName) => this;
public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo)
{
Classes[attributeInfo.FullName] = attributeInfo.SecurityClass;
return new Handle(attributeInfo.FullName);
}
public void AddProperty(string browseName, DriverDataType dataType, object? value) { }
private sealed class Handle(string fullReference) : IVariableHandle
{
public string FullReference => fullReference;
public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) => new Sink();
private sealed class Sink : IAlarmConditionSink
{
public void OnTransition(AlarmEventArgs args) { }
}
}
}
}
@@ -200,4 +200,28 @@ public sealed class SqliteDialect : ISqlDialect
_ => DriverDataType.String,
};
}
// ---- writes (lmxopcua#781) — SQLite stands in for a named-marker backend with a PostgreSQL-shaped upsert ----
/// <inheritdoc />
// Provider is Odbc (a stand-in), whose shared table refuses Upsert; SQLite itself upserts, so the end-to-end
// upsert suite runs offline. Procedure stays refused — SQLite has none.
public bool SupportsWriteMode(SqlWriteMode mode) => mode is SqlWriteMode.Update or SqlWriteMode.Insert or SqlWriteMode.Upsert;
/// <inheritdoc />
public string? UpsertSql(
string quotedTable, string quotedKeyColumn, string keyMarker,
IReadOnlyList<(string QuotedColumn, string Marker)> assignments)
=> string.Concat(
"INSERT INTO ", quotedTable, " (", quotedKeyColumn, ", ", string.Join(", ", assignments.Select(a => a.QuotedColumn)),
") VALUES (", keyMarker, ", ", string.Join(", ", assignments.Select(a => a.Marker)),
") ON CONFLICT (", quotedKeyColumn, ") DO UPDATE SET ",
string.Join(", ", assignments.Select(a => a.QuotedColumn + " = excluded." + a.QuotedColumn)));
/// <inheritdoc />
// SQLITE_CONSTRAINT (19): extended 2067 UNIQUE / 1555 PRIMARYKEY ⇒ unique; any other constraint ⇒ integrity.
public SqlWriteFailure ClassifyWriteFailure(Exception exception)
=> exception is SqliteException { SqliteErrorCode: 19 } sqlite
? sqlite.SqliteExtendedErrorCode is 2067 or 1555 ? SqlWriteFailure.UniqueViolation : SqlWriteFailure.IntegrityViolation
: SqlWriteFailure.Other;
}