Merge pull request #74 from tgiachi/develop

release: persistence and database seeders (0.27.0)

Author: tgiachi

samples/SquidStd.Samples.Persistence/Program.cs

@@ -32,7 +32,7 @@ IPersistenceService BuildPersistence()
     return new PersistenceService(registry, journal, snapshot, config);
 }
 
-#region step-1: load existing state (snapshot + journal replay)
+#region step-1
 
 var persistence = BuildPersistence();
 await persistence.InitializeAsync();
@@ -48,7 +48,7 @@ IPersistenceService BuildPersistence()
 
 #endregion
 
-#region step-2: mutate — every upsert/remove is appended to the journal
+#region step-2
 
 var nextId = await players.CountAsync() + 1;
 await players.UpsertAsync(new() { Id = nextId, Name = $"Hero-{nextId}", Level = nextId * 10 });
@@ -57,7 +57,7 @@ IPersistenceService BuildPersistence()
 
 #endregion
 
-#region step-3: snapshot — capture full state and trim the journal
+#region step-3
 
 await persistence.SaveSnapshotAsync();
 Console.WriteLine("Snapshot saved. Re-run this sample to see the state reload.");

src/SquidStd.Database/Data/Internal/DatabaseSeederRegistration.cs

@@ -0,0 +1,10 @@
+using DryIoc;
+using SquidStd.Database.Interfaces.Seeding;
+
+namespace SquidStd.Database.Data.Internal;
+
+/// <summary>
+/// A declarative database-seeder registration; the resolver runs when the database service is
+/// constructed.
+/// </summary>
+public sealed record DatabaseSeederRegistration(Func<IResolverContext, IDatabaseSeeder> Resolve);

src/SquidStd.Database/Data/Internal/SeedHistoryEntity.cs

@@ -0,0 +1,17 @@
+using FreeSql.DataAnnotations;
+
+namespace SquidStd.Database.Data.Internal;
+
+/// <summary>
+/// History row recording an applied database seeder.
+/// </summary>
+[Table(Name = "__squidstd_seed_history")]
+public sealed class SeedHistoryEntity
+{
+    /// <summary>The unique seeder name.</summary>
+    [Column(IsPrimary = true, StringLength = 256)]
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>UTC timestamp of the successful run.</summary>
+    public DateTime AppliedAt { get; set; }
+}

src/SquidStd.Database/Extensions/RegisterDatabaseExtension.cs

@@ -1,10 +1,14 @@
 using DryIoc;
 using SquidStd.Abstractions.Extensions.Config;
+using SquidStd.Abstractions.Extensions.Container;
 using SquidStd.Abstractions.Extensions.Services;
 using SquidStd.Database.Abstractions.Data.Database;
 using SquidStd.Database.Abstractions.Interfaces.Data;
 using SquidStd.Database.Data;
+using SquidStd.Database.Data.Internal;
+using SquidStd.Database.Interfaces.Seeding;
 using SquidStd.Database.Interfaces.Services;
+using SquidStd.Database.Internal;
 using SquidStd.Database.Services;
 
 namespace SquidStd.Database.Extensions;
@@ -17,6 +21,41 @@ public static class RegisterDatabaseExtension
     /// <param name="container">The DI container.</param>
     extension(IContainer container)
     {
+        /// <summary>
+        /// Registers a database seeder by type; it is resolved from the container when the
+        /// database service is constructed and runs once ever per its Name.
+        /// </summary>
+        /// <typeparam name="TSeeder">The seeder type.</typeparam>
+        /// <returns>The same container for chaining.</returns>
+        public IContainer RegisterDatabaseSeeder<TSeeder>()
+            where TSeeder : class, IDatabaseSeeder
+        {
+            container.Register<TSeeder>(Reuse.Singleton);
+            container.AddToRegisterTypedList(
+                new DatabaseSeederRegistration(static resolver => resolver.Resolve<TSeeder>())
+            );
+
+            return container;
+        }
+
+        /// <summary>
+        /// Registers a delegate-backed database seeder that runs once ever per
+        /// <paramref name="name" />.
+        /// </summary>
+        /// <param name="name">Unique, stable seeder name recorded in the history table.</param>
+        /// <param name="seed">The seeding callback.</param>
+        /// <returns>The same container for chaining.</returns>
+        public IContainer RegisterDatabaseSeeder(string name, Func<IDatabaseService, CancellationToken, ValueTask> seed)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(name);
+            ArgumentNullException.ThrowIfNull(seed);
+            container.AddToRegisterTypedList(
+                new DatabaseSeederRegistration(_ => new DelegateDatabaseSeeder(name, seed))
+            );
+
+            return container;
+        }
+
         /// <summary>
         /// Registers the database config section, the database service, and the open-generic data access.
         /// </summary>
