StellaOps.Infrastructure.Postgres

Shared PostgreSQL infrastructure for StellaOps modules

PackageStellaOps.Infrastructure.Postgres
ComponentWorkflow
LicenceBUSL-1.1 (Workflow licence)
Package kindLibrary
Target frameworknet10.0

To add the package to a project, see Installing Stella Ops packages.

Namespaces

NamespaceTypes
StellaOps.Infrastructure.Postgres1
StellaOps.Infrastructure.Postgres.Capacity29
StellaOps.Infrastructure.Postgres.Connections2
StellaOps.Infrastructure.Postgres.Exceptions1
StellaOps.Infrastructure.Postgres.Migrations32
StellaOps.Infrastructure.Postgres.Options1
StellaOps.Infrastructure.Postgres.Repositories1
StellaOps.Infrastructure.Postgres.Testing2

StellaOps.Infrastructure.Postgres namespace

TypeKindDescription
ServiceCollectionExtensionsclassExtension methods for configuring PostgreSQL infrastructure services.

ServiceCollectionExtensions class

public static class ServiceCollectionExtensions

Extension methods for configuring PostgreSQL infrastructure services.

AddPostgresInfrastructure(IServiceCollection, Action<PostgresOptions>) extension method

public static IServiceCollection AddPostgresInfrastructure(this IServiceCollection services, Action<PostgresOptions> configureOptions)

Adds PostgreSQL infrastructure with the specified options.

Parameters

Returns

Service collection for chaining.

AddPostgresOptions(IServiceCollection, IConfiguration, string) extension method

public static IServiceCollection AddPostgresOptions(this IServiceCollection services, IConfiguration configuration, string sectionName = "Postgres")

Adds PostgreSQL infrastructure options from configuration.

Parameters

Returns

Service collection for chaining.

StellaOps.Infrastructure.Postgres.Capacity namespace

TypeKindDescription
CapacityAssessmentrecordThe capacity verdict an operator sees, with its evidence.
CapacityBudgetRegisterclassReads budgets from the data identity register, the one source of truth for them.
CapacityBudgetSetrecordEverything one host’s probe measures against, with the register version it came from.
CapacityCountSessionclassThe probe’s READ ONLY transaction as a count sees it.
CapacityDatabaseBudgetrecordA service database’s byte budget, with its shrink-only interim ceiling.
CapacityDuplicationBudgetrecordOne duplication line’s budget, read from the register entry’s budget.duplication.
CapacityDuplicationCountstructA count, and whether it stopped at the cap it was given.
CapacityDuplicationMeasurementrecordOne duplication line as measured.
CapacityEvaluatorclassTurns a measurement into a receipt; pure, so a health check and the probe agree.
CapacityEventLedgerMeasurementrecordAn eventing ledger as measured: the rows written in the trailing CapacityEvaluator.EventRateWindow.
CapacityEventRateBudgetrecordAn eventing ledger’s events-per-day budget: eventing.outbox or eventing.inbox, measured as the rows written in the trailing CapacityEvaluator.EventRateWindowdivided by its days.
CapacityLinerecordOne measured value against its lines.
CapacityMeasurementrecordThe host database and its registered tables at one instant.
CapacityPauseCauseenumWhy a writer gate is closed.
CapacityReceiptrecordOne probe run, as written to <schema>.capacity_probe_receipt.
CapacityReceiptAssessmentclassJudges the newest receipt.
CapacityReceiptWriterGateclassCloses while the newest receipt shows the database at or above its stop line, while the newest receipt is older than CapacityWriterGateOptions.StaleAfter, and while no receipt exists once CapacityWriterGateOptions.UnmeasuredGraceafter the gate started has passed.
CapacityTableBudgetrecordOne registered table’s budget, read from the data-identity register.
CapacityTableMeasurementrecordOne registered table as measured.
CapacityVerdictenumThe verdict of a capacity line or receipt.
CapacityWriterGateDecisionrecordWhether a writer may start a cycle, and if not, the reason an operator reads.
CapacityWriterGateOptionsclassSettings of the capacity writer gate (Capacity:WriterGate).
CapacityWriterGateServiceCollectionExtensionsclassRegisters the capacity writer gate.
ICapacityDuplicationLineinterfaceThe owning host’s count for one duplication line.
ICapacityReceiptStoreinterfaceReads and writes one host database’s capacity receipts.
ICapacityWriterGateinterfaceConsulted by a writer before a write cycle.
PostgresCapacityDuplicationProbeclassMeasures the declared duplication lines with the owning host’s counts.
PostgresCapacityProbeclassCatalog-only measurement: pg_total_relation_size and pg_class.reltuples (a partitioned table sums its partition tree, because its own size is zero and pg_partition_tree lists nothing for a plain table), plus pg_database_size.
PostgresCapacityReceiptStoreclass<schema>.capacity_probe_receipt in the host’s own database.

CapacityAssessment record

public sealed record CapacityAssessment

The capacity verdict an operator sees, with its evidence.

Parameters

CapacityAssessment(CapacityVerdict, string, IReadOnlyDictionary<string, string>) constructor

public CapacityAssessment(CapacityVerdict Verdict, string Message, IReadOnlyDictionary<string, string> Evidence)

The capacity verdict an operator sees, with its evidence.

Parameters

Evidence property

public IReadOnlyDictionary<string, string> Evidence { get; init; }

The evidence, by key, in key order.

Message property

public string Message { get; init; }

The operator message.

Verdict property

public CapacityVerdict Verdict { get; init; }

The verdict.

CapacityBudgetRegister class

public static class CapacityBudgetRegister

Reads budgets from the data identity register, the one source of truth for them. Each owning host embeds the register under CapacityBudgetRegister.ResourceName; nothing copies a budget into code or configuration.

InterimHeadroom constant

public const readonly decimal InterimHeadroom = 1.05

Headroom above a pinned measurement before a pinned table reaches its stop line.

ResourceName constant

public const string ResourceName = "StellaOps.Capacity.DataIdentityRegister.json"

The logical name every host embeds the register under.

LoadEmbedded(Assembly, string) method

public static CapacityBudgetSet LoadEmbedded(Assembly assembly, string database)

Reads the budgets of a database from the register an assembly embeds under CapacityBudgetRegister.ResourceName.

Parameters

Returns

The budgets.

Exceptions

Parse(byte[], string) method

public static CapacityBudgetSet Parse(byte[] registerJson, string database)

Reads the budgets of a database from the register: the database budget and its event rates, the table budgets of its family’s entries with their duplication lines, and the interim lines of the pins that cover budget.

Parameters

Returns

The budgets, with the SHA-256 of the register.

Exceptions

CapacityBudgetSet record

public sealed record CapacityBudgetSet

Everything one host’s probe measures against, with the register version it came from.

Parameters

CapacityBudgetSet(CapacityDatabaseBudget, IReadOnlyList<CapacityTableBudget>, string, IReadOnlyList<CapacityEventRateBudget>, IReadOnlyList<CapacityDuplicationBudget>) constructor

public CapacityBudgetSet(CapacityDatabaseBudget Database, IReadOnlyList<CapacityTableBudget> Tables, string RegisterSha256, IReadOnlyList<CapacityEventRateBudget>? EventRates = null, IReadOnlyList<CapacityDuplicationBudget>? Duplication = null)

Everything one host’s probe measures against, with the register version it came from.

Parameters

Database property

public CapacityDatabaseBudget Database { get; init; }

The database budget.

Duplication property

public IReadOnlyList<CapacityDuplicationBudget>? Duplication { get; init; }

The family’s duplication line budgets, ordered by table and metric.

EventRates property

public IReadOnlyList<CapacityEventRateBudget>? EventRates { get; init; }

The database’s eventing ledger budgets, ordered by ledger; empty when the register declares none.

RegisterSha256 property

public string RegisterSha256 { get; init; }

The SHA-256 of the register the budgets came from.

Tables property

public IReadOnlyList<CapacityTableBudget> Tables { get; init; }

The table budgets, ordered by table.

CapacityCountSession class

public sealed class CapacityCountSession

The probe’s READ ONLY transaction as a count sees it. A count creates its commands here, never on a raw connection: each command’s client timeout is longer than the posture’s statement timeout, so a slow count is cancelled by the server (SQLSTATE 57014), rolled back to its savepoint and reported absent. With a client timeout shorter than the statement timeout (Npgsql’s default is 30 s), a slow count would end the pass with a client-side TimeoutException and write no receipt.

ClientTimeoutMargin field

public static readonly TimeSpan ClientTimeoutMargin

How long a command’s client timeout outlasts the statement timeout, so the server cancels first.

CommandTimeoutSeconds property

public int CommandTimeoutSeconds { get; }

The client timeout, in whole seconds, every command of this session carries.

ClientTimeoutSeconds(TimeSpan) method

public static int ClientTimeoutSeconds(TimeSpan statementTimeout)

The statement timeout rounded up to whole seconds, plus CapacityCountSession.ClientTimeoutMargin.

CreateCommand(string) method

public NpgsqlCommand CreateCommand(string sql)

A command in the probe’s transaction whose client timeout outlasts the statement timeout.

CapacityDatabaseBudget record

public sealed record CapacityDatabaseBudget

A service database’s byte budget, with its shrink-only interim ceiling.

Parameters

CapacityDatabaseBudget(string, string, long, decimal, decimal, long?, IReadOnlyList<string>) constructor

public CapacityDatabaseBudget(string Database, string Family, long Bytes, decimal Alarm, decimal Stop, long? InterimCeilingBytes = null, IReadOnlyList<string>? Remediation = null)

A service database’s byte budget, with its shrink-only interim ceiling.

Parameters

Alarm property

public decimal Alarm { get; init; }

The alarm line as a ratio of a budget, for every line of the database.

Bytes property

public long Bytes { get; init; }

The byte budget of the database.

Database property

public string Database { get; init; }

The register’s name for the database.

Family property

public string Family { get; init; }

The service family that owns the database.

InterimCeilingBytes property

public long? InterimCeilingBytes { get; init; }

While set, the database’s stop line (FAIL, writer pause). The owner budget keeps setting the alarm line, so a database above its budget warns until the remediation lands.

Remediation property

public IReadOnlyList<string>? Remediation { get; init; }

The work items that own the excess, as the register records them.

Stop property

public decimal Stop { get; init; }

The stop line as a ratio of a budget, for every line of the database.

CapacityDuplicationBudget record

public sealed record CapacityDuplicationBudget

One duplication line’s budget, read from the register entry’s budget.duplication. Alarm and stop come from the database ratios unless the line declares both AlarmAt and StopAt (a small count, such as a generation count, where 80% and 95% of the budget round to the same integer).

Parameters

CapacityDuplicationBudget(string, string, long, long?, long?) constructor

public CapacityDuplicationBudget(string Table, string Metric, long Budget, long? AlarmAt = null, long? StopAt = null)

One duplication line’s budget, read from the register entry’s budget.duplication. Alarm and stop come from the database ratios unless the line declares both AlarmAt and StopAt (a small count, such as a generation count, where 80% and 95% of the budget round to the same integer).

Parameters

AlarmAt property

public long? AlarmAt { get; init; }

The declared alarm line; with StopAt, it replaces the database ratios.

Budget property

public long Budget { get; init; }

The budget.

Metric property

public string Metric { get; init; }

One of CapacityEvaluator.DuplicationMetrics.

StopAt property

public long? StopAt { get; init; }

The declared stop line; with AlarmAt, it replaces the database ratios.

Table property

public string Table { get; init; }

The register entry that declares the line; the receipt line’s subject.

CapacityDuplicationCount struct

public readonly struct CapacityDuplicationCount : IEquatable<CapacityDuplicationCount>

A count, and whether it stopped at the cap it was given.

Parameters

CapacityDuplicationCount(long, bool) constructor

public CapacityDuplicationCount(long Value, bool Capped)

A count, and whether it stopped at the cap it was given.

Parameters

Capped property

public bool Capped { get; init; }

Whether the count stopped at the cap.

Value property

public long Value { get; init; }

The count.

CapacityDuplicationMeasurement record

public sealed record CapacityDuplicationMeasurement

One duplication line as measured. An absent line (no count, its index missing, or a count that ran past the statement timeout) is reported, not measured.

Parameters

CapacityDuplicationMeasurement(string, string, bool, long, bool, bool) constructor

public CapacityDuplicationMeasurement(string Table, string Metric, bool Present, long Measured, bool Capped = false, bool TimedOut = false)

