payments/migration1: add migration test suite and helpers

Add test helpers plus sql_migration_test coverage for KV→SQL migration.
Basic migration, sequence ordering, data integrity, and feature-specific cases
(MPP/AMP, custom records, blinded routes, metadata, failure messages). Also
cover duplicate payment migration to payment_duplicates, including missing
attempt info to ensure terminal failure is recorded.

This gives broad regression coverage for the migration path and its edge-cases.

payments/db/migration1/test_harness.go

@@ -0,0 +1,26 @@
+package migration1
+
+import (
+	"testing"
+
+	"github.com/lightningnetwork/lnd/lntypes"
+)
+
+// TestHarness provides implementation-specific test utilities for the payments
+// database. Different database backends (KV, SQL) have different internal
+// structures and indexing mechanisms, so this interface allows tests to verify
+// implementation-specific behavior without coupling the test logic to a
+// particular backend.
+type TestHarness interface {
+	// AssertPaymentIndex checks that a payment is correctly indexed.
+	// For KV: verifies the payment index bucket entry exists and points
+	// to the correct payment hash.
+	// For SQL: no-op (SQL doesn't use a separate index bucket).
+	AssertPaymentIndex(t *testing.T, expectedHash lntypes.Hash)
+
+	// AssertNoIndex checks that an index for a sequence number doesn't
+	// exist.
+	// For KV: verifies the index bucket entry is deleted.
+	// For SQL: no-op.
+	AssertNoIndex(t *testing.T, seqNr uint64)
+}

payments/db/migration1/test_postgres.go

@@ -0,0 +1,94 @@
+//go:build test_db_postgres && !test_db_sqlite
+
+package migration1
+
+import (
+	"testing"
+
+	"github.com/lightningnetwork/lnd/lntypes"
+	"github.com/lightningnetwork/lnd/payments/db/migration1/sqlc"
+	"github.com/lightningnetwork/lnd/sqldb"
+	"github.com/stretchr/testify/require"
+)
+
+// NewTestDB is a helper function that creates a SQLStore backed by a SQL
+// database for testing.
+func NewTestDB(t testing.TB, opts ...OptionModifier) (DB, TestHarness) {
+	db := NewTestDBWithFixture(t, nil, opts...)
+	return db, &noopTestHarness{}
+}
+
+// NewTestDBFixture creates a new sqldb.TestPgFixture for testing purposes.
+func NewTestDBFixture(t *testing.T) *sqldb.TestPgFixture {
+	pgFixture := sqldb.NewTestPgFixture(
+		t, sqldb.DefaultPostgresFixtureLifetime,
+	)
+	t.Cleanup(func() {
+		pgFixture.TearDown(t)
+	})
+	return pgFixture
+}
+
+// NewTestDBWithFixture is a helper function that creates a SQLStore backed by a
+// SQL database for testing.
+func NewTestDBWithFixture(t testing.TB,
+	pgFixture *sqldb.TestPgFixture, opts ...OptionModifier) DB {
+
+	var querier BatchedSQLQueries
+	if pgFixture == nil {
+		querier = newBatchQuerier(t)
+	} else {
+		querier = newBatchQuerierWithFixture(t, pgFixture)
+	}
+
+	store, err := NewSQLStore(
+		&SQLStoreConfig{
+			QueryCfg: sqldb.DefaultPostgresConfig(),
+		}, querier, opts...,
+	)
+	require.NoError(t, err)
+
+	return store
+}
+
+// newBatchQuerier creates a new BatchedSQLQueries instance for testing
+// using a PostgreSQL database fixture.
+func newBatchQuerier(t testing.TB) BatchedSQLQueries {
+	pgFixture := sqldb.NewTestPgFixture(
+		t, sqldb.DefaultPostgresFixtureLifetime,
+	)
+	t.Cleanup(func() {
+		pgFixture.TearDown(t)
+	})
+
+	return newBatchQuerierWithFixture(t, pgFixture)
+}
+
+// newBatchQuerierWithFixture creates a new BatchedSQLQueries instance for
+// testing using a PostgreSQL database fixture.
+func newBatchQuerierWithFixture(t testing.TB,
+	pgFixture *sqldb.TestPgFixture) BatchedSQLQueries {
+
+	rawDB := sqldb.NewTestPostgresDB(t, pgFixture).BaseDB.DB
+
+	return &testBatchedSQLQueries{
+		db:      rawDB,
+		Queries: sqlc.New(rawDB),
+	}
+}
+
+// noopTestHarness is the SQL test harness implementation. Since SQL doesn't
+// use a separate payment index bucket like KV, these assertions are no-ops.
+type noopTestHarness struct{}
+
+// AssertPaymentIndex is a no-op for SQL implementations.
+func (h *noopTestHarness) AssertPaymentIndex(t *testing.T,
+	expectedHash lntypes.Hash) {
+
+	// No-op: SQL doesn't use a separate index bucket.
+}
+
+// AssertNoIndex is a no-op for SQL implementations.
+func (h *noopTestHarness) AssertNoIndex(t *testing.T, seqNr uint64) {
+	// No-op: SQL doesn't use a separate index bucket.
+}

