feat(data): add migrations, repositories and TitanoDatabase facade

Embedded per-dialect migrations applied in one transaction and recorded
in schema_migrations (advisory lock on PostgreSQL, newer schemas
refused). Schema for every BRIEF section 5 entity plus import history and
uploads. Hand-written repositories for archives, sequences (filters,
keyset paging, Archive statistics), frames (bulk insert and updates),
renders, jobs (exclusive claiming, checkpoints, crash recovery), media
cards, users, tokens, render nodes, settings, tags, audit and uploads.
TitanoDatabase opens, migrates and exposes them, also bound to a
transaction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 10:05:43 +00:00
1 parent 14567ecac3
commit 8d93abd65b
18 files changed
+2334

No files matched your search

@@ -0,0 +1,157 @@
using System.Text;
using Titano.Core.Imaging;
using Titano.Core.Model;
namespace Titano.Data.Repositories;
/// <summary>Light statistics of one frame, written by the analysis job.</summary>
public readonly record struct FrameLightStats(Guid FrameId, double? MeanLogLuminance, double? ClipLow, double? ClipHigh);
/// <summary>Frames of sequences: bulk import, paged listing, duplicate lookup and bulk updates.</summary>
public sealed class FrameRepository
{
private static readonly string[] ColumnNames =
[
"id", "sequence_id", "idx", "relative_path", "file_name", "original_file_name", "size", "sha256", "captured_at",
"utc_offset_minutes", "timestamp_source", "exposure_time", "f_number", "iso", "focal_length", "exposure_bias",
"white_balance", "orientation", "width", "height", "format", "preview_offset", "preview_length",
"mean_log_luminance", "clip_low", "clip_high", "flags",
];
private static readonly string Columns = string.Join(", ", ColumnNames);
private static readonly string InsertSql =
$"INSERT INTO frames ({Columns}) VALUES ({string.Join(", ", ColumnNames.Select((_, i) => "$" + (i + 1)))})";
/// <summary>Rows per statement of the batched PostgreSQL updates (4 or fewer parameters per row).</summary>
private const int Batch = 1000;
private readonly DbAccess _db;
internal FrameRepository(DbAccess db) => _db = db;
public async Task InsertAsync(Frame frame, CancellationToken cancellationToken = default) =>
await _db.ExecuteAsync(InsertSql, Array.ConvertAll(Values(frame), v => new DbParam(v)), cancellationToken).ConfigureAwait(false);
/// <summary>Inserts many frames at once (COPY on PostgreSQL, batched INSERTs in one transaction on SQLite).</summary>
public Task<long> BulkInsertAsync(IEnumerable<Frame> frames, CancellationToken cancellationToken = default) =>
_db.RunAsync(session => session.BulkInsertAsync("frames", ColumnNames, frames.Select(Values).ToAsyncEnumerable(), cancellationToken), cancellationToken);
public Task<Frame?> GetAsync(Guid id, CancellationToken cancellationToken = default) =>
_db.SingleAsync($"SELECT {Columns} FROM frames WHERE id = $1", [id], Map, cancellationToken);
/// <summary>Frames of a sequence by index, starting after <paramref name="afterIndex"/> (keyset paging).</summary>
public Task<IReadOnlyList<Frame>> ListBySequenceAsync(Guid sequenceId, int afterIndex = -1, int limit = 1000, CancellationToken cancellationToken = default) =>
_db.ListAsync($"SELECT {Columns} FROM frames WHERE sequence_id = $1 AND idx > $2 ORDER BY idx LIMIT $3",
[sequenceId, afterIndex, Cursor.ClampLimit(limit)], Map, cancellationToken);
/// <summary>Every frame with this content hash (duplicate detection, upload short-circuit).</summary>
public Task<IReadOnlyList<Frame>> FindBySha256Async(string sha256, CancellationToken cancellationToken = default) =>
_db.ListAsync($"SELECT {Columns} FROM frames WHERE sha256 = $1 ORDER BY sequence_id, idx", [sha256.ToLowerInvariant()], Map, cancellationToken);
/// <summary>Writes analysis results for many frames in one transaction; returns the number of frames updated.</summary>
public Task<int> UpdateLightStatsAsync(IReadOnlyList<FrameLightStats> stats, CancellationToken cancellationToken = default) =>
_db.InTransactionAsync(async session =>
{
var updated = 0;
if (_db.Sql.IsPostgres)
{
// One UPDATE … FROM (VALUES …) per batch instead of a round trip per frame.
for (var start = 0; start < stats.Count; start += Batch)
{
var count = Math.Min(Batch, stats.Count - start);
var sql = new StringBuilder("UPDATE frames AS f SET mean_log_luminance = v.m, clip_low = v.lo, clip_high = v.hi FROM (VALUES ");
var args = new DbParam[count * 4];
for (var i = 0; i < count; i++)
{
var s = stats[start + i];
sql.Append(i > 0 ? ", (" : "(").Append('$').Append(4 * i + 1).Append(", $").Append(4 * i + 2)
.Append(", $").Append(4 * i + 3).Append(", $").Append(4 * i + 4).Append(')');
args[4 * i] = s.FrameId;
args[4 * i + 1] = s.MeanLogLuminance;
args[4 * i + 2] = s.ClipLow;
args[4 * i + 3] = s.ClipHigh;
}
sql.Append(") AS v(id, m, lo, hi) WHERE f.id = v.id");
updated += await session.ExecuteAsync(sql.ToString(), args, cancellationToken).ConfigureAwait(false);
}
}
else
{
foreach (var s in stats)
{
updated += await session.ExecuteAsync(
"UPDATE frames SET mean_log_luminance = $2, clip_low = $3, clip_high = $4 WHERE id = $1",
[s.FrameId, s.MeanLogLuminance, s.ClipLow, s.ClipHigh], cancellationToken).ConfigureAwait(false);
}
}
return updated;
}, cancellationToken);
/// <summary>Sets and clears flags on many frames in one transaction; returns the number of frames updated.</summary>
public Task<int> UpdateFlagsAsync(IReadOnlyList<Guid> frameIds, FrameFlags set, FrameFlags clear, CancellationToken cancellationToken = default) =>
_db.InTransactionAsync(async session =>
{
// 500 ids per statement stays below SQLite's historical 999-variable limit.
const int idsPerStatement = 500;
var updated = 0;
for (var start = 0; start < frameIds.Count; start += idsPerStatement)
{
var count = Math.Min(idsPerStatement, frameIds.Count - start);
var args = new DbParam[count + 2];
args[0] = (int)set;
args[1] = (int)clear;
var placeholders = new StringBuilder();
for (var i = 0; i < count; i++)
{
args[i + 2] = frameIds[start + i];
placeholders.Append(i > 0 ? ", $" : "$").Append(i + 3);
}
updated += await session.ExecuteAsync($"UPDATE frames SET flags = (flags | $1) & ~$2 WHERE id IN ({placeholders})",
args, cancellationToken).ConfigureAwait(false);
}
return updated;
}, cancellationToken);
/// <summary>Removes every frame of a sequence; returns how many.</summary>
public Task<int> DeleteBySequenceAsync(Guid sequenceId, CancellationToken cancellationToken = default) =>
_db.ExecuteAsync("DELETE FROM frames WHERE sequence_id = $1", [sequenceId], cancellationToken);
private static object?[] Values(Frame f) =>
[
f.Id, f.SequenceId, f.Index, f.RelativePath, f.FileName, f.OriginalFileName, f.Size, f.Sha256?.ToLowerInvariant(),
SequenceRepository.Wall(f.CapturedAt), f.UtcOffsetMinutes, (int)f.TimestampSource, f.ExposureTime, f.FNumber, f.Iso,
f.FocalLength, f.ExposureBias, f.WhiteBalance, f.Orientation, f.Width, f.Height, (int)f.Format, f.PreviewOffset,
f.PreviewLength, f.MeanLogLuminance, f.ClipLow, f.ClipHigh, (int)f.Flags,
];
private static Frame Map(DbRow r) => new()
{
Id = r.GetGuid(0),
SequenceId = r.GetGuid(1),
Index = r.GetInt32(2),
RelativePath = r.GetString(3),
FileName = r.GetString(4),
OriginalFileName = r.GetStringOrNull(5),
Size = r.GetInt64(6),
Sha256 = r.GetStringOrNull(7),
CapturedAt = r.GetDateTimeOrNull(8),
UtcOffsetMinutes = r.GetInt32OrNull(9),
TimestampSource = (TimestampSource)r.GetInt32(10),
ExposureTime = r.GetDoubleOrNull(11),
FNumber = r.GetDoubleOrNull(12),
Iso = r.GetInt32OrNull(13),
FocalLength = r.GetDoubleOrNull(14),
ExposureBias = r.GetDoubleOrNull(15),
WhiteBalance = r.GetInt32OrNull(16),
Orientation = r.GetInt32(17),
Width = r.GetInt32(18),
Height = r.GetInt32(19),
Format = (ImageFileFormat)r.GetInt32(20),
PreviewOffset = r.GetInt64OrNull(21),
PreviewLength = r.GetInt64OrNull(22),
MeanLogLuminance = r.GetDoubleOrNull(23),
ClipLow = r.GetDoubleOrNull(24),
ClipHigh = r.GetDoubleOrNull(25),
Flags = (FrameFlags)r.GetInt32(26),
};
}