One duplication line as measured. An absent line (no count, its index missing, or a count that ran past the statement timeout) is reported, not measured.

Parameters

Capped property

public bool Capped { get; init; }

The count stopped at its cap, so Measured is a lower bound.

Measured property

public long Measured { get; init; }

The count.

Metric property

public string Metric { get; init; }

The duplication metric.

Present property

public bool Present { get; init; }

Whether the line was counted.

Table property

public string Table { get; init; }

The register entry that declares the line.

TimedOut property

public bool TimedOut { get; init; }

The count ran past the statement timeout and was rolled back; the line is absent.

CapacityEvaluator class

public static class CapacityEvaluator

Turns a measurement into a receipt; pure, so a health check and the probe agree.

Bytes constant

public const string Bytes = "bytes"

The size metric, in bytes.

DuplicationMetrics field

public static readonly IReadOnlySet<string> DuplicationMetrics

The duplication metrics a register entry may budget (budget.duplication).

EventRateWindow field

public static readonly TimeSpan EventRateWindow

The trailing window an event rate divides. The eventing pruners never reclaim a row younger than seven days (the outbox and inbox retention minimum), so every row written in this window is still in its ledger when the probe counts it.

EventsPerDay constant

public const string EventsPerDay = "eventsPerDay"

The event rate metric, in events per day.

Generations constant

public const string Generations = "generations"

Generations present against the declared generation count.

GrowthPerDay constant

public const string GrowthPerDay = "growthPerDay"

The growth metric, in bytes per day.

MinimumGrowthSpan field

public static readonly TimeSpan MinimumGrowthSpan

Growth is the byte delta to the previous receipt, normalised to a day. Two receipts closer than this say more about a single import than about a rate.

OverrideRows constant

public const string OverrideRows = "overrideRows"

Tenant rows stored where the global row would otherwise serve.

Rows constant

public const string Rows = "rows"

The row count metric.

SupersededCopies constant

public const string SupersededCopies = "supersededCopies"

D2: rows of a table beyond one per identity (superseded copies a rule still retains or has not yet reclaimed).

TombstonesPastRule constant

public const string TombstonesPastRule = "tombstonesPastRule"

Superseded identities whose tombstone is past the entry’s reclaim rule.

DuplicationThresholds(CapacityDuplicationBudget, CapacityDatabaseBudget) method

public static (long AlarmAt, long StopAt) DuplicationThresholds(CapacityDuplicationBudget line, CapacityDatabaseBudget database)

A duplication line’s alarm and stop lines: the declared pair when the register sets one, else the database’s ratios of the budget, like every other line. The stop line is also the cap a bounded count stops at.

Evaluate(CapacityBudgetSet, CapacityMeasurement, CapacityReceipt, DateTimeOffset) method

public static CapacityReceipt Evaluate(CapacityBudgetSet budgets, CapacityMeasurement measurement, CapacityReceipt? previous, DateTimeOffset probedAt)

Builds a receipt from a measurement: the bytes line of the database; for each budgeted table its bytes and rows lines, and a growth line when the previous receipt is at least CapacityEvaluator.MinimumGrowthSpanolder; and the event rate and duplication lines the measurement carries. A required subject that was not measured is listed as absent.

Parameters

Returns

The receipt, not stored yet.

EventsPerDayFor(long) method

public static long EventsPerDayFor(long windowRows)

Events per day from the rows written in the trailing CapacityEvaluator.EventRateWindow.

CapacityEventLedgerMeasurement record

public sealed record CapacityEventLedgerMeasurement

An eventing ledger as measured: the rows written in the trailing CapacityEvaluator.EventRateWindow. An absent ledger is reported, not measured.

Parameters

CapacityEventLedgerMeasurement(string, bool, long) constructor

public CapacityEventLedgerMeasurement(string Ledger, bool Present, long WindowRows)

An eventing ledger as measured: the rows written in the trailing CapacityEvaluator.EventRateWindow. An absent ledger is reported, not measured.

Parameters

Ledger property

public string Ledger { get; init; }

The ledger.

Present property

public bool Present { get; init; }

Whether the ledger exists.

WindowRows property

public long WindowRows { get; init; }

The rows written in the trailing window.

CapacityEventRateBudget record

public sealed record CapacityEventRateBudget

An eventing ledger’s events-per-day budget: eventing.outbox or eventing.inbox, measured as the rows written in the trailing CapacityEvaluator.EventRateWindowdivided by its days. A sustained breach is the signal of a new churn source (an identity migration, a re-normalization storm, a writer that re-emits unchanged state). The line warns and fails; it never pauses writers.

Parameters

CapacityEventRateBudget(string, long, long?) constructor

public CapacityEventRateBudget(string Ledger, long PerDay, long? InterimCeilingPerDay = null)

An eventing ledger’s events-per-day budget: eventing.outbox or eventing.inbox, measured as the rows written in the trailing CapacityEvaluator.EventRateWindowdivided by its days. A sustained breach is the signal of a new churn source (an identity migration, a re-normalization storm, a writer that re-emits unchanged state). The line warns and fails; it never pauses writers.

Parameters

InterimCeilingPerDay property

public long? InterimCeilingPerDay { get; init; }

While set, the ledger’s stop line: the shrink-only ceiling over a window that still holds a known burst. The budget keeps the alarm line.

Ledger property

public string Ledger { get; init; }

The ledger: eventing.outbox or eventing.inbox.

PerDay property

public long PerDay { get; init; }

The events-per-day budget.

CapacityLine record

public sealed record CapacityLine

One measured value against its lines. Reaching the alarm line warns; reaching the stop line fails. A metric with no stop line (growth per day) can only warn.

Parameters

CapacityLine(string, string, long, long, long, long?, bool, long?, bool) constructor

public CapacityLine(string Subject, string Metric, long Measured, long Budget, long AlarmAt, long? StopAt, bool Interim, long? WindowRows = null, bool Capped = false)

One measured value against its lines. Reaching the alarm line warns; reaching the stop line fails. A metric with no stop line (growth per day) can only warn.

Parameters

DatabaseSubject constant

public const string DatabaseSubject = "database"

The subject of the database line.

AlarmAt property

public long AlarmAt { get; init; }

The alarm line.

Budget property

public long Budget { get; init; }

The budget.

Capped property

public bool Capped { get; init; }

For a duplication line: the count stopped at the stop line, so Measured is a lower bound.

Interim property

public bool Interim { get; init; }

The stop line is an interim ceiling or a pinned measurement, not the owner budget.

Measured property

public long Measured { get; init; }

The measured value.

Metric property

public string Metric { get; init; }

bytes, rows, growthPerDay (bytes per day), eventsPerDay or a duplication metric (CapacityEvaluator.DuplicationMetrics).

StopAt property

public long? StopAt { get; init; }

The stop line; none for a metric that can only warn.

Subject property

public string Subject { get; init; }

CapacityLine.DatabaseSubject, a qualified table name or an eventing ledger.

Verdict property

public CapacityVerdict Verdict { get; }

CapacityVerdict.Failat or above the stop line, CapacityVerdict.Warnat or above the alarm line, else CapacityVerdict.Pass.

WindowRows property

public long? WindowRows { get; init; }

For eventsPerDay: the rows written in the trailing window the rate divides.

CapacityMeasurement record

public sealed record CapacityMeasurement

The host database and its registered tables at one instant.

Parameters

CapacityMeasurement(string, long, IReadOnlyList<CapacityTableMeasurement>, IReadOnlyList<CapacityEventLedgerMeasurement>, IReadOnlyList<CapacityDuplicationMeasurement>) constructor

public CapacityMeasurement(string Database, long DatabaseBytes, IReadOnlyList<CapacityTableMeasurement> Tables, IReadOnlyList<CapacityEventLedgerMeasurement>? EventLedgers = null, IReadOnlyList<CapacityDuplicationMeasurement>? Duplication = null)

The host database and its registered tables at one instant.

Parameters

Database property

public string Database { get; init; }

The physical database the connection reached (current_database()).

DatabaseBytes property

public long DatabaseBytes { get; init; }

The database size, in bytes (pg_database_size).

Duplication property

public IReadOnlyList<CapacityDuplicationMeasurement>? Duplication { get; init; }

The duplication lines’ counts; null when the caller measured none.

EventLedgers property

public IReadOnlyList<CapacityEventLedgerMeasurement>? EventLedgers { get; init; }

The eventing ledgers’ trailing-window counts; null when the caller measured no event rate.

Tables property

public IReadOnlyList<CapacityTableMeasurement> Tables { get; init; }

The registered tables as measured.

CapacityPauseCause enum

public enum CapacityPauseCause

Why a writer gate is closed.

ValueDescription
None = 0The gate is open.
StopLine = 1The newest receipt shows the database at or above its stop line.
StaleReceipt = 2The newest receipt is older than CapacityWriterGateOptions.StaleAfter.
NoReceipt = 3No receipt exists once CapacityWriterGateOptions.UnmeasuredGracehas passed.

CapacityReceipt record

public sealed record CapacityReceipt

One probe run, as written to <schema>.capacity_probe_receipt.

Parameters

CapacityReceipt(long?, string, string, DateTimeOffset, string, IReadOnlyList<CapacityLine>, IReadOnlyList<string>, IReadOnlyList<string>) constructor

public CapacityReceipt(long? ReceiptId, string BudgetDatabase, string PhysicalDatabase, DateTimeOffset ProbedAt, string RegisterSha256, IReadOnlyList<CapacityLine> Lines, IReadOnlyList<string> AbsentTables, IReadOnlyList<string>? Remediation = null)

One probe run, as written to <schema>.capacity_probe_receipt.

Parameters

AbsentTables property

public IReadOnlyList<string> AbsentTables { get; init; }

The required subjects that were not measured: tables, ledgers and duplication lines.

BudgetDatabase property

public string BudgetDatabase { get; init; }

The register’s name for the database (the budget key).

DatabaseLine property

public CapacityLine DatabaseLine { get; }

The bytes line of the database.

DuplicationLines property

public IReadOnlyList<CapacityLine> DuplicationLines { get; }

The duplication lines, ordered by table and metric.

EventRateLines property

public IReadOnlyList<CapacityLine> EventRateLines { get; }

The eventing ledgers’ events-per-day lines, ordered by ledger.

Lines property

public IReadOnlyList<CapacityLine> Lines { get; init; }

The measured lines.

PhysicalDatabase property

public string PhysicalDatabase { get; init; }

The database the probe actually measured.

ProbedAt property

public DateTimeOffset ProbedAt { get; init; }

When the probe measured.

ReceiptId property

public long? ReceiptId { get; init; }

The id the store assigned; none before the receipt is stored.

RegisterSha256 property

public string RegisterSha256 { get; init; }

The SHA-256 of the register the budgets came from.

Remediation property

public IReadOnlyList<string>? Remediation { get; init; }

The work items the register names as owning the database’s excess.

RemediationText property

public string RemediationText { get; }

The remediation rows by name, or the statement that none owns the excess.

Summary property

public string Summary { get; }

The one-line operator summary the probe logs and stores.

Verdict property

public CapacityVerdict Verdict { get; }

CapacityVerdict.Failwhen a required subject was not measured; otherwise the worst line verdict, and CapacityVerdict.Passwithout lines.

WriterPause property

public bool WriterPause { get; }

The database is at or above its stop line, so writer admission must pause. This receipt records that decision; it does not observe whether a caller enforced it. Only database bytes require a writer pause; table/event-rate stop lines fail the capacity health check.

CapacityReceiptAssessment class

public static class CapacityReceiptAssessment

Judges the newest receipt. A missing receipt and a receipt older than CapacityReceiptAssessment.MaximumReceiptAgeboth FAIL: a dead probe is a failure, not “no data”. Its age is measured on the caller’s clock, so the verdict turns red on its own when the probe stops, which is the one property a monitor without a freshness rule lacks.

MaximumReceiptAge field

public static readonly TimeSpan MaximumReceiptAge

The age after which a receipt fails: 36 hours.

Assess(string, CapacityReceipt, DateTimeOffset) method

public static CapacityAssessment Assess(string database, CapacityReceipt? newest, DateTimeOffset now)

Judges the newest receipt of a database: CapacityVerdict.Failwithout a receipt or with one older than CapacityReceiptAssessment.MaximumReceiptAge; otherwise the receipt’s verdict, with the message and the evidence an operator sees.

Parameters

Returns

The assessment.