@@ -27,6 +66,18 @@ public IContainer RegisterDatabase()
             container.RegisterStdService<IDatabaseService, DatabaseService>();
             container.Register(typeof(IDataAccess<>), typeof(FreeSqlDataAccess<>), Reuse.Transient);
 
+            container.RegisterDelegate<IReadOnlyList<IDatabaseSeeder>>(
+                static resolver =>
+                {
+                    var recorded = resolver.Resolve<List<DatabaseSeederRegistration>>(IfUnresolved.ReturnDefault);
+
+                    return recorded is null
+                               ? []
+                               : recorded.Select(registration => registration.Resolve(resolver)).ToList();
+                },
+                Reuse.Singleton
+            );
+
             return container;
         }
     }

src/SquidStd.Database/Interfaces/Seeding/IDatabaseSeeder.cs

@@ -0,0 +1,23 @@
+using SquidStd.Database.Interfaces.Services;
+
+namespace SquidStd.Database.Interfaces.Seeding;
+
+/// <summary>
+/// Seeds initial database data. Each seeder runs once ever per unique <see cref="Name" />,
+/// tracked in the __squidstd_seed_history table; the history row is written only after a
+/// successful run, so a failed seeder retries at the next start. A seeder exception aborts
+/// startup. Retries happen at the next process start: a service instance whose start failed
+/// is not restartable. The seed and its history row are not wrapped in a transaction, so a
+/// seeder should tolerate running again over data it already wrote. Use case-distinct names:
+/// the duplicate check is ordinal, while the history lookup follows the database collation.
+/// </summary>
+public interface IDatabaseSeeder
+{
+    /// <summary>Unique, stable seeder name recorded in the history table.</summary>
+    string Name { get; }
+
+    /// <summary>Writes the seed data through the ORM.</summary>
+    /// <param name="database">The started database service.</param>
+    /// <param name="cancellationToken">Token used to cancel the seeding.</param>
+    ValueTask SeedAsync(IDatabaseService database, CancellationToken cancellationToken = default);
+}

src/SquidStd.Database/Internal/DelegateDatabaseSeeder.cs

@@ -0,0 +1,25 @@
+using SquidStd.Database.Interfaces.Seeding;
+using SquidStd.Database.Interfaces.Services;
+
+namespace SquidStd.Database.Internal;
+
+/// <summary>
+/// Adapts a seeding delegate to <see cref="IDatabaseSeeder" /> so
+/// <c>RegisterDatabaseSeeder(Func{IDatabaseService,CancellationToken,ValueTask})</c> can record
+/// it alongside class-based seeders.
+/// </summary>
+internal sealed class DelegateDatabaseSeeder : IDatabaseSeeder
+{
+    private readonly Func<IDatabaseService, CancellationToken, ValueTask> _seed;
+
+    public string Name { get; }
+
+    public DelegateDatabaseSeeder(string name, Func<IDatabaseService, CancellationToken, ValueTask> seed)
+    {
+        Name = name;
+        _seed = seed;
+    }
+
+    public ValueTask SeedAsync(IDatabaseService database, CancellationToken cancellationToken = default)
+        => _seed(database, cancellationToken);
+}

src/SquidStd.Database/README.md