payments/db/migration1/test_sql.go

@@ -0,0 +1,58 @@
+//go:build test_db_postgres || test_db_sqlite
+
+package migration1
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+
+	"github.com/lightningnetwork/lnd/payments/db/migration1/sqlc"
+	"github.com/lightningnetwork/lnd/sqldb"
+	"github.com/stretchr/testify/require"
+)
+
+// setupTestSQLDB creates a SQLStore-backed test database.
+func setupTestSQLDB(t testing.TB, opts ...OptionModifier) *SQLStore {
+	t.Helper()
+
+	db, _ := NewTestDB(t, opts...)
+	sqlStore, ok := db.(*SQLStore)
+	require.True(t, ok)
+
+	return sqlStore
+}
+
+// testBatchedSQLQueries is a simple implementation of BatchedSQLQueries for
+// testing.
+type testBatchedSQLQueries struct {
+	db *sql.DB
+	*sqlc.Queries
+}
+
+// ExecTx implements the transaction execution logic.
+func (t *testBatchedSQLQueries) ExecTx(ctx context.Context,
+	txOpts sqldb.TxOptions, txBody func(SQLQueries) error,
+	reset func()) error {
+
+	sqlOptions := sql.TxOptions{
+		Isolation: sql.LevelSerializable,
+		ReadOnly:  txOpts.ReadOnly(),
+	}
+
+	tx, err := t.db.BeginTx(ctx, &sqlOptions)
+	if err != nil {
+		return err
+	}
+
+	reset()
+	queries := sqlc.New(tx)
+
+	if err := txBody(queries); err != nil {
+		_ = tx.Rollback()
+
+		return err
+	}
+
+	return tx.Commit()
+}

payments/db/migration1/test_sqlite.go

@@ -0,0 +1,73 @@
+//go:build !test_db_postgres && test_db_sqlite
+
+package migration1
+
+import (
+	"testing"
+
+	"github.com/lightningnetwork/lnd/lntypes"
+	"github.com/lightningnetwork/lnd/payments/db/migration1/sqlc"
+	"github.com/lightningnetwork/lnd/sqldb"
+	"github.com/stretchr/testify/require"
+)
+
+// NewTestDB is a helper function that creates a SQLStore backed by a SQL
+// database for testing.
+func NewTestDB(t testing.TB, opts ...OptionModifier) (DB, TestHarness) {
+	db := NewTestDBWithFixture(t, nil, opts...)
+	return db, &noopTestHarness{}
+}
+
+// NewTestDBFixture is a no-op for the sqlite build.
+func NewTestDBFixture(_ *testing.T) *sqldb.TestPgFixture {
+	return nil
+}
+
+// NewTestDBWithFixture is a helper function that creates a SQLStore backed by a
+// SQL database for testing.
+func NewTestDBWithFixture(t testing.TB, _ *sqldb.TestPgFixture,
+	opts ...OptionModifier) DB {
+
+	store, err := NewSQLStore(
+		&SQLStoreConfig{
+			QueryCfg: sqldb.DefaultSQLiteConfig(),
+		}, newBatchQuerier(t), opts...,
+	)
+	require.NoError(t, err)
+	return store
+}
+
+// newBatchQuerier creates a new BatchedSQLQueries instance for testing
+// using a SQLite database.
+func newBatchQuerier(t testing.TB) BatchedSQLQueries {
+	return newBatchQuerierWithFixture(t, nil)
+}
+
+// newBatchQuerierWithFixture creates a new BatchedSQLQueries instance for
+// testing using a SQLite database.
+func newBatchQuerierWithFixture(t testing.TB,
+	_ *sqldb.TestPgFixture) BatchedSQLQueries {
+
+	rawDB := sqldb.NewTestSqliteDB(t).BaseDB.DB
+
+	return &testBatchedSQLQueries{
+		db:      rawDB,
+		Queries: sqlc.New(rawDB),
+	}
+}
+
+// noopTestHarness is the SQL test harness implementation. Since SQL doesn't
+// use a separate payment index bucket like KV, these assertions are no-ops.
+type noopTestHarness struct{}
+
+// AssertPaymentIndex is a no-op for SQL implementations.
+func (h *noopTestHarness) AssertPaymentIndex(t *testing.T,
+	expectedHash lntypes.Hash) {
+
+	// No-op: SQL doesn't use a separate index bucket.
+}
+
+// AssertNoIndex is a no-op for SQL implementations.
+func (h *noopTestHarness) AssertNoIndex(t *testing.T, seqNr uint64) {
+	// No-op: SQL doesn't use a separate index bucket.
+}