CapacityReceiptWriterGate class

public sealed class CapacityReceiptWriterGate : ICapacityWriterGate

Closes while the newest receipt shows the database at or above its stop line, while the newest receipt is older than CapacityWriterGateOptions.StaleAfter, and while no receipt exists once CapacityWriterGateOptions.UnmeasuredGraceafter the gate started has passed. A stop-line receipt is honoured whatever its age: resuming writes on an unmeasured, last-known-full database is the failure this prevents. A missing receipt table reads as no receipt, so a writer deployed before the host that runs the probe pauses with that reason once the grace has passed, and resumes on the first receipt below the stop line. One log line per transition (opened, closed, or closed for a different cause), never one per evaluation.

CapacityReceiptWriterGate(ICapacityReceiptStore, string, ILogger, TimeProvider, CapacityWriterGateOptions) constructor

public CapacityReceiptWriterGate(ICapacityReceiptStore store, string writer, ILogger logger, TimeProvider? clock = null, CapacityWriterGateOptions? options = null)

Creates the gate; the grace for a missing receipt counts from this moment.

Parameters

Exceptions

EvaluateAsync(CancellationToken) method

public Task<CapacityWriterGateDecision> EvaluateAsync(CancellationToken cancellationToken)

Reads the newest receipt and decides. Writers pause when the database is at or above its stop line, when the newest receipt is older than StaleAfter, or when no receipt exists once UnmeasuredGrace has passed since the gate was created. A change of decision is logged.

Parameters

Returns

The decision.

CapacityTableBudget record

public sealed record CapacityTableBudget

One registered table’s budget, read from the data-identity register.

Parameters

CapacityTableBudget(string, long, long, long, long?, long?, DateOnly?) constructor

public CapacityTableBudget(string Table, long Bytes, long Rows, long GrowthPerDay, long? InterimBytes = null, long? InterimRows = null, DateOnly? InterimUntil = null)

One registered table’s budget, read from the data-identity register.

Parameters

Bytes property

public long Bytes { get; init; }

The byte budget.

GrowthPerDay property

public long GrowthPerDay { get; init; }

The growth budget, in bytes per day; it is the alarm line of the growth line, which has no stop line.

InterimBytes property

public long? InterimBytes { get; init; }

The stop line a pin that covers budget holds the table at: the pin’s declared interim ceiling (for example a designed generation peak), else its pinned measurement plus CapacityBudgetRegister.InterimHeadroom. Applies while InterimUntil (the pin’s sunset) has not passed, so a remediation that stalls past its sunset turns the table red with no code change.

InterimRows property

public long? InterimRows { get; init; }

The row stop line the pin holds the table at, as for InterimBytes.

InterimUntil property

public DateOnly? InterimUntil { get; init; }

The pin’s sunset: the interim stop lines apply through this day.

Rows property

public long Rows { get; init; }

The row budget.

Table property

public string Table { get; init; }

The qualified table name.

CapacityTableMeasurement record

public sealed record CapacityTableMeasurement

One registered table as measured. An absent table is reported, not measured.

Parameters

CapacityTableMeasurement(string, bool, long, long) constructor

public CapacityTableMeasurement(string Table, bool Present, long Bytes, long Rows)

One registered table as measured. An absent table is reported, not measured.

Parameters

Bytes property

public long Bytes { get; init; }

The total size with indexes (pg_total_relation_size); a partitioned table sums its partitions.

Present property

public bool Present { get; init; }

Whether the table exists.

Rows property

public long Rows { get; init; }

The estimated row count (pg_class.reltuples).

Table property

public string Table { get; init; }

The qualified table name.

CapacityVerdict enum

public enum CapacityVerdict

The verdict of a capacity line or receipt.

ValueDescription
Pass = 0Below the alarm line.
Warn = 1At or above the alarm line, below the stop line.
Fail = 2At or above the stop line, or a required subject was not measured.

CapacityWriterGateDecision record

public sealed record CapacityWriterGateDecision

Whether a writer may start a cycle, and if not, the reason an operator reads.

Parameters

CapacityWriterGateDecision(bool, string, CapacityPauseCause) constructor

public CapacityWriterGateDecision(bool Paused, string? Reason, CapacityPauseCause Cause = None)

Whether a writer may start a cycle, and if not, the reason an operator reads.

Parameters

Open field

public static readonly CapacityWriterGateDecision Open

The open gate: writers write.

Cause property

public CapacityPauseCause Cause { get; init; }

The cause of the pause.

Paused property

public bool Paused { get; init; }

Whether writers must pause.

Reason property

public string? Reason { get; init; }

Why they pause; none when the gate is open.

CapacityWriterGateOptions class

public sealed class CapacityWriterGateOptions

Settings of the capacity writer gate (Capacity:WriterGate).

CapacityWriterGateOptions() constructor

public CapacityWriterGateOptions()

Creates an instance of CapacityWriterGateOptions.

SectionName constant

public const string SectionName = "Capacity:WriterGate"

The configuration section the options bind from: Capacity:WriterGate.

StaleAfter property

public TimeSpan StaleAfter { get; set; }

A newest receipt older than this closes the gate (“capacity unmeasured”). The probe writes a receipt every 24 h plus up to 1 h of jitter and retries a failed pass after 15 minutes. 48 h is two probe intervals: one missed or retried pass never pauses writers, and a dead probe cannot leave writers running unmeasured into a third day.

UnmeasuredGrace property

public TimeSpan UnmeasuredGrace { get; set; }

How long after the gate starts a missing receipt leaves writers running: the probe’s startup delay (1 minute), one pass (a few catalog statements, each bounded at 60 seconds) and one retry after a failed first pass (15 minutes). After it, a missing receipt closes the gate.

IsValid() method

public bool IsValid()

Whether the options are usable: CapacityWriterGateOptions.StaleAfterpositive and CapacityWriterGateOptions.UnmeasuredGracenot negative.

Returns

true when the options are usable.

CapacityWriterGateServiceCollectionExtensions class

public static class CapacityWriterGateServiceCollectionExtensions

Registers the capacity writer gate.

AddCapacityWriterGate(IServiceCollection, IConfiguration, string, Func<IServiceProvider, ICapacityReceiptStore>) extension method

public static IServiceCollection AddCapacityWriterGate(this IServiceCollection services, IConfiguration configuration, string writer, Func<IServiceProvider, ICapacityReceiptStore> receipts)

Registers the host’s writer gate over its database’s receipt store, with CapacityWriterGateOptionsbound from CapacityWriterGateOptions.SectionName. One gate per host: a service writes only its own database, so every gated writer in the host shares it and the transition log is written once.

Parameters

ICapacityDuplicationLine interface

public interface ICapacityDuplicationLine

The owning host’s count for one duplication line. A count is index-backed and bounded: it walks ICapacityDuplicationLine.RequiredIndex, and a count whose cost grows with its value stops at the cap (the line’s stop line, the smallest value that fails), so a 100 GB table and a runaway backlog cost what the stop line costs. It runs inside the probe’s READ ONLY transaction (PostgresCapacityDuplicationProbe.ApplyPostureAsync(NpgsqlConnection, NpgsqlTransaction, TimeSpan, CancellationToken)), with commands from the CapacityCountSessionit is handed, and must write nothing; it may set transaction-local settings (a tenant context) with set_config(..., true).

Metric property

string Metric { get; }

One of CapacityEvaluator.DuplicationMetrics.

RequiredIndex property

string RequiredIndex { get; }

The index the count walks, schema-qualified. While it does not exist the line is absent, never a scan.

Table property

string Table { get; }

The register entry that declares the line.

CountAsync(CapacityCountSession, long, DateTimeOffset, CancellationToken) method

Task<CapacityDuplicationCount> CountAsync(CapacityCountSession session, long cap, DateTimeOffset probedAt, CancellationToken cancellationToken)

Counts the line, stopping at the cap.

Parameters

Returns

The count, and whether it stopped at the cap.

ICapacityReceiptStore interface

public interface ICapacityReceiptStore

Reads and writes one host database’s capacity receipts.

BudgetDatabase property

string BudgetDatabase { get; }

The register’s name for the database these receipts describe.

AppendAsync(CapacityReceipt, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>, CancellationToken) method

Task<long> AppendAsync(CapacityReceipt receipt, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>? beforeCommit, CancellationToken cancellationToken)

Appends a receipt and reclaims the oldest beyond the family migration’s retained count, in one transaction. beforeCommit runs inside it (the probe’s lease fence).

ReadNewestAsync(CancellationToken) method

Task<CapacityReceipt?> ReadNewestAsync(CancellationToken cancellationToken)

The newest receipt, or null when none exists (or the receipt table is not there yet).

ICapacityWriterGate interface

public interface ICapacityWriterGate

Consulted by a writer before a write cycle. Above the stop line, or while capacity is unmeasured, the writer skips the cycle with an operator-visible reason; it never crashes and never fills the volume.

EvaluateAsync(CancellationToken) method

Task<CapacityWriterGateDecision> EvaluateAsync(CancellationToken cancellationToken)

Decides whether writers must pause.

Parameters

Returns

The decision.

PostgresCapacityDuplicationProbe class

public static class PostgresCapacityDuplicationProbe

Measures the declared duplication lines with the owning host’s counts.

ApplyPostureAsync(NpgsqlConnection, NpgsqlTransaction, TimeSpan, CancellationToken) method

public static Task ApplyPostureAsync(NpgsqlConnection connection, NpgsqlTransaction transaction, TimeSpan statementTimeout, CancellationToken cancellationToken)

The posture every count runs under, and the one a plan test reproduces: READ ONLY, the statement timeout, no parallel workers (a parallel hash lives in the container’s small /dev/shm) and no sequential scan where an index can serve (the count walks its index, never the table’s heap). Call it first in a fresh transaction.

MeasureAsync(NpgsqlDataSource, IReadOnlyCollection<CapacityDuplicationBudget>, IEnumerable<ICapacityDuplicationLine>, CapacityDatabaseBudget, DateTimeOffset, TimeSpan, CancellationToken) method

public static Task<IReadOnlyList<CapacityDuplicationMeasurement>> MeasureAsync(NpgsqlDataSource dataSource, IReadOnlyCollection<CapacityDuplicationBudget> declared, IEnumerable<ICapacityDuplicationLine> lines, CapacityDatabaseBudget database, DateTimeOffset probedAt, TimeSpan statementTimeout, CancellationToken cancellationToken)

One READ ONLY transaction, rolled back. A declared line with no count, or whose required index does not exist, is absent. Each count runs under its own savepoint: one that runs past the statement timeout is rolled back and reported absent (CapacityDuplicationMeasurement.TimedOut), so a slow count never costs the receipt its database and table lines. The count’s commands come from a CapacityCountSession, so the server’s statement timeout ends a slow count before the client’s does. Two counts for one line are a composition error.

PostgresCapacityProbe class

public static class PostgresCapacityProbe

Catalog-only measurement: pg_total_relation_size and pg_class.reltuples (a partitioned table sums its partition tree, because its own size is zero and pg_partition_tree lists nothing for a plain table), plus pg_database_size. No statement reads a table’s rows, so a 100 GB table costs the same as an empty one. Runs inside one READ ONLY transaction with a statement timeout and rolls back.

DefaultStatementTimeout field

public static readonly TimeSpan DefaultStatementTimeout

The default statement timeout of a measurement: 60 seconds.

MeasureAsync(NpgsqlDataSource, IReadOnlyCollection<string>, TimeSpan, CancellationToken) method

public static Task<CapacityMeasurement> MeasureAsync(NpgsqlDataSource dataSource, IReadOnlyCollection<string> tables, TimeSpan statementTimeout, CancellationToken cancellationToken)

Measures the database and the named tables in one READ ONLY transaction under a statement timeout.

Parameters

Returns

The measurement; a table that does not exist is measured as absent.

Exceptions

PostgresCapacityReceiptStore class

public sealed class PostgresCapacityReceiptStore : ICapacityReceiptStore

<schema>.capacity_probe_receipt in the host’s own database. Each owning family creates the table and its prune_capacity_probe_receipts function in its own forward-only migration; the retained count is that function’s default, so it has one source.

PostgresCapacityReceiptStore(NpgsqlDataSource, string, string) constructor

public PostgresCapacityReceiptStore(NpgsqlDataSource dataSource, string schema, string budgetDatabase)

Creates the store for a schema of the host database.

Parameters

Exceptions

PruneFunctionName constant