@@ -37,6 +37,78 @@ var page = await users.GetPagedAsync(page: 1, pageSize: 20, orderBy: u => u.Name
 | `ConnectionStringParser`     | URI → provider + native connection string.                          |
 | `ZLinqResultExtensions`      | Zero-alloc in-memory result helpers.                                |
 
+## Seeding
+
+Seeders populate initial database data once per seeder name. Each seeder's name is tracked in the
+`__squidstd_seed_history` table; a seeder runs only if its name does not yet exist in the history. The
+history row is written only after a successful run - if a seeder throws, it is retried at the next
+process start. A seeder exception aborts startup (fail-fast). The seed and history row are not wrapped
+in a transaction, so a seeder should tolerate running again over data it already wrote.
+
+The history table is created during database service start when at least one seeder is registered,
+independent of whether `AutoMigrate` is on or off. Seeder names must be unique; the startup duplicate
+check is ordinal (case-sensitive), while the history-table lookup for a given seeder's name follows
+the database's collation.
+
+### Delegate seeder
+
+Register an inline seeding callback with a unique name:
+
+```csharp
+bootstrap.ConfigureServices(c =>
+{
+    c.RegisterDatabase();  // binds "database" config, runs seeders after init
+    
+    // Inline delegate seeder
+    c.RegisterDatabaseSeeder("accounts.admin", async (database, ct) =>
+    {
+        await database.Orm.Insert(new User { Id = 1, Name = "Admin" }).ExecuteAffrowsAsync(ct);
+    });
+    
+    return c;
+});
+```
+
+### Class seeder
+
+Implement `IDatabaseSeeder` (which provides the name) and register it by type:
+
+```csharp
+public sealed class AdminAccountSeeder : IDatabaseSeeder
+{
+    public string Name => "accounts.admin";
+    
+    public async ValueTask SeedAsync(IDatabaseService database, CancellationToken cancellationToken = default)
+    {
+        await database.Orm.Insert(new User { Id = 1, Name = "Admin" }).ExecuteAffrowsAsync(cancellationToken);
+    }
+}
+
+bootstrap.ConfigureServices(c =>
+{
+    c.RegisterDatabase();
+    c.RegisterDatabaseSeeder<AdminAccountSeeder>();
+    
+    return c;
+});
+```
+
+### Key semantics
+
+- **Run-once per name**: The `__squidstd_seed_history` table tracks which seeders have successfully run.
+  A seeder is skipped if its name already exists in the history.
+- **Failed-seeder retry**: The history row is written only after the seeder succeeds. If a seeder throws,
+  the row is not written, and the seeder retries at the next process start.
+- **History table creation**: The table is created during database service start when at least one seeder
+  is registered (this is what triggers `RunSeedersAsync`), independent of whether `AutoMigrate` is on or
+  off. Its schema is internal to SquidStd and should not be modified.
+- **Duplicate name check**: Seeder names must be unique. Duplicate names (ordinal, case-sensitive match)
+  are detected at startup and cause an exception.
+- **Execution order**: Seeders run in registration order. Multiple seeders can be registered via chained
+  `RegisterDatabaseSeeder()` calls.
+- **No transaction wrap**: The seed and its history row are not wrapped in a transaction. Seeders should
+  be idempotent or accept re-running over partially-written state.
+
 ## Related
 
 - Tutorial: [Database](https://tgiachi.github.io/squid-std/tutorials/database.html)

src/SquidStd.Database/Services/DatabaseService.cs

@@ -4,6 +4,8 @@
 using SquidStd.Database.Abstractions.Types.Data;
 using SquidStd.Core.Directories;
 using SquidStd.Database.Connection;
+using SquidStd.Database.Data.Internal;
+using SquidStd.Database.Interfaces.Seeding;
 using SquidStd.Database.Interfaces.Services;
 
 namespace SquidStd.Database.Services;
@@ -17,6 +19,7 @@ public sealed class DatabaseService : IDatabaseService
 
     private readonly DatabaseConfig _config;
     private readonly DirectoriesConfig _directories;
+    private readonly IReadOnlyList<IDatabaseSeeder> _seeders;
     private IFreeSql? _orm;
     private int _started;
 
@@ -28,20 +31,25 @@ public sealed class DatabaseService : IDatabaseService
     /// </summary>
     /// <param name="config">The database configuration section.</param>
     /// <param name="directories">The directories configuration, providing the root directory.</param>
-    public DatabaseService(DatabaseConfig config, DirectoriesConfig directories)
+    /// <param name="seeders">
+    /// Optional seeders run once ever, in order, right after the FreeSql instance is built in
+    /// <see cref="StartAsync" />; applied names are tracked in the __squidstd_seed_history table.
+    /// </param>
+    public DatabaseService(DatabaseConfig config, DirectoriesConfig directories, IReadOnlyList<IDatabaseSeeder>? seeders = null)
     {
         _config = config;
         _directories = directories;
+        _seeders = seeders ?? [];
     }
 
     /// <inheritdoc />
-    public ValueTask StartAsync(CancellationToken cancellationToken = default)
+    public async ValueTask StartAsync(CancellationToken cancellationToken = default)
     {
         cancellationToken.ThrowIfCancellationRequested();
 
         if (Interlocked.Exchange(ref _started, 1) != 0)
         {
-            return ValueTask.CompletedTask;
+            return;
         }
 
         var parsed = ConnectionStringParser.Parse(_config.ConnectionString, _directories.Root);
@@ -67,13 +75,49 @@ public ValueTask StartAsync(CancellationToken cancellationToken = default)
         _orm.Aop.SyncStructureAfter += (_, e) =>
                                            Logger.Verbose("Migrated {Entities} -> {Sql}", e.EntityTypes, e.Sql);
 
+        if (_seeders.Count > 0)
+        {
+            await RunSeedersAsync(cancellationToken);
+        }
+
         Logger.Information(
             "Database service started ({Provider}, autoMigrate={AutoMigrate})",
             parsed.Provider,
             _config.AutoMigrate
         );
+    }
 
-        return ValueTask.CompletedTask;
+    private async ValueTask RunSeedersAsync(CancellationToken cancellationToken)
+    {
+        var duplicate = _seeders.GroupBy(seeder => seeder.Name, StringComparer.Ordinal)
+                                .FirstOrDefault(group => group.Count() > 1);
+
+        if (duplicate is not null)
+        {
+            throw new InvalidOperationException($"Duplicate database seeder name '{duplicate.Key}'.");
+        }
+
+        // The history table must exist even when AutoMigrate is off.
+        Orm.CodeFirst.SyncStructure<SeedHistoryEntity>();
+
+        foreach (var seeder in _seeders)
+        {
+            var applied = await Orm.Select<SeedHistoryEntity>()
+                                   .Where(entry => entry.Name == seeder.Name)
+                                   .AnyAsync(cancellationToken);
+
+            if (applied)
+            {
+                Logger.Debug("Database seeder {Seeder:l} already applied; skipping", seeder.Name);
+
+                continue;
+            }
+
+            await seeder.SeedAsync(this, cancellationToken);
+            await Orm.Insert(new SeedHistoryEntity { Name = seeder.Name, AppliedAt = DateTime.UtcNow })
+                     .ExecuteAffrowsAsync(cancellationToken);
+            Logger.Information("Database seeder {Seeder:l} applied", seeder.Name);
+        }
     }
 
     /// <inheritdoc />

src/SquidStd.Persistence.Abstractions/Interfaces/Persistence/IPersistenceSeeder.cs

@@ -0,0 +1,19 @@
+namespace SquidStd.Persistence.Abstractions.Interfaces.Persistence;
+
+/// <summary>
+/// Seeds initial data into a fresh persistence store. Seeders run after the snapshot load and
+/// journal replay, only when the save is brand new (no snapshot and no journal existed), in
+/// registration order. Seed writes go through the normal entity stores, so subsequent boots
+/// are no longer fresh and seeders never run again. A seeder exception aborts startup.
+/// If an earlier seeder's writes reach the journal before a later seeder fails, the save is no longer fresh at the next boot and the remaining seeders never run - prefer a single seeder, or make the set safe to lose a tail.
+/// A seeder that performs no writes leaves the save fresh, so it runs again at every boot.
+/// Class-form seeders must not constructor-inject IPersistenceService (circular resolution);
+/// use the SeedAsync parameter instead.
+/// </summary>
+public interface IPersistenceSeeder
+{
+    /// <summary>Writes the seed data through the normal entity stores.</summary>
+    /// <param name="persistence">The started persistence service.</param>
+    /// <param name="cancellationToken">Token used to cancel the seeding.</param>
+    ValueTask SeedAsync(IPersistenceService persistence, CancellationToken cancellationToken = default);
+}

src/SquidStd.Persistence/Data/Internal/PersistenceSeederRegistration.cs

@@ -0,0 +1,10 @@
+using DryIoc;
+using SquidStd.Persistence.Abstractions.Interfaces.Persistence;
+
+namespace SquidStd.Persistence.Data.Internal;
+
+/// <summary>
+/// A declarative persistence-seeder registration; the resolver runs when the persistence
+/// service is constructed.
+/// </summary>
+public sealed record PersistenceSeederRegistration(Func<IResolverContext, IPersistenceSeeder> Resolve);