sqldb: guard native-SQL migration path against silent downgrades

[kpshukla]

Change Description

Fixes #10781.

sqldb.ApplyMigrations reads the migration version tracked in the
migration_tracker table and skips every configured migration whose
Version is <= currentVersion. There is no check for the reverse case:
if currentVersion is higher than anything the running binary's
migrationConfig knows about, every migration is silently skipped and
lnd proceeds to operate against a schema it doesn't understand.

This can happen if a user upgrades to a newer lnd release (which
advances migration_tracker forward), then accidentally relaunches an
older binary against the same database. The older binary has no way of
knowing it's behind, and unlike channeldb's kvdb meta store (which
already guards against this via ErrDBReversion), the native-SQL store
had no equivalent protection.

Note: sqldb/v2/migrations.go (an in-progress, not-yet-wired-in
package) already implements the same kind of guard for schema-level
downgrades (ErrMigrationDowngrade). This PR ports that idiom to the
currently-in-use sqldb package's migration_tracker-level version
check, which is what the linked issue is specifically about.

Fix

Added ErrDBDowngrade and a check in ApplyMigrations that compares
currentVersion against the highest version the binary's
migrationConfig contains (len(migrations), which is safe because the
function already validates that migration versions are numbered
contiguously from 1). If the database is ahead, ApplyMigrations now
fails loudly instead of silently skipping every migration.

Scope note

The issue also proposed a second, complementary change: bumping
channeldb's mandatory kvdb version with a no-op entry, so that even a
pre-fix binary refuses to start against a database a newer release
already touched (closing the gap for binaries that predate this PR).
I intentionally left that out of this PR — it affects every lnd node
on upgrade (not just native-SQL-store users) and "spends" a kvdb version
slot permanently, which felt like a call best left to a maintainer
rather than bundled unilaterally into a bug-fix PR. Happy to follow up
with that change if maintainers want it.

Testing

• go build ./... and go vet ./... clean in the sqldb module.
• Added TestApplyMigrationsRefusesDowngrade: migrates a fresh database
  forward using a 3-entry migration list (simulating a "newer" binary),
  then reopens the same database file/instance and calls
  ApplyAllMigrations with only a 2-entry list (simulating an "older"
  binary). Asserts ErrDBDowngrade is returned and that the tracked
  migration version is left untouched. Covered for both SQLite and
  Postgres backends.
• Ran the full existing migration suite (TestMigrations,
  TestCustomMigration, TestMigrationSucceedsAfterDirtyStateMigrationFailure19RC1,
  TestMigrationConfigConsistency) plus the new test under go test -race. All SQLite-backed and non-DB cases pass. Postgres-backed cases
  in this suite require a local Docker daemon, which wasn't available in
  my dev environment (docker info confirms), so those specific
  subtests couldn't be locally exercised — this is a pre-existing
  environment limitation, not something introduced by this change, and
  CI should cover the Postgres path.
• gofmt -l clean; all added lines respect the repo's 80-column
  convention.

Pull Request Checklist

Testing

• Your PR passes all CI checks.
• Tests covering the positive and negative (error paths) are included.
• Bug fixes contain tests triggering the bug to prevent regressions.

Code Style and Documentation

• The change is not insubstantial.
• The change obeys the Code Documentation and Commenting guidelines, and lines wrap at 80.
• Commits follow the Ideal Git Commit Structure.
• There is a change description in the release notes.

📝 Please see our Contribution Guidelines for further guidance.

[github-actions]

🔴 PR Severity: CRITICAL

gh pr view | 3 files | 161 lines changed

🔴 Critical (1 file)

• sqldb/migrations.go - Database migration file; per policy, changes under sqldb/* (and channeldb/migration*, wtdb/*) are always classified CRITICAL regardless of size, since they affect on-disk schema/state for all nodes.

🟢 Low (2 files)

• sqldb/migrations_test.go - Test-only file (*_test.go), excluded from severity-driving classification and from the file/line bump count.
• docs/release-notes/release-notes-0.22.0.md - Documentation/release notes.

Analysis

The only non-test, non-doc file touched is sqldb/migrations.go, which adds a new migration (31 lines). Database migrations are explicitly always CRITICAL per policy, since they run against every node's on-disk database and are difficult to safely revert if something goes wrong. The accompanying migrations_test.go changes (121 lines) are test-only and don't affect the severity determination, and the release-notes update is informational.

Total non-test/non-doc lines changed (40) and file count (1) are both well below the bump thresholds (>500 lines / >20 files), so no additional severity bump applies — the CRITICAL classification here comes solely from the migration-file rule, not from size.

Given this touches migration logic, recommend review from someone familiar with the sqldb migration framework and testing on both fresh and upgraded databases.

---

_{To override, add a severity-override-{critical,high,medium,low} label.}