public const string PruneFunctionName = "prune_capacity_probe_receipts"

The function that reclaims the oldest receipts.

TableName constant

public const string TableName = "capacity_probe_receipt"

The receipt table.

BudgetDatabase property

public string BudgetDatabase { get; }

The register’s name for the database these receipts describe.

AppendAsync(CapacityReceipt, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>, CancellationToken) method

public Task<long> AppendAsync(CapacityReceipt receipt, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>? beforeCommit, CancellationToken cancellationToken)

Appends a receipt and reclaims the oldest beyond the family migration’s retained count, in one transaction. beforeCommit runs inside it (the probe’s lease fence).

ReadNewestAsync(CancellationToken) method

public Task<CapacityReceipt?> ReadNewestAsync(CancellationToken cancellationToken)

The newest receipt, or null when none exists (or the receipt table is not there yet).

StellaOps.Infrastructure.Postgres.Connections namespace

TypeKindDescription
DataSourceBaseclassBase class for module-specific PostgreSQL data sources.
PostgresConnectionStringPolicyclassApplies StellaOps runtime defaults to PostgreSQL connection strings.

DataSourceBase class

public abstract class DataSourceBase : IAsyncDisposable

Base class for module-specific PostgreSQL data sources. Manages connection pooling, tenant context configuration, and session settings.

Remarks

Each module should derive from this class to create a strongly-typed data source. Example: OrdersDataSource : DataSourceBase

DataSourceBase(PostgresOptions, ILogger) constructor

protected DataSourceBase(PostgresOptions options, ILogger logger)

Creates a new data source with the specified options.

CommandTimeoutSeconds property

public int CommandTimeoutSeconds { get; }

Command timeout in seconds from options.

ModuleName property

protected abstract string ModuleName { get; }

Module name for logging and metrics.

Options property

protected PostgresOptions Options { get; }

PostgreSQL options for this data source.

SchemaName property

public string? SchemaName { get; }

Schema name for this module’s tables.

ConfigureDataSourceBuilder(NpgsqlDataSourceBuilder) method

protected virtual void ConfigureDataSourceBuilder(NpgsqlDataSourceBuilder builder)

Override to configure additional NpgsqlDataSourceBuilder options.

ConfigureSessionAsync(NpgsqlConnection, string, CancellationToken) method

protected virtual Task ConfigureSessionAsync(NpgsqlConnection connection, string tenantId, CancellationToken cancellationToken)

Override to add custom session configuration.

ConfigureSystemSessionAsync(NpgsqlConnection, CancellationToken) method

protected virtual Task ConfigureSystemSessionAsync(NpgsqlConnection connection, CancellationToken cancellationToken)

Override to add custom system session configuration.

DisposeAsync() method

public ValueTask DisposeAsync()

Disposes the data source and releases all pooled connections.

OnConnectionClosed(string) method

protected virtual void OnConnectionClosed(string role)

Override to handle connection closed events for metrics.

OnConnectionOpened(string) method

protected virtual void OnConnectionOpened(string role)

Override to handle connection opened events for metrics.

OpenConnectionAsync(string, CancellationToken) method

public Task<NpgsqlConnection> OpenConnectionAsync(string tenantId, CancellationToken cancellationToken = default)

Opens a connection with tenant context configured.

Parameters

Returns

Open PostgreSQL connection with tenant context set.

OpenConnectionAsync(string, string, CancellationToken) method

public Task<NpgsqlConnection> OpenConnectionAsync(string tenantId, string role, CancellationToken cancellationToken = default)

Opens a connection with tenant context and role label configured.

Parameters

Returns

Open PostgreSQL connection with tenant context set.

OpenSystemConnectionAsync(CancellationToken) method

public Task<NpgsqlConnection> OpenSystemConnectionAsync(CancellationToken cancellationToken = default)

Opens a connection for system operations without tenant context. Use sparingly - only for migrations, health checks, and cross-tenant admin operations.

Parameters

Returns

Open PostgreSQL connection without tenant context.

PostgresConnectionStringPolicy class

public static class PostgresConnectionStringPolicy

Applies StellaOps runtime defaults to PostgreSQL connection strings.

Build(PostgresOptions, string) method

public static string Build(PostgresOptions options, string defaultApplicationName)

Applies the attribution and pooling policy of the options to their connection string, with the options’ application name or, when they set none, the default one.

Parameters

Returns

The connection string.

Build(string, string, bool?, int?, int?, int?) method

public static string Build(string connectionString, string applicationName, bool? pooling = null, int? minPoolSize = null, int? maxPoolSize = null, int? connectionIdleLifetimeSeconds = null)

Applies the runtime attribution and pooling policy to a raw connection string. A pooling argument the caller leaves null keeps what the connection string itself says — the operator’s value — and falls back to the defaults (pooling on, min 1, max 100) only when the string carries nothing. A non-null caller value still wins.

An operator’s Maximum Pool Size in the connection string is therefore kept, so hosts that share one PostgreSQL server stay within the pool sizes the operator set for the server’s max_connections.

BuildDefaultApplicationName(string) method

public static string BuildDefaultApplicationName(string moduleName)

The default application name of a module: stellaops- and the module name in lower-case kebab case.

Parameters

Returns

The application name.

StellaOps.Infrastructure.Postgres.Exceptions namespace

TypeKindDescription
PostgresExceptionHelperclassHelper methods for handling PostgreSQL exceptions.

PostgresExceptionHelper class

public static class PostgresExceptionHelper

Helper methods for handling PostgreSQL exceptions.

CheckViolation constant

public const string CheckViolation = "23514"

PostgreSQL error code for check constraint violation.

DeadlockDetected constant

public const string DeadlockDetected = "40P01"

PostgreSQL error code for deadlock detected (retry needed).

ForeignKeyViolation constant

public const string ForeignKeyViolation = "23503"

PostgreSQL error code for foreign key violation.

NotNullViolation constant

public const string NotNullViolation = "23502"

PostgreSQL error code for not null violation.

SerializationFailure constant

public const string SerializationFailure = "40001"

PostgreSQL error code for serialization failure (retry needed).

UniqueViolation constant

public const string UniqueViolation = "23505"

PostgreSQL error code for unique constraint violation.

IsCheckViolation(PostgresException) method

public static bool IsCheckViolation(PostgresException ex)

Checks if the exception is a check constraint violation.

IsForeignKeyViolation(PostgresException) method

public static bool IsForeignKeyViolation(PostgresException ex)

Checks if the exception is a foreign key violation.

IsNotNullViolation(PostgresException) method

public static bool IsNotNullViolation(PostgresException ex)

Checks if the exception is a not null violation.

IsRetryable(Exception) method

public static bool IsRetryable(Exception ex)

Checks if any exception in the chain is retryable.

IsRetryable(PostgresException) method

public static bool IsRetryable(PostgresException ex)

Checks if the exception is retryable (serialization failure or deadlock).

IsUniqueViolation(PostgresException) method

public static bool IsUniqueViolation(PostgresException ex)

Checks if the exception is a unique constraint violation.

IsUniqueViolation(PostgresException, string) method

public static bool IsUniqueViolation(PostgresException ex, string constraintName)

Checks if the exception is a unique constraint violation for a specific constraint.

StellaOps.Infrastructure.Postgres.Migrations namespace

TypeKindDescription
AppliedMigrationDetailrecordDetails of an applied migration.
DeferredIndexBuilderclassResumes declared concurrent index builds after the host starts.
DeferredIndexDefinitionrecordOwner-reviewed deferral of exactly one index statement in an immutable startup migration.
DeferredIndexNotReadyExceptionclassAn index-dependent operation is temporarily unavailable while maintenance converges.
DeferredIndexOptionsclassBounded post-start maintenance budgets, bindable through the owner’s configuration.
IMigrationRunnerinterfaceInterface for running database migrations.
IMigrationSqlExecutorinterfaceOptional module-owned SQL execution policy.
IMigrationStatusServiceinterfaceService for querying migration status without applying migrations.
MigrationAssemblySourcerecordMigration source descriptor (assembly + optional resource prefix).
MigrationCategoryenumCategorizes migrations by when they should be executed.
MigrationCategoryExtensionsclassExtension methods for migration category operations.
MigrationChecksumclassCanonical checksum computation for migration SQL content.
MigrationChecksumReconciliationPinrecordAn owner-declared statement that one specific already-applied checksum was produced by content whose executable SQL matches the current file — used to reconcile a database whose row was written before the host recorded normalized checksums.
MigrationInfostructInformation about an applied migration.
MigrationReconciliationReasonclassWhy a recorded migration checksum was rewritten without re-running the migration.
MigrationResultclassResult of a migration execution.
MigrationRunOptionsclassOptions for migration execution.
MigrationRunnerclassRuns PostgreSQL migrations from filesystem or embedded resources with advisory-lock coordination.
MigrationServiceExtensionsclassExtension methods for registering migration services.
MigrationSqlExecutionContextrecordThe existing runner-owned connection and transaction for one immutable SQL file.
MigrationSqlNormalizerclassReduces migration SQL to a canonical form in which comments and inter-token whitespace have been removed, so that two files whose executable SQL is identical normalize to the same text even when their comments or layout differ.
MigrationStatusrecordCurrent migration status for a module.
MigrationStatusServiceclassImplementation of migration status service.
MigrationTelemetryclassOpenTelemetry instrumentation for database migrations.
MigrationValidatorclassValidates migration files for naming conventions, duplicates, and ordering issues.
MigrationValidator.ValidationErrorrecordValidation error that will block migration execution.
MigrationValidator.ValidationResultrecordValidation result for a set of migrations.
MigrationValidator.ValidationWarningrecordValidation warning that should be addressed but won’t block execution.
PendingMigrationInforecordInformation about a pending migration.
RequiredDatabaseRolerecordA PostgreSQL role that must already exist before a module’s migrations run, together with the install step that provisions it.
StartupMigrationHostclassHosted service that runs database migrations at application startup.
StartupMigrationOptionsclassOptions for startup migration behavior.

AppliedMigrationDetail record

public sealed record AppliedMigrationDetail

Details of an applied migration.

Parameters

AppliedMigrationDetail(string, MigrationCategory, long, bool) constructor

public AppliedMigrationDetail(string Name, MigrationCategory Category, long DurationMs, bool WasDryRun)

Details of an applied migration.

Parameters

Category property

public MigrationCategory Category { get; init; }

The migration category.

DurationMs property

public long DurationMs { get; init; }

How long it ran, in milliseconds.

Name property

public string Name { get; init; }

The migration file name.

WasDryRun property

public bool WasDryRun { get; init; }

Whether it was a dry run, which applies nothing.

DeferredIndexBuilder class

public sealed class DeferredIndexBuilder : BackgroundService

Resumes declared concurrent index builds after the host starts. PostgreSQL session ownership fences both DDL and progress writes: losing the session terminates its work and releases its lock.

DeferredIndexBuilder(string, string, IReadOnlyList<DeferredIndexDefinition>, DeferredIndexOptions, IHostApplicationLifetime, ILogger) constructor

public DeferredIndexBuilder(string connectionString, string ledgerSchema, IReadOnlyList<DeferredIndexDefinition> definitions, DeferredIndexOptions options, IHostApplicationLifetime lifetime, ILogger logger)

Resumes declared concurrent index builds after the host starts. PostgreSQL session ownership fences both DDL and progress writes: losing the session terminates its work and releases its lock.

RunPassAsync(CancellationToken) method

public Task RunPassAsync(CancellationToken cancellationToken)

Attempts each due declared index once; also used by disposable-database convergence tests.

DeferredIndexDefinition record

public sealed record DeferredIndexDefinition

Owner-reviewed deferral of exactly one index statement in an immutable startup migration. The original migration checksum remains the ledger identity. All other SQL still runs at startup.

Parameters

DeferredIndexDefinition(string, string, string, string, string, string, string) constructor

public DeferredIndexDefinition(string MigrationName, string MigrationChecksum, string IndexSchema, string IndexName, string TableName, string IndexStatement, string CatalogDefinition)

Owner-reviewed deferral of exactly one index statement in an immutable startup migration. The original migration checksum remains the ledger identity. All other SQL still runs at startup.

Parameters

CatalogDefinition property

public string CatalogDefinition { get; init; }

The definition the catalog reports for the built index (pg_get_indexdef).

IndexName property

public string IndexName { get; init; }

The index name.

IndexSchema property

public string IndexSchema { get; init; }

The schema of the index.

