Interface IGuildUpdateService

Namespace

FishMMO.Database.Npgsql.Services.Interfaces

Assembly

FishMMO-DB.dll

Service interface for guild update timestamp tracking. Provides async methods for persisting, deleting, and fetching guild update records.

public interface IGuildUpdateService

Remarks

Write operations (Persist*, Delete*) are executed through BaseService<TEntity> wrappers, which provide consistent retry and error mapping behavior for transient database failures.

All methods return DatabaseResult or DatabaseResult<T> to provide structured error information through the DatabaseException system, helping distinguish between: - Validation failures (invalid parameters) - Not found scenarios (guild doesn't exist) - Database errors (connection issues, constraint violations, timeouts) - Entity not found errors - Unexpected runtime errors

PersistAsync uses a single-statement UPSERT to prevent race conditions during concurrent updates.

Methods

DeleteAsync(long, CancellationToken)

Deletes all update records for a guild.

Task<DatabaseResult<int>> DeleteAsync(long guildId, CancellationToken cancellationToken = default)

Parameters

guildId long

Guild ID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<int>>

A DatabaseResult<T> containing the number of records deleted on success, or a DatabaseException on failure.

Remarks

This is an idempotent cleanup operation. Unlike entity delete methods, this method does NOT throw DatabaseEntityNotFoundException when no records exist. Instead, it returns 0 rows deleted. This design supports safe concurrent cleanup where multiple callers may attempt to delete the same records.

Uses a single-statement DELETE.

FetchAsync(List<long>, DateTime, CancellationToken)

Fetches guild update records for specified guilds updated since last fetch.

Task<DatabaseResult<List<GuildUpdateData>>> FetchAsync(List<long> guildIds, DateTime lastFetch, CancellationToken cancellationToken = default)

Parameters

guildIds List<long>

List of guild IDs to check.

lastFetch DateTime

Timestamp to compare against.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<List<GuildUpdateData>>>

A DatabaseResult<T> containing the list of guild update data on success, or a DatabaseException on failure.

Remarks

Filters by both timestamp and guild ID list.

PersistAsync(long, CancellationToken)

Saves or updates the last update timestamp for a guild using atomic UPSERT.

Task<DatabaseResult> PersistAsync(long guildId, CancellationToken cancellationToken = default)

Parameters

guildId long

Guild ID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or containing a DatabaseException on failure.

Remarks

Uses a single-statement PostgreSQL INSERT ... ON CONFLICT DO UPDATE with a conditional update to avoid regressing last_update.