IndexStatement property

public string IndexStatement { get; init; }

The index statement, as the migration writes it.

MigrationChecksum property

public string MigrationChecksum { get; init; }

The checksum of the migration, its ledger identity.

MigrationName property

public string MigrationName { get; init; }

The migration that holds the index statement.

TableName property

public string TableName { get; init; }

The table of the index.

IsReadyAsync(NpgsqlConnection, NpgsqlTransaction, CancellationToken) method

public Task<bool> IsReadyAsync(NpgsqlConnection connection, NpgsqlTransaction? transaction, CancellationToken cancellationToken)

Checks the actual relation, table, definition and PostgreSQL validity flags.

RemoveFrom(string) method

public string RemoveFrom(string migrationSql)

Validates the pinned input and returns only the non-deferred SQL.

RequireReadyAsync(NpgsqlConnection, NpgsqlTransaction, CancellationToken) method

public Task RequireReadyAsync(NpgsqlConnection connection, NpgsqlTransaction? transaction, CancellationToken cancellationToken)

Refuses an index-dependent query before it can scan the unindexed table.

DeferredIndexNotReadyException class

public sealed class DeferredIndexNotReadyException : InvalidOperationException

An index-dependent operation is temporarily unavailable while maintenance converges.

DeferredIndexNotReadyException(string, string) constructor

public DeferredIndexNotReadyException(string schema, string index)

An index-dependent operation is temporarily unavailable while maintenance converges.

DeferredIndexOptions class

public sealed class DeferredIndexOptions

Bounded post-start maintenance budgets, bindable through the owner’s configuration.

DeferredIndexOptions() constructor

public DeferredIndexOptions()

Creates an instance of DeferredIndexOptions.

BuildTimeoutSeconds property

public int BuildTimeoutSeconds { get; set; }

The statement timeout of one index build, in seconds, from 1 to 86400. The default is 3600.

LockTimeoutSeconds property

public int LockTimeoutSeconds { get; set; }

The lock timeout of one index build, in seconds, from 1 to 300. The default is 10.

MaxRetryDelaySeconds property

public int MaxRetryDelaySeconds { get; set; }

The longest retry delay, in seconds, from DeferredIndexOptions.RetryDelaySecondsto 86400. The default is 900.

PollIntervalSeconds property

public int PollIntervalSeconds { get; set; }

The pause between two checks for pending index builds, in seconds, from 1 to 300. The default is 5.

RetryDelaySeconds property

public int RetryDelaySeconds { get; set; }

The delay before the first retry of a failed build, in seconds, from 1 to 86400; it doubles for each further retry. The default is 30.

IMigrationRunner interface

public interface IMigrationRunner

Interface for running database migrations.

ModuleName property

string ModuleName { get; }

Gets the module name for this migration runner.

SchemaName property

string SchemaName { get; }

Gets the schema name for this migration runner.

GetAppliedMigrationInfoAsync(CancellationToken) method

Task<IReadOnlyList<MigrationInfo>> GetAppliedMigrationInfoAsync(CancellationToken cancellationToken = default)

Gets all applied migrations.

GetCurrentVersionAsync(CancellationToken) method

Task<string?> GetCurrentVersionAsync(CancellationToken cancellationToken = default)

Gets the current migration version (latest applied migration).

RunAsync(string, MigrationRunOptions, CancellationToken) method

Task<MigrationResult> RunAsync(string migrationsPath, MigrationRunOptions? options = null, CancellationToken cancellationToken = default)

Runs pending migrations from the specified path.

Parameters

Returns

Result of migration execution.

RunFromAssemblyAsync(Assembly, string, MigrationRunOptions, CancellationToken) method

Task<MigrationResult> RunFromAssemblyAsync(Assembly assembly, string? resourcePrefix = null, MigrationRunOptions? options = null, CancellationToken cancellationToken = default)

Runs pending migrations from embedded resources in an assembly.

Parameters

Returns

Result of migration execution.

ValidateChecksumsAsync(Assembly, string, CancellationToken) method

Task<IReadOnlyList<string>> ValidateChecksumsAsync(Assembly assembly, string? resourcePrefix = null, CancellationToken cancellationToken = default)

Validates checksums of applied migrations against source files.

Parameters

Returns

List of checksum validation errors, empty if all valid.

IMigrationSqlExecutor interface

public interface IMigrationSqlExecutor

Optional module-owned SQL execution policy. The runner retains locks, checksums and ledger commits.

ExecuteAsync(MigrationSqlExecutionContext, CancellationToken) method

Task ExecuteAsync(MigrationSqlExecutionContext context, CancellationToken cancellationToken)

Runs the SQL of one migration on the runner’s connection and transaction.

Parameters

Returns

A task that completes when the SQL has run.

IMigrationStatusService interface

public interface IMigrationStatusService

Service for querying migration status without applying migrations.

GetStatusAsync(CancellationToken) method

Task<MigrationStatus> GetStatusAsync(CancellationToken cancellationToken = default)

Gets the current migration status for the module.

MigrationAssemblySource record

public sealed record MigrationAssemblySource

Migration source descriptor (assembly + optional resource prefix).

Parameters

MigrationAssemblySource(Assembly, string) constructor

public MigrationAssemblySource(Assembly MigrationsAssembly, string? ResourcePrefix = null)

Migration source descriptor (assembly + optional resource prefix).

Parameters

MigrationsAssembly property

public Assembly MigrationsAssembly { get; init; }

The assembly that embeds the migrations.

ResourcePrefix property

public string? ResourcePrefix { get; init; }

Only the resources whose names contain this text, ignoring case; all when not set.

MigrationCategory enum

public enum MigrationCategory

Categorizes migrations by when they should be executed.

ValueDescription
Startup = 0Automatic migrations that run at application startup. Must be non-breaking and complete quickly (< 60s). Prefix: 001-099
Release = 1Manual migrations that require CLI execution before deployment. Used for breaking changes that need coordination. Prefix: 100-199
Seed = 2Optional seed/demo data that is inserted only when an operator runs it explicitly. Prefix: S001-S999
Data = 3Long-running data migrations that run as background jobs. Prefix: DM001-DM999

MigrationCategoryExtensions class

public static class MigrationCategoryExtensions

Extension methods for migration category operations.

GetCategory(string) method

public static MigrationCategory GetCategory(string migrationName)

Determines the category of a migration based on its filename.

IsAutomatic(MigrationCategory) extension method

public static bool IsAutomatic(this MigrationCategory category)

Returns true if this migration should run automatically at startup.

RequiresManualExecution(MigrationCategory) extension method

public static bool RequiresManualExecution(this MigrationCategory category)

Returns true if this migration requires manual CLI execution before startup may proceed. Seed migrations are intentionally excluded because they are opt-in/manual only and must not block runtime.

MigrationChecksum class

public static class MigrationChecksum

Canonical checksum computation for migration SQL content.

Remarks

The migration host records a SHA-256 checksum of each applied migration’s SQL and re-validates it on every startup so that an accidental edit to an already-applied migration is caught (migrations are forward-only). The checksum MUST be stable across operating systems and source checkouts; otherwise a clone with CRLF line endings produces a different hash than one with LF endings for byte-identical SQL, and the host fails closed on a non-drift.

MigrationChecksum.Compute(string)therefore normalizes all line endings to \n before hashing so the same logical SQL hashes identically regardless of how it was checked out.

MigrationChecksum.ComputeRaw(string)hashes the bytes as-is (no normalization). It exists ONLY to recognize a legacy schema_migrations row whose stored checksum was written by an older host build (or a different-line-ending checkout) that hashed the raw bytes. Such a row is the same SQL, just hashed before normalization existed; the host self-heals it to the normalized value rather than treating it as drift (see MigrationChecksum.IsSelfHealableLegacyChecksum(string, string)). A genuine content change matches no line-ending rendering and still fails closed.

Compute(string) method

public static string Compute(string content)

Computes the canonical, line-ending-normalized SHA-256 checksum (lowercase hex) of the supplied migration SQL content.

Parameters

Returns

Lowercase hex SHA-256 of the LF-normalized content.

ComputeRaw(string) method

public static string ComputeRaw(string content)

Computes the SHA-256 checksum (lowercase hex) of the supplied content WITHOUT any line-ending normalization. This reproduces the historical, pre-normalization hash form used to detect a self-healable legacy checksum.

Parameters

Returns

Lowercase hex SHA-256 of the raw content bytes.

IsSelfHealableLegacyChecksum(string, string) method

public static bool IsSelfHealableLegacyChecksum(string content, string storedChecksum)

Determines whether a stored checksum that does not match the canonical (MigrationChecksum.Compute(string)) checksum is nonetheless a self-healable legacy value: the raw, un-normalized hash of the SAME logical SQL under a different line-ending rendering (e.g. a CRLF checkout recorded the row, but the host now reads/normalizes LF, or vice versa).

Parameters

Returns

true when storedChecksum equals the raw hash of either the all-LF or the all-CRLF rendering of the same SQL (and therefore differs from the canonical hash only because of historical non-normalization); false for a genuine content change or when the stored value already equals the canonical hash.

MigrationChecksumReconciliationPin record

public sealed record MigrationChecksumReconciliationPin

An owner-declared statement that one specific already-applied checksum was produced by content whose executable SQL matches the current file — used to reconcile a database whose row was written before the host recorded normalized checksums.

Parameters

Remarks

A pin is not a blanket exemption. The host accepts it only when all three hold: the database’s stored checksum equals MigrationChecksumReconciliationPin.AppliedChecksumexactly; the current file normalizes successfully; and that normalized form hashes to MigrationChecksumReconciliationPin.AppliedNormalizedChecksum. So a pin is bound to one exact pair of contents: a later DDL edit on top of a pinned file changes the normalized hash and fails closed again, and a pin authored against different content never matches.

A pin also expires on use: once the row is reconciled its checksum is the file’s, so the first condition can never match again.

MigrationChecksumReconciliationPin.AppliedNormalizedChecksumis derived from the historical content — read the applied version out of source control and run it through MigrationSqlNormalizer.TryComputeNormalizedChecksum(string, out string). Deriving it from the current file instead would make the pin self-confirming and prove nothing.

MigrationChecksumReconciliationPin(string, string, string, string) constructor

public MigrationChecksumReconciliationPin(string MigrationName, string AppliedChecksum, string AppliedNormalizedChecksum, string Justification)

An owner-declared statement that one specific already-applied checksum was produced by content whose executable SQL matches the current file — used to reconcile a database whose row was written before the host recorded normalized checksums.

Parameters

Remarks

A pin is not a blanket exemption. The host accepts it only when all three hold: the database’s stored checksum equals MigrationChecksumReconciliationPin.AppliedChecksumexactly; the current file normalizes successfully; and that normalized form hashes to MigrationChecksumReconciliationPin.AppliedNormalizedChecksum. So a pin is bound to one exact pair of contents: a later DDL edit on top of a pinned file changes the normalized hash and fails closed again, and a pin authored against different content never matches.

A pin also expires on use: once the row is reconciled its checksum is the file’s, so the first condition can never match again.

MigrationChecksumReconciliationPin.AppliedNormalizedChecksumis derived from the historical content — read the applied version out of source control and run it through MigrationSqlNormalizer.TryComputeNormalizedChecksum(string, out string). Deriving it from the current file instead would make the pin self-confirming and prove nothing.

AppliedChecksum property

public string AppliedChecksum { get; init; }

Whole-file checksum the database currently holds for that row.

AppliedNormalizedChecksum property

public string AppliedNormalizedChecksum { get; init; }

Normalized checksum of the content that produced AppliedChecksum.

IsRuledEdit property

public bool IsRuledEdit { get; }

True when this pin records an owner-ruled SQL edit rather than a comment-only legacy row.

Justification property

public string Justification { get; init; }

Short audit note (commit + what changed), persisted with the ledger row.

MigrationName property

public string MigrationName { get; init; }

File name as recorded in schema_migrations.migration_name.

RuledEditNormalizedChecksum property

public string? RuledEditNormalizedChecksum { get; init; }

Set only for a recorded exception to the forward-only rule: the normalized checksum of the ONE edited file content accepted in place of the applied content. When set, the pin matches a row whose stored checksum is MigrationChecksumReconciliationPin.AppliedChecksumor whose recorded normalized checksum is MigrationChecksumReconciliationPin.AppliedNormalizedChecksum, and it reconciles only when the current file normalizes to this value; any further edit fails closed. Leave null for a comment-only legacy pin, whose executable SQL must be unchanged.

Ruling property

public string? Ruling { get; init; }

The ruling that authorised the edit (date and record), persisted with the justification.

MigrationInfo struct

public readonly struct MigrationInfo : IEquatable<MigrationInfo>

Information about an applied migration.

Parameters

MigrationInfo(string, DateTimeOffset, string) constructor

public MigrationInfo(string Name, DateTimeOffset AppliedAt, string Checksum)

Information about an applied migration.

Parameters

AppliedAt property

public DateTimeOffset AppliedAt { get; init; }

When it was applied.

Checksum property

public string Checksum { get; init; }

The checksum recorded when it was applied.

Name property

public string Name { get; init; }

The migration file name.

MigrationReconciliationReason class

public static class MigrationReconciliationReason

Why a recorded migration checksum was rewritten without re-running the migration. Persisted verbatim in <schema>.schema_migration_reconciliations.reason.

CommentOnly constant

public const string CommentOnly = "comment-only-reconciliation"

The file’s SQL is unchanged once comments and layout are removed; only comments/whitespace moved.

LegacyPin constant

public const string LegacyPin = "legacy-pin-reconciliation"

The row predates normalized-checksum tracking, and an owner-declared pin proved the applied content and the current file normalize to the same SQL.

LineEnding constant

public const string LineEnding = "line-ending-reconciliation"

The stored value was the pre-normalization hash of the same SQL under different line endings.

RuledEdit constant

public const string RuledEdit = "ruled-edit-reconciliation"

The executable SQL of an applied migration was changed under a recorded exception to the forward-only rule. The pin binds the historical content to the one accepted edited form; the migration is not re-run.

MigrationResult class

public sealed class MigrationResult

Result of a migration execution.

MigrationResult() constructor

public MigrationResult()

Creates an instance of MigrationResult.

AppliedCount property

public int AppliedCount { get; init; }

Number of migrations applied.

AppliedMigrations property

public IReadOnlyList<AppliedMigrationDetail> AppliedMigrations { get; init; }

Details of applied migrations.

ChecksumErrors property

public IReadOnlyList<string> ChecksumErrors { get; init; }

Checksum validation errors, if any.

DurationMs property

public long DurationMs { get; init; }

Total duration in milliseconds.

ErrorMessage property

public string? ErrorMessage { get; init; }

Error message if migration failed.

FilteredCount property

public int FilteredCount { get; init; }

Number of migrations filtered out by category.

SkippedCount property

public int SkippedCount { get; init; }

Number of migrations skipped (already applied).

Success property

public bool Success { get; init; }

Whether the migration run was successful.

Failed(string, IReadOnlyList<string>) method

public static MigrationResult Failed(string errorMessage, IReadOnlyList<string>? checksumErrors = null)

Creates a failed result.

Successful(int, int, int, long, IReadOnlyList<AppliedMigrationDetail>) method

public static MigrationResult Successful(int appliedCount, int skippedCount, int filteredCount, long durationMs, IReadOnlyList<AppliedMigrationDetail> appliedMigrations)

Creates a successful result.

MigrationRunOptions class

public sealed class MigrationRunOptions

Options for migration execution.

MigrationRunOptions() constructor

public MigrationRunOptions()

Creates an instance of MigrationRunOptions.

CategoryFilter property

public MigrationCategory? CategoryFilter { get; set; }

Filter migrations by category. If null, all categories are included.

ChecksumReconciliationPins property

public IList<MigrationChecksumReconciliationPin> ChecksumReconciliationPins { get; }

Owner-declared reconciliations for rows written before the runner recorded normalized checksums. Same contract as StartupMigrationOptions.ChecksumReconciliationPins.

DryRun property

public bool DryRun { get; set; }

If true, only show what would be executed without applying.

FailOnChecksumMismatch property

public bool FailOnChecksumMismatch { get; set; }

If true, fail if checksum validation errors are found.

TimeoutSeconds property

public int TimeoutSeconds { get; set; }

Timeout in seconds for individual migration execution. Default: 300.

ValidateChecksums property

public bool ValidateChecksums { get; set; }

If true, validate checksums before applying new migrations.

MigrationRunner class

public sealed class MigrationRunner : IMigrationRunner

Runs PostgreSQL migrations from filesystem or embedded resources with advisory-lock coordination.

MigrationRunner(string, string, string, ILogger) constructor

public MigrationRunner(string connectionString, string schemaName, string moduleName, ILogger logger)

Creates a runner for the migrations of a module.

Parameters

Exceptions

ModuleName property

public string ModuleName { get; }

Gets the module name for this migration runner.

SchemaName property

public string SchemaName { get; }

Gets the schema name for this migration runner.

GetAppliedMigrationInfoAsync(CancellationToken) method

public Task<IReadOnlyList<MigrationInfo>> GetAppliedMigrationInfoAsync(CancellationToken cancellationToken = default)

Gets all applied migrations.

GetCurrentVersionAsync(CancellationToken) method

public Task<string?> GetCurrentVersionAsync(CancellationToken cancellationToken = default)

Gets the current migration version (latest applied migration).

RunAsync(string, MigrationRunOptions, CancellationToken) method

public Task<MigrationResult> RunAsync(string migrationsPath, MigrationRunOptions? options = null, CancellationToken cancellationToken = default)

Runs pending migrations from the specified path.

Parameters

Returns

Result of migration execution.

RunFromAssemblyAsync(Assembly, string, MigrationRunOptions, CancellationToken) method

public Task<MigrationResult> RunFromAssemblyAsync(Assembly assembly, string? resourcePrefix = null, MigrationRunOptions? options = null, CancellationToken cancellationToken = default)

Runs pending migrations from embedded resources in an assembly.

Parameters

Returns

Result of migration execution.

ValidateChecksumsAsync(Assembly, string, CancellationToken) method

public Task<IReadOnlyList<string>> ValidateChecksumsAsync(Assembly assembly, string? resourcePrefix = null, CancellationToken cancellationToken = default)

Validates checksums of applied migrations against source files.

Parameters

Returns

List of checksum validation errors, empty if all valid.

MigrationServiceExtensions class

public static class MigrationServiceExtensions

Extension methods for registering migration services.

AddMigrationRunner<TOptions>(IServiceCollection, string, string, Func<TOptions, string>) extension method

public static IServiceCollection AddMigrationRunner<TOptions>(this IServiceCollection services, string schemaName, string moduleName, Func<TOptions, string> connectionStringSelector) where TOptions : class

Adds a migration runner as a singleton for manual/CLI migration execution.

AddMigrationStatus<TOptions>(IServiceCollection, string, string, Assembly, Func<TOptions, string>, string) extension method

public static IServiceCollection AddMigrationStatus<TOptions>(this IServiceCollection services, string schemaName, string moduleName, Assembly migrationsAssembly, Func<TOptions, string> connectionStringSelector, string? resourcePrefix = null) where TOptions : class

Adds the migration status service for querying migration state.

AddStartupMigrations(IServiceCollection, string, string, Assembly, Action<StartupMigrationOptions>) extension method

public static IServiceCollection AddStartupMigrations(this IServiceCollection services, string schemaName, string moduleName, Assembly migrationsAssembly, Action<StartupMigrationOptions>? configureOptions = null)

Adds a startup migration host using PostgresOptions.

AddStartupMigrations<TOptions>(IServiceCollection, string, string, Assembly, Func<TOptions, string>, Action<StartupMigrationOptions>) extension method

public static IServiceCollection AddStartupMigrations<TOptions>(this IServiceCollection services, string schemaName, string moduleName, Assembly migrationsAssembly, Func<TOptions, string> connectionStringSelector, Action<StartupMigrationOptions>? configureOptions = null) where TOptions : class

Adds a startup migration host for the specified module.

Type parameters

Parameters

Returns

Service collection for chaining.

MigrationSqlExecutionContext record

public sealed record MigrationSqlExecutionContext

The existing runner-owned connection and transaction for one immutable SQL file.

Parameters

MigrationSqlExecutionContext(NpgsqlConnection, NpgsqlTransaction, string, string, int) constructor

public MigrationSqlExecutionContext(NpgsqlConnection Connection, NpgsqlTransaction? Transaction, string MigrationName, string Sql, int CommandTimeoutSeconds)

The existing runner-owned connection and transaction for one immutable SQL file.

Parameters

CommandTimeoutSeconds property

public int CommandTimeoutSeconds { get; init; }

The command timeout, in seconds.

Connection property

public NpgsqlConnection Connection { get; init; }

The runner’s open connection.

MigrationName property

public string MigrationName { get; init; }

The migration.

Sql property

public string Sql { get; init; }

The SQL of the migration file.

Transaction property

public NpgsqlTransaction? Transaction { get; init; }

The runner’s transaction; none for a migration that runs outside one.

MigrationSqlNormalizer class

public static class MigrationSqlNormalizer

Reduces migration SQL to a canonical form in which comments and inter-token whitespace have been removed, so that two files whose executable SQL is identical normalize to the same text even when their comments or layout differ.

Remarks

Why this exists. MigrationChecksumhashes the whole file, which is correct for detecting drift but means a comment edit to an already-applied migration blocks deployment exactly as hard as an altered DDL statement: a host built after a comment-only edit would fail to start against every database that had applied the original file. The normalizer supplies the evidence needed to tell “someone changed a comment” apart from “someone changed the schema”, so the first can be reconciled forward and the second still fails closed.

It is deliberately conservative. A normalizer that is clever about ambiguous input is worse than one that refuses: a wrong answer here reconciles a real DDL change. Every construct whose extent cannot be determined without knowing server settings, and every unterminated construct, produces a refusal (MigrationSqlNormalizer.TryNormalize(string, out string, out string)returns false) and the caller must fall back to failing closed.

Rules. Line endings are normalized to \n first (matching MigrationChecksum.Compute(string)). Then, outside of string literals: -- line comments and /* */ block comments (PostgreSQL block comments nest) are replaced by a single separator, and every run of whitespace collapses to one space. Single-quoted literals, E'' escape literals, double-quoted identifiers and dollar-quoted bodies are copied through verbatim — including any whitespace and any -- or /* they contain, which are data, not comments.

Whitespace normalizes too, on the same terms: re-indenting a statement does not change what it does. Whitespace inside a literal is preserved, because 'a b' and 'a b' are different values.

TryComputeNormalizedChecksum(string, out string) method

public static string? TryComputeNormalizedChecksum(string content, out string? refusal)

Computes the SHA-256 (lowercase hex) of the normalized form of content.

Parameters

Returns

The normalized checksum, or null when normalization was refused.

TryNormalize(string, out string, out string) method

public static bool TryNormalize(string content, out string normalized, out string? refusal)

Attempts to reduce content to its comment-free, whitespace-collapsed form.

Parameters

Returns

true when the content was fully understood; otherwise false.

MigrationStatus record

public sealed record MigrationStatus

Current migration status for a module.

MigrationStatus() constructor

public MigrationStatus()

Creates an instance of MigrationStatus.

AppliedCount property

public int AppliedCount { get; init; }

Number of applied migrations.

ChecksumErrors property

public IReadOnlyList<string> ChecksumErrors { get; init; }

Any checksum mismatches detected.

HasBlockingIssues property

public bool HasBlockingIssues { get; }

Whether there are blocking issues (pending release migrations or checksum errors).

IsUpToDate property

public bool IsUpToDate { get; }

Whether the database is up to date (no pending startup/release migrations).

LastAppliedAt property

public DateTimeOffset? LastAppliedAt { get; init; }

When the last migration was applied.

LastAppliedMigration property

public string? LastAppliedMigration { get; init; }

Last applied migration name.

ModuleName property

public required string ModuleName { get; init; }

Module name.

PendingIndexCount property

public int PendingIndexCount { get; init; }

Index obligations whose post-start completion has not been recorded.

PendingMigrations property

public IReadOnlyList<PendingMigrationInfo> PendingMigrations { get; init; }

List of pending migrations.

PendingReleaseCount property

public int PendingReleaseCount { get; init; }

Number of pending release migrations.

PendingStartupCount property

public int PendingStartupCount { get; init; }

Number of pending startup migrations.

SchemaName property

public required string SchemaName { get; init; }

Schema name.

MigrationStatusService class

public sealed class MigrationStatusService : IMigrationStatusService

Implementation of migration status service.

MigrationStatusService(string, string, string, Assembly, ILogger, string) constructor

public MigrationStatusService(string connectionString, string schemaName, string moduleName, Assembly migrationsAssembly, ILogger logger, string? resourcePrefix = null)

Creates the status service for the migrations of one assembly.

Parameters

MigrationStatusService(string, string, string, IReadOnlyList<MigrationAssemblySource>, ILogger) constructor

public MigrationStatusService(string connectionString, string schemaName, string moduleName, IReadOnlyList<MigrationAssemblySource> migrationSources, ILogger logger)

Creates the status service for the migrations of several sources.

Parameters

Exceptions

GetStatusAsync(CancellationToken) method

public Task<MigrationStatus> GetStatusAsync(CancellationToken cancellationToken = default)

Gets the current migration status for the module.

MigrationTelemetry class

public static class MigrationTelemetry

OpenTelemetry instrumentation for database migrations.

ActivitySourceName constant

public const string ActivitySourceName = "StellaOps.Infrastructure.Postgres.Migrations"

The name of the activity source for migration tracing.

MeterName constant

public const string MeterName = "StellaOps.Infrastructure.Postgres.Migrations"

The name of the meter for migration metrics.

RecordChecksumError(string, string) method

public static void RecordChecksumError(string moduleName, string migrationName)

Records a checksum validation error.

RecordLockAcquired(string, string, double) method

public static void RecordLockAcquired(string moduleName, string schemaName, double waitSeconds)

Records a successful lock acquisition.

RecordLockTimeout(string, string) method

public static void RecordLockTimeout(string moduleName, string schemaName)

Records a lock acquisition timeout.

RecordMigrationApplied(string, string, MigrationCategory, double) method

public static void RecordMigrationApplied(string moduleName, string migrationName, MigrationCategory category, double durationSeconds)

Records a successful migration application.

RecordMigrationFailed(string, string, MigrationCategory, string) method

public static void RecordMigrationFailed(string moduleName, string migrationName, MigrationCategory category, string errorCode)

Records a migration failure.

SetActivityError(Activity, Exception) method

public static void SetActivityError(Activity? activity, Exception exception)

Sets the error on an activity.

SetActivitySuccess(Activity, int) method

public static void SetActivitySuccess(Activity? activity, int appliedCount)

Marks an activity as successful.

StartLockAcquisition(string, string) method

public static Activity? StartLockAcquisition(string moduleName, string schemaName)

Starts an activity for advisory lock acquisition.

StartMigrationApply(string, string, MigrationCategory) method

public static Activity? StartMigrationApply(string moduleName, string migrationName, MigrationCategory category)

Starts an activity for a single migration.

StartMigrationRun(string, string, int) method

public static Activity? StartMigrationRun(string moduleName, string schemaName, int pendingCount)

Starts an activity for migration execution.

MigrationValidator class

public static class MigrationValidator

Validates migration files for naming conventions, duplicates, and ordering issues.

DetectDuplicatePrefixes(IEnumerable<string>) method

public static IReadOnlyList<(string Prefix, IReadOnlyList<string> Names)> DetectDuplicatePrefixes(IEnumerable<string> migrationNames)

Detects migrations with duplicate numeric prefixes.

ExtractNumericPrefix(string) method

public static string? ExtractNumericPrefix(string migrationName)

Extracts the numeric prefix from a migration name.

Validate(IEnumerable<string>) method

public static MigrationValidator.ValidationResult Validate(IEnumerable<string> migrationNames)

Validates a collection of migration file names.

MigrationValidator.ValidationError record

public sealed record ValidationError

Validation error that will block migration execution.

Parameters

ValidationError(string, string, string) constructor

public ValidationError(string Code, string Message, string? MigrationName = null)

Validation error that will block migration execution.

Parameters

Code property

public string Code { get; init; }

The error code.

Message property

public string Message { get; init; }

The message.

MigrationName property

public string? MigrationName { get; init; }

The migration the error concerns; none when it concerns the set.

MigrationValidator.ValidationResult record

public sealed record ValidationResult

Validation result for a set of migrations.

ValidationResult() constructor

public ValidationResult()

Creates an instance of MigrationValidator.ValidationResult.

Errors property

public IReadOnlyList<MigrationValidator.ValidationError> Errors { get; init; }

The errors.

IsValid property

public bool IsValid { get; }

Whether there is no error.

Warnings property

public IReadOnlyList<MigrationValidator.ValidationWarning> Warnings { get; init; }

The warnings.

Failed(IReadOnlyList<MigrationValidator.ValidationError>, IReadOnlyList<MigrationValidator.ValidationWarning>) method

public static MigrationValidator.ValidationResult Failed(IReadOnlyList<MigrationValidator.ValidationError> errors, IReadOnlyList<MigrationValidator.ValidationWarning>? warnings = null)

A result with errors.

Parameters

Returns

The result.

Success(IReadOnlyList<MigrationValidator.ValidationWarning>) method

public static MigrationValidator.ValidationResult Success(IReadOnlyList<MigrationValidator.ValidationWarning>? warnings = null)

A result without errors.

Parameters

Returns

The result.

MigrationValidator.ValidationWarning record

public sealed record ValidationWarning

Validation warning that should be addressed but won’t block execution.

Parameters

ValidationWarning(string, string, string) constructor

public ValidationWarning(string Code, string Message, string? MigrationName = null)

Validation warning that should be addressed but won’t block execution.

Parameters

Code property

public string Code { get; init; }

The warning code.

Message property

public string Message { get; init; }

The message.

MigrationName property

public string? MigrationName { get; init; }

The migration the warning concerns; none when it concerns the set.

PendingMigrationInfo record

public sealed record PendingMigrationInfo

Information about a pending migration.

Parameters

PendingMigrationInfo(string, MigrationCategory) constructor

public PendingMigrationInfo(string Name, MigrationCategory Category)

Information about a pending migration.

Parameters

Category property

public MigrationCategory Category { get; init; }

The migration category.

Name property

public string Name { get; init; }

The migration file name.

RequiredDatabaseRole record

public sealed record RequiredDatabaseRole

A PostgreSQL role that must already exist before a module’s migrations run, together with the install step that provisions it.

Parameters

Remarks

A schema migration runs as the service’s OWN role, and that role is provisioned NOSUPERUSER NOCREATEDB NOCREATEROLE. It therefore cannot create a role, so a migration must never provision one: role creation belongs to the install/bootstrap path, which runs as the superuser.

An applied migration is immutable (migrations are forward-only), so a migration that carries a guarded IF NOT EXISTS … CREATE ROLE block keeps it. The block is inert wherever the role already exists, and it is a hard boot failure on a from-scratch install whose service role is least-privileged: PostgreSQL answers 42501 permission denied to create role and the host stops at app.Run().

Declaring the role here converts that into a named, actionable startup failure raised BEFORE the baseline is reached, and — because the guard short-circuits once the role exists — pre-creating the role from the install path means the CREATE ROLE statement is never executed at all.

RequiredDatabaseRole(string, string) constructor

public RequiredDatabaseRole(string Name, string Provisioning)

A PostgreSQL role that must already exist before a module’s migrations run, together with the install step that provisions it.

Parameters

Remarks

A schema migration runs as the service’s OWN role, and that role is provisioned NOSUPERUSER NOCREATEDB NOCREATEROLE. It therefore cannot create a role, so a migration must never provision one: role creation belongs to the install/bootstrap path, which runs as the superuser.

An applied migration is immutable (migrations are forward-only), so a migration that carries a guarded IF NOT EXISTS … CREATE ROLE block keeps it. The block is inert wherever the role already exists, and it is a hard boot failure on a from-scratch install whose service role is least-privileged: PostgreSQL answers 42501 permission denied to create role and the host stops at app.Run().

Declaring the role here converts that into a named, actionable startup failure raised BEFORE the baseline is reached, and — because the guard short-circuits once the role exists — pre-creating the role from the install path means the CREATE ROLE statement is never executed at all.

FailurePrefix constant

public const string FailurePrefix = "Migration preflight"

The stable prefix every missing-role failure carries, so operators, log scrapes and tests can tell this apart from the raw 42501 it replaces.

Name property

public string Name { get; init; }

The role name, exactly as the module’s SQL expects it (for example orders_admin).

Provisioning property

public string Provisioning { get; init; }

One sentence naming the install step that creates the role. It is shown verbatim to the operator in the startup failure, so it must point at a real, current artifact.

FormatMissingMessage(string) method

public string FormatMissingMessage(string moduleName)

Builds the operator-facing message for a role that is absent.

StartupMigrationHost class

public abstract class StartupMigrationHost : IHostedService

Hosted service that runs database migrations at application startup. Uses advisory locks to prevent race conditions in multi-instance deployments.

Remarks

This service: - Acquires an advisory lock to prevent concurrent migrations - Validates checksums of already-applied migrations - Blocks startup if pending release/data migrations exist - Runs only startup migrations automatically; seed migrations remain operator-invoked

StartupMigrationHost(string, string, string, Assembly, ILogger, IHostApplicationLifetime, StartupMigrationOptions) constructor

protected StartupMigrationHost(string connectionString, string schemaName, string moduleName, Assembly migrationsAssembly, ILogger logger, IHostApplicationLifetime lifetime, StartupMigrationOptions? options = null)

Creates a new startup migration host.

OpenConnectionAsync(CancellationToken) method

protected virtual Task<NpgsqlConnection> OpenConnectionAsync(CancellationToken cancellationToken)

Opens the PostgreSQL connection used by the startup migration pass.

Remarks

This seam keeps transient-startup retry behavior directly testable without weakening the fail-closed handling of migration and authentication errors.

StartAsync(CancellationToken) method

public Task StartAsync(CancellationToken cancellationToken)

See IHostedService.StartAsync(CancellationToken).

StopAsync(CancellationToken) method

public Task StopAsync(CancellationToken cancellationToken)

See IHostedService.StopAsync(CancellationToken).

StartupMigrationOptions class

public sealed class StartupMigrationOptions

Options for startup migration behavior.

StartupMigrationOptions() constructor

public StartupMigrationOptions()

Creates an instance of StartupMigrationOptions.

ChecksumReconciliationPins property

public IList<MigrationChecksumReconciliationPin> ChecksumReconciliationPins { get; }

Owner-declared reconciliations for databases whose schema_migrations rows were written before the host recorded normalized checksums. Default: none.

Remarks

Only needed for a migration that was edited between the applying build and this one. Comment-only edits made from here on reconcile without a pin, because the applying host records the normalized checksum alongside the whole-file one. Each pin is checked against the file before it is honoured — see MigrationChecksumReconciliationPin.

ConnectionRetryDelayMilliseconds property

public int ConnectionRetryDelayMilliseconds { get; set; }

Delay between transient PostgreSQL connection attempts. Default: 1000 ms.

ConnectionRetryTimeoutSeconds property

public int ConnectionRetryTimeoutSeconds { get; set; }

Maximum time to retry transient PostgreSQL connection failures while the database is recovering or starting. Default: 60 seconds. Set to zero to retain single-attempt behavior.

DeferredIndexBuild property

public DeferredIndexOptions DeferredIndexBuild { get; set; }

Owner-configured budgets for the resumable concurrent index builder.

DeferredIndexes property

public IList<DeferredIndexDefinition> DeferredIndexes { get; }

Explicit immutable migration/index contracts whose builds continue after startup.

Enabled property

public bool Enabled { get; set; }

Whether to run migrations at startup. Default: true.

FailOnChecksumMismatch property

public bool FailOnChecksumMismatch { get; set; }

Whether to fail startup if checksum validation fails. Default: true.

FailOnLockTimeout property

public bool FailOnLockTimeout { get; set; }

Whether to fail startup if lock cannot be acquired. Default: true.

FailOnMigrationError property

public bool FailOnMigrationError { get; set; }

Whether to fail startup if migration execution fails. Default: true.

FailOnPendingReleaseMigrations property

public bool FailOnPendingReleaseMigrations { get; set; }

Whether to fail startup if there are pending release migrations. Default: true.

LockTimeoutSeconds property

public int LockTimeoutSeconds { get; set; }

Timeout in seconds for acquiring the advisory lock. Default: 120.

MigrationTimeoutSeconds property

public int MigrationTimeoutSeconds { get; set; }

Timeout in seconds for individual migration execution. Default: 300.

RequiredRoles property

public IList<RequiredDatabaseRole> RequiredRoles { get; }

PostgreSQL roles the module’s SQL expects to already exist. Verified before any migration runs; an absent role fails startup with the message RequiredDatabaseRole.FormatMissingMessage(string)produces. Default: none.

Remarks

See RequiredDatabaseRolefor why a migration may not provision a role itself. Declaring one here is a fail-closed assertion, never a creation: the host has no more privilege than the service role it connects as.

ResourcePrefix property

public string? ResourcePrefix { get; set; }

Optional embedded-resource prefix used to isolate one migration stream when an assembly contains SQL for multiple modules. Default: no filter.

RunSeedMigrations property

public bool RunSeedMigrations { get; set; }

Whether to apply pending Seed-category migrations at startup. Default: false.

Remarks

Seed migrations are normally run only by an operator, so that production deployments do not silently load demonstration data. A host whose seeds are for development or bootstrap only may opt in by setting this to true when it detects an explicit bootstrap-enabled setting of its own. When the flag is left at the default false, the host does not apply seed migrations and logs the “Run manually when needed” guidance line.

SqlExecutor property

public IMigrationSqlExecutor? SqlExecutor { get; set; }

Optional module policy for SQL execution; it never owns migration-ledger or transaction completion.

StellaOps.Infrastructure.Postgres.Options namespace

TypeKindDescription
PostgresOptionsclassPostgreSQL connection and behavior options.

PostgresOptions class

public sealed class PostgresOptions

PostgreSQL connection and behavior options.

PostgresOptions() constructor

public PostgresOptions()

Creates an instance of PostgresOptions.

ApplicationName property

public string? ApplicationName { get; set; }

Stable PostgreSQL application name used for runtime attribution.

AutoMigrate property

public bool AutoMigrate { get; set; }

Enable automatic migration on startup. Default is false for production safety.

CommandTimeoutSeconds property

public int CommandTimeoutSeconds { get; set; }

Command timeout in seconds. Default is 30 seconds.

ConnectionIdleLifetimeSeconds property

public int ConnectionIdleLifetimeSeconds { get; set; }

Connection idle lifetime in seconds. Default is 300 seconds (5 minutes).

ConnectionString property

public required string ConnectionString { get; set; }

PostgreSQL connection string.

MaxPoolSize property

public int MaxPoolSize { get; set; }

Maximum number of connections in the pool. Default is 100.

MigrationsPath property

public string? MigrationsPath { get; set; }

Path to SQL migration files. Required if AutoMigrate is true.

MinPoolSize property

public int MinPoolSize { get; set; }

Minimum number of connections in the pool. Default is 1.

Pooling property

public bool Pooling { get; set; }

Enable connection pooling. Default is true.

SchemaName property

public string? SchemaName { get; set; }

Schema name for module-specific tables. If null, uses public schema.

StellaOps.Infrastructure.Postgres.Repositories namespace

TypeKindDescription
RepositoryBase<TDataSource>classBase class for PostgreSQL repositories providing common patterns and utilities.

RepositoryBase<TDataSource> class

public abstract class RepositoryBase<TDataSource> where TDataSource : DataSourceBase

Base class for PostgreSQL repositories providing common patterns and utilities.

Type parameters

RepositoryBase(TDataSource, ILogger) constructor

protected RepositoryBase(TDataSource dataSource, ILogger logger)

Creates a new repository with the specified data source and logger.

CommandTimeoutSeconds property

protected int CommandTimeoutSeconds { get; }

Command timeout from data source options.

DataSource property

protected TDataSource DataSource { get; }

The data source for database connections.

Logger property

protected ILogger Logger { get; }

Logger for this repository.

AddJsonbParameter(NpgsqlCommand, string, string) method

protected static void AddJsonbParameter(NpgsqlCommand command, string name, string? jsonValue)

Adds a typed JSONB parameter to the command.

AddParameter(NpgsqlCommand, string, object) method

protected static void AddParameter(NpgsqlCommand command, string name, object? value)

Adds a parameter to the command, handling null values.

AddTextArrayParameter(NpgsqlCommand, string, string[]) method

protected static void AddTextArrayParameter(NpgsqlCommand command, string name, string[]? values)

Adds a text array parameter to the command.

AddUuidArrayParameter(NpgsqlCommand, string, Guid[]) method

protected static void AddUuidArrayParameter(NpgsqlCommand command, string name, Guid[]? values)

Adds a UUID array parameter to the command.

BuildOrderByClause(string, bool, string) method

protected static string BuildOrderByClause(string primaryColumn, bool descending = false, string? tiebreaker = "id")

Builds ORDER BY clause with deterministic ordering. Always includes a unique column (typically id) as tiebreaker for pagination stability.

BuildPaginationClause(int, int) method

protected static string BuildPaginationClause(int limit, int offset)

Builds LIMIT/OFFSET clause for pagination.

BuildWhereClause(params (string condition, string paramName, object value, bool include)[]) method

protected static (string whereClause, List<(string name, object value)> parameters) BuildWhereClause(params (string condition, string paramName, object? value, bool include)[] conditions)

Builds a dynamic WHERE clause with the specified conditions.

CreateCommand(string, NpgsqlConnection) method

protected NpgsqlCommand CreateCommand(string sql, NpgsqlConnection connection)

Creates a command with timeout configured.

ExecuteAsync(string, string, Action<NpgsqlCommand>, CancellationToken, string) method

protected Task<int> ExecuteAsync(string tenantId, string sql, Action<NpgsqlCommand>? configureCommand, CancellationToken cancellationToken, string? callerName = null)

Executes a non-query command and returns the number of affected rows.

ExecuteInBatchAsync<TResult>(string, Func<NpgsqlConnection, NpgsqlTransaction, Task<TResult>>, CancellationToken, string) method

protected Task<TResult> ExecuteInBatchAsync<TResult>(string tenantId, Func<NpgsqlConnection, NpgsqlTransaction, Task<TResult>> body, CancellationToken cancellationToken, string? callerName = null)

Opens a single writer connection with the tenant session configured exactly once and begins one transaction, then hands both to body so a caller can run many statements (a batch) on the same connection/transaction instead of paying a connection open + tenant set_config + auto-commit round-trip per statement.

Remarks

This is an additive batched path; the per-statement helpers (RepositoryBase<TDataSource>.QueryAsync<T>(string, string, Action<NpgsqlCommand>, Func<NpgsqlDataReader, T>, CancellationToken, string), RepositoryBase<TDataSource>.ExecuteAsync(string, string, Action<NpgsqlCommand>, CancellationToken, string), …) are unchanged and remain the default for single-statement callers. The transaction is committed when body returns and rolled back if it throws, so the caller is responsible for per-item fault isolation (e.g. via savepoints) when a single bad row must not abort the whole batch.

ExecuteScalarAsync<T>(string, string, Action<NpgsqlCommand>, CancellationToken, string) method

protected Task<T?> ExecuteScalarAsync<T>(string tenantId, string sql, Action<NpgsqlCommand>? configureCommand, CancellationToken cancellationToken, string? callerName = null)

Executes a scalar query and returns the result.

GetNullableBoolean(NpgsqlDataReader, int) method

protected static bool? GetNullableBoolean(NpgsqlDataReader reader, int ordinal)

Gets a nullable bool from the reader.

GetNullableDateTimeOffset(NpgsqlDataReader, int) method

protected static DateTimeOffset? GetNullableDateTimeOffset(NpgsqlDataReader reader, int ordinal)

Gets a nullable DateTimeOffset from the reader.

GetNullableDecimal(NpgsqlDataReader, int) method

protected static decimal? GetNullableDecimal(NpgsqlDataReader reader, int ordinal)

Gets a nullable decimal from the reader.

GetNullableGuid(NpgsqlDataReader, int) method

protected static Guid? GetNullableGuid(NpgsqlDataReader reader, int ordinal)

Gets a nullable Guid from the reader.

GetNullableInt32(NpgsqlDataReader, int) method

protected static int? GetNullableInt32(NpgsqlDataReader reader, int ordinal)

Gets a nullable int from the reader.

GetNullableInt64(NpgsqlDataReader, int) method

protected static long? GetNullableInt64(NpgsqlDataReader reader, int ordinal)

Gets a nullable long from the reader.

GetNullableString(NpgsqlDataReader, int) method

protected static string? GetNullableString(NpgsqlDataReader reader, int ordinal)

Gets a nullable string from the reader.

QueryAsync<T>(string, string, Action<NpgsqlCommand>, Func<NpgsqlDataReader, T>, CancellationToken, string) method

protected Task<IReadOnlyList<T>> QueryAsync<T>(string tenantId, string sql, Action<NpgsqlCommand>? configureCommand, Func<NpgsqlDataReader, T> mapRow, CancellationToken cancellationToken, string? callerName = null)

Executes a query and returns all results as a list.

QuerySingleOrDefaultAsync<T>(string, string, Action<NpgsqlCommand>, Func<NpgsqlDataReader, T>, CancellationToken, string) method

protected Task<T?> QuerySingleOrDefaultAsync<T>(string tenantId, string sql, Action<NpgsqlCommand>? configureCommand, Func<NpgsqlDataReader, T> mapRow, CancellationToken cancellationToken, string? callerName = null) where T : class

Executes a query and returns a single result or null.

StellaOps.Infrastructure.Postgres.Testing namespace

TypeKindDescription
PostgresFixtureclassTest fixture for PostgreSQL integration tests.
PostgresFixtureFactoryclassFactory for creating PostgreSQL test fixtures.

PostgresFixture class

public sealed class PostgresFixture : IAsyncDisposable

Test fixture for PostgreSQL integration tests. Provides connection management and schema setup for tests.

Remarks

Use with Testcontainers or a local PostgreSQL instance. Each test class should create its own schema for isolation.

PostgresFixture(string, string, ILogger) constructor

public PostgresFixture(string connectionString, string schemaName, ILogger? logger = null)

Creates a new PostgreSQL test fixture.

Parameters

ConnectionString property

public string ConnectionString { get; }

Connection string for the test database.

SchemaName property

public string SchemaName { get; }

Schema name for test isolation.

CreateOptions() method

public PostgresOptions CreateOptions()

Creates PostgreSQL options for the test fixture.

DisposeAsync() method

public ValueTask DisposeAsync()

Cleans up the test schema.

ExecuteSqlAsync(string, CancellationToken) method

public Task ExecuteSqlAsync(string sql, CancellationToken cancellationToken = default)

Executes raw SQL for test setup.

InitializeAsync(CancellationToken) method

public Task InitializeAsync(CancellationToken cancellationToken = default)

Initializes the test schema.

RunMigrationsAsync(string, string, CancellationToken) method

public Task RunMigrationsAsync(string migrationsPath, string moduleName, CancellationToken cancellationToken = default)

Runs migrations for the test schema from filesystem path.

Parameters

RunMigrationsFromAssemblyAsync(Assembly, string, string, CancellationToken) method

public Task RunMigrationsFromAssemblyAsync(Assembly assembly, string moduleName, string? resourcePrefix = null, CancellationToken cancellationToken = default)

Runs migrations for the test schema from embedded resources in an assembly.

Parameters

RunMigrationsFromAssemblyAsync(Assembly, string, string, MigrationRunOptions, CancellationToken) method

public Task RunMigrationsFromAssemblyAsync(Assembly assembly, string moduleName, string? resourcePrefix, MigrationRunOptions? options, CancellationToken cancellationToken = default)

Runs migrations for the test schema from embedded resources in an assembly, with run options.

Parameters

Returns

A task that completes when the migrations have run.

Exceptions

RunMigrationsFromAssemblyAsync<TAssemblyMarker>(string, string, CancellationToken) method

public Task RunMigrationsFromAssemblyAsync<TAssemblyMarker>(string moduleName, string? resourcePrefix = null, CancellationToken cancellationToken = default)

Runs migrations for the test schema from embedded resources using a type from the assembly.

Type parameters

Parameters

TruncateAllTablesAsync(CancellationToken) method

public Task TruncateAllTablesAsync(CancellationToken cancellationToken = default)

Truncates all tables in the test schema for test isolation.

PostgresFixtureFactory class

public static class PostgresFixtureFactory

Factory for creating PostgreSQL test fixtures.

Create(string, string, ILogger) method

public static PostgresFixture Create(string connectionString, string testClassName, ILogger? logger = null)

Creates a fixture with a unique schema name based on the test class name.

Parameters

CreateRandom(string, ILogger) method

public static PostgresFixture CreateRandom(string connectionString, ILogger? logger = null)

Creates a fixture with a random schema name.