Skip to content

Comments

[sql-64] firewalldb: add database benchmarking for firewalldb package#1232

Closed
ViktorT-11 wants to merge 7 commits intolightninglabs:trigger-kvdb-to-sql-migfrom
ViktorT-11:2026-02-add-firewalldb-benchmarking
Closed

[sql-64] firewalldb: add database benchmarking for firewalldb package#1232
ViktorT-11 wants to merge 7 commits intolightninglabs:trigger-kvdb-to-sql-migfrom
ViktorT-11:2026-02-add-firewalldb-benchmarking

Conversation

@ViktorT-11
Copy link
Contributor

Based on #1231

Implements the last part of step 7. of "Phase 3" in #917.

This PR implements benchmarking tests for different database backends in the firewalldb package.

@ViktorT-11 ViktorT-11 added the no-changelog This PR is does not require a release notes entry label Feb 18, 2026
@ViktorT-11 ViktorT-11 changed the base branch from sql-migration-base to trigger-kvdb-to-sql-mig February 18, 2026 11:31
@gemini-code-assist
Copy link

Summary of Changes

Hello @ViktorT-11, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the project's database infrastructure by introducing robust benchmarking capabilities for the firewalldb package, allowing for performance comparisons across different database backends. It also includes a crucial upgrade of the Go language version and a substantial refactoring of the SQL store implementations to align with the new lnd/sqldb/v2 module, streamlining database operations and migration processes. These changes lay the groundwork for more efficient and maintainable data persistence layers.

Highlights

  • Database Benchmarking: Introduced comprehensive benchmarking tests for the firewalldb package, covering various operations across KVDB (bbolt), SQLite, and PostgreSQL backends. This fulfills the last part of 'Phase 3' for issue db: use native SQL #917.
  • Go Version Update: Upgraded the Go language version from 1.24.9 to 1.24.11 across the project, reflected in Dockerfile, Makefile, and go.mod files.
  • SQL Store Refactoring & Migration Infrastructure: Refactored SQL store implementations in accounts, session, and firewalldb packages to leverage the new lnd/sqldb/v2 module for improved database interaction and transaction management. This includes introducing a dedicated db/migrationstreams package to handle migration logic and programmatic callbacks, especially for KVDB to SQL migrations in development environments.
  • Linter Configuration: Added a linter exclusion in .golangci.yml for the newly introduced db/sqlcmig6 package to ignore line length (lll) violations, as this package contains copied generated code.
  • Documentation: Added a new documentation file (docs/benchmark_db_backends.md) detailing how to run and compare database benchmarks for different backends.
  • SQL Query Simplification: Removed the UpdateAccountAliasForTests query from db/sqlc as it was intended for testing and is no longer needed with the new migration strategy.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog
  • .golangci.yml
    • Added linter exclusion for the db/sqlcmig6 package to ignore line length violations.
  • Dockerfile
    • Updated Go version to 1.24.11.
  • Makefile
    • Updated Go version to 1.24.11.
    • Added a new unit-bench target for running benchmark tests.
  • accounts/benchmark_test.go
    • Added new benchmark tests for various account store operations (e.g., NewAccount, UpdateBalance, AddInvoice, CreditAccount, DebitAccount, UpsertPayment, DeletePayment, RemoveAccount, GetAccount, ListAccounts, StoreLastIndexes, LastIndexes) across different database backends.
  • accounts/service.go
    • Updated comments from 'db' to 'DB'.
  • accounts/service_test.go
    • Updated comments from 'db' to 'DB'.
  • accounts/sql_migration.go
    • Updated imports to use db/sqlcmig6 and sqldb/v2.
    • Adjusted function signatures for MigrateAccountStoreToSQL, migrateAccountsToSQL, migrateSingleAccountToSQL, and migrateAccountsIndicesToSQL to use *sqlcmig6.Queries.
    • Updated calls to getAndMarshalMig6Account and sqlcmig6.InsertAccountParams, sqlcmig6.AddAccountInvoiceParams, sqlcmig6.UpsertAccountPaymentParams, and sqlcmig6.SetAccountIndexParams.
  • accounts/sql_migration_test.go
    • Updated imports to use db/sqlcmig6 and sqldb/v2.
    • Modified makeSQLDB function to return *sqlcmig6.TxExecutor[*sqlcmig6.Queries].
    • Adjusted ExecTx calls to pass sqldb.NoOpReset.
  • accounts/store_kvdb.go
    • Renamed the db field to DB in the BoltStore struct.
    • Updated all internal references to the DB field.
    • Changed DBFilename constant from 'accounts.db' to 'accounts.DB'.
  • accounts/store_sql.go
    • Updated imports to use sqldb/v2.
    • Modified SQLQueries interface to embed sqldb.BaseQuerier.
    • Removed UpdateAccountAliasForTests from the SQLQueries interface.
    • Updated BatchedSQLQueries interface to use sqldb.BatchedTx from lnd/sqldb/v2.
    • Refactored NewSQLStore to accept *sqlc.Queries and introduced SQLQueriesExecutor for transaction management.
    • Added sqldb.NoOpReset to all ExecTx calls.
  • accounts/test_kvdb.go
    • Updated store.db.Close() to store.DB.Close().
  • accounts/test_sql.go
    • Modified createStore function to accept *sqlc.Queries and use sqlc.NewForType for query initialization.
  • accounts/test_sqlite.go
    • Updated imports to use sqldb/v2.
    • Adjusted NewTestDB and NewTestDBFromPath functions to use sqldb.NewTestSqliteDB and sqldb.NewTestSqliteDBFromPath with db.MakeTestMigrationStreams().
  • autopilotserverrpc/go.mod
    • Updated Go version to 1.24.11.
  • config_dev.go
    • Updated imports to include context, db/migrationstreams, db/sqlc, lnrpc, and sqldb/v2.
    • Modified NewStores function signature to accept context.Context and lnrpc.LightningClient.
    • Refactored SQLite and PostgreSQL store initialization to use sqldb.NewSqliteStore and sqldb.NewPostgresStore with sqldb.ApplyAllMigrations and migrationstreams.MakeMigrationStreams.
    • Updated NewSQLStore calls for accounts, session, and firewalldb to pass *sqlc.Queries.
  • config_prod.go
    • Updated imports to include context and lnrpc.
    • Modified NewStores function signature to accept context.Context and lnrpc.LightningClient.
  • db/interfaces.go
    • Removed generic TransactionExecutor, BatchedTx, BaseDB, and related types, as these functionalities are now provided by lnd/sqldb/v2.
  • db/migrations.go
    • Simplified the file by removing migration-related helper functions and types that are now handled by lnd/sqldb/v2 and the new db/migrationstreams package.
    • Added LatestDevMigrationVersion constant.
    • Introduced MakeTestMigrationStreams function for creating migration streams in test environments.
  • db/migrationstreams/log.go
    • Added new file to define logging for the migrationstreams package.
  • db/migrationstreams/post_migration_callbacks_dev.go
    • Added new file (with dev build tag) to define programmatic post-migration callbacks, specifically for KVDB to SQL migration in development environments.
  • db/migrationstreams/sql_migrations.go
    • Added new file (non-dev build tag) to define MakeMigrationStreams for production environments.
  • db/migrationstreams/sql_migrations_dev.go
    • Added new file (with dev build tag) to define MakeMigrationStreams for development environments, including the KVDBtoSQLMigVersion and programmatic migration callbacks.
  • db/postgres.go
    • Simplified the file by removing PostgresStore struct and related migration logic, now relying on lnd/sqldb/v2.
    • Updated NewTestPostgresDB to use sqldb.NewTestPostgresDB with MakeTestMigrationStreams().
  • db/schemas.go
    • Modified go:embed directive to include sqlc/migrations_dev directory.
  • db/sqlc/accounts.sql.go
    • Removed the updateAccountAliasForTests SQL query and its corresponding UpdateAccountAliasForTestsParams struct and UpdateAccountAliasForTests function.
  • db/sqlc/db_custom.go
    • Refactored Backend and NewForType functions to use sqldb.BackendType from lnd/sqldb/v2.
    • Removed NewSqlite and NewPostgres functions.
  • db/sqlc/migrations_dev/000001_code_migration_kvdb_to_sql.down.sql
    • Added new empty SQL migration file for dev environment.
  • db/sqlc/migrations_dev/000001_code_migration_kvdb_to_sql.up.sql
    • Added new empty SQL migration file for dev environment.
  • db/sqlc/querier.go
    • Removed UpdateAccountAliasForTests from the Querier interface.
  • db/sqlc/queries/accounts.sql
    • Removed the UpdateAccountAliasForTests SQL query.
  • db/sqlcmig6/accounts.sql.go
    • Added new file, appearing to be a copy of db/sqlc/accounts.sql.go before recent changes, used for migration purposes.
  • db/sqlcmig6/actions.sql.go
    • Added new file, appearing to be a copy of db/sqlc/actions.sql.go, used for migration purposes.
  • db/sqlcmig6/actions_custom.go
    • Added new file, appearing to be a copy of db/sqlc/actions_custom.go, used for migration purposes.
  • db/sqlcmig6/db.go
    • Added new file defining DBTX, Queries, and TxExecutor types for the sqlcmig6 package.
  • db/sqlcmig6/db_custom.go
    • Added new file defining wrappedTX, Backend, NewForType, and CustomQueries for the sqlcmig6 package.
  • db/sqlcmig6/kvstores.sql.go
    • Added new file, appearing to be a copy of db/sqlc/kvstores.sql.go, used for migration purposes.
  • db/sqlcmig6/models.go
    • Added new file, appearing to be a copy of db/sqlc/models.go, used for migration purposes.
  • db/sqlcmig6/privacy_paris.sql.go
    • Added new file, appearing to be a copy of db/sqlc/privacy_paris.sql.go, used for migration purposes.
  • db/sqlcmig6/querier.go
    • Added new file, appearing to be a copy of db/sqlc/querier.go, used for migration purposes.
  • db/sqlcmig6/sessions.sql.go
    • Added new file, appearing to be a copy of db/sqlc/sessions.sql.go, used for migration purposes.
  • dev.Dockerfile
    • Updated Go version to 1.24.11.
  • docs/benchmark_db_backends.md
    • Added new documentation file explaining how to run database benchmarks for different backends.
  • firewalldb/actions_sql.go
    • Updated imports to use sqldb/v2.
    • Added sqldb.NoOpReset to ExecTx calls for transaction execution.
  • firewalldb/benchmark_test.go
    • Added new benchmark tests for various firewall DB operations (e.g., AddAction, SetActionState, ListActions, KVStoreSet, KVStoreGet, KVStoreDel, DeleteTempKVStores, PrivacyNewPair, PrivacyRealToPseudo, PrivacyPseudoToReal, PrivacyFetchAllPairs) across different database backends.
  • firewalldb/kvstores_sql.go
    • Updated imports to use sqldb/v2.
    • Added ListAllKVStoresRecords to SQLKVStoreQueries interface.
    • Added sqldb.NoOpReset to ExecTx calls for transaction execution.
  • firewalldb/sql_migration.go
    • Updated imports to use db/sqlcmig6, sqldb/v2, macaroon-bakery.v2, and macaroon.v2.
    • Adjusted function signatures for MigrateFirewallDBToSQL, migrateKVStoresDBToSQL, collectAllPairs, collectRulePairs, insertPair, getSQLValue, migratePrivacyMapperDBToSQL, collectPrivacyPairs, insertPrivacyPairs, insertGroupPairs, validatePrivacyPairsMigration, validateGroupPairsMigration, migrateActionsToSQL, migrateActionToSQL, validateMigratedAction, paramsFromBothSessionAndAccounts, paramsFromSession, paramsFromAccounts, paramsFromAction, getMatchingSessionForAction, getMatchingAccountForAction, marshalDBAction, mapAccounts, and mapSessions to use *sqlcmig6.Queries and sqlcmig6 types.
    • Removed sessionDB and accountDB parameters from MigrateFirewallDBToSQL and migrateActionsToSQL as these are now accessed directly through the sqlcmig6.Queries object.
  • firewalldb/sql_migration_test.go
    • Updated imports to use db/sqlcmig6 and sqldb/v2.
    • Modified makeSQLDB function to return *sqlcmig6.TxExecutor[*sqlcmig6.Queries].
    • Adjusted assertKvStoreMigrationResults and assertActionsMigrationResults signatures to accept *sqlcmig6.Queries.
    • Updated ExecTx calls to pass sqldb.NoOpReset.
    • Modified createPrivacyPairs, randomPrivacyPairs, actionWithMultipleAccounts, actionWithSessionAndAccount, actionWithSessionWithLinkedAccountAndAccount, randomActions, testAccountWithExpiry, and testSessionWithAccount to use sqlcmig6.NewForType and sqlcmig6 types for account and session queries.
  • firewalldb/sql_store.go
    • Updated imports to include db/sqlc and sqldb/v2.
    • Modified SQLQueries interface to embed sqldb.BaseQuerier.
    • Updated BatchedSQLQueries interface to use sqldb.BatchedTx from lnd/sqldb/v2.
    • Refactored NewSQLDB to accept *sqlc.Queries and introduced SQLQueriesExecutor for transaction management.
    • Added sqldb.NoOpReset to all ExecTx calls.
  • firewalldb/test_sql.go
    • Updated imports to include db/sqlc and sqldb/v2.
    • Modified createStore function to accept *sqlc.Queries and use sqlc.NewForType for query initialization.
  • firewalldb/test_sqlite.go
    • Updated imports to use sqldb/v2.
    • Adjusted NewTestDB and NewTestDBFromPath functions to use sqldb.NewTestSqliteDB and sqldb.NewTestSqliteDBFromPath with db.MakeTestMigrationStreams().
  • go.mod
    • Updated Go version to 1.24.11.
    • Updated golang-migrate/migrate/v4 to v4.19.0.
    • Updated lightning-node-connect/gbn and lightning-node-connect/mailbox modules.
    • Updated lightninglabs/taproot-assets and lightninglabs/taproot-assets/taprpc modules.
    • Updated lightningnetwork/lnd to v0.20.0-beta.rc4.
    • Added github.com/lightningnetwork/lnd/sqldb/v2 module.
    • Updated golang.org/x/exp and modernc.org/sqlite versions.
    • Added a replace directive for github.com/lightningnetwork/lnd/sqldb/v2.
  • go.sum
    • Updated checksums for various dependencies due to version bumps and new modules.
  • itest/litd_node.go
    • Added taproot-assets.allow-public-uni-proof-courier flag to default litd arguments.
  • litrpc/Dockerfile
    • Updated Go version to 1.24.11.
  • litrpc/go.mod
    • Updated Go version to 1.24.11.
  • log.go
    • Added sqldb.UseLogger and migrationstreams.UseLogger to SetupLoggers.
  • make/builder.Dockerfile
    • Updated Go version to 1.24.11.
  • make/testing_flags.mk
    • Added UNIT_BENCH target definition for running benchmark tests.
  • perms/go.mod
    • Updated Go version to 1.24.11.
  • scripts/gen_sqlc_docker.sh
    • Modified script to include migrations_dev directory when restoring and applying SQLite bigint patches.
  • session/benchmark_test.go
    • Added new benchmark tests for various session store operations (e.g., NewSession, GetSession, GetSessionByLocalPub, ListSessions, ListSessionsByType, ListSessionsByState, ShiftState, UpdateRemoteKey, DeleteReservedSession, DeleteReservedSessions, GetGroupID, GetSessionIDs) across different database backends.
  • session/sql_migration.go
    • Updated imports to include btcec/v2, mailbox, db/sqlcmig6, sqldb/v2, macaroon-bakery.v2, and macaroon.v2.
    • Adjusted function signatures for MigrateSessionStoreToSQL and migrateSingleSessionToSQL to use *sqlcmig6.Queries.
    • Introduced getAndUnmarshalSession, unmarshalMig6Session, unmarshalMig6MacPerms, unmarshalMig6MacCaveats, unmarshalMig6FeatureConfigs, and unmarshalMig6PrivacyFlags functions for handling sqlcmig6 types during migration.
    • Updated calls to sqlcmig6.InsertSessionParams, sqlcmig6.SetSessionRevokedAtParams, sqlcmig6.SetSessionGroupIDParams, sqlcmig6.InsertSessionMacaroonPermissionParams, sqlcmig6.InsertSessionMacaroonCaveatParams, sqlcmig6.InsertSessionFeatureConfigParams, and sqlcmig6.InsertSessionPrivacyFlagParams.
  • session/sql_migration_test.go
    • Updated imports to use db/sqlcmig6 and sqldb/v2.
    • Modified makeSQLDB function to return *sqlcmig6.TxExecutor[*sqlcmig6.Queries].
    • Adjusted ExecTx calls to pass sqldb.NoOpReset.
  • session/sql_store.go
    • Updated imports to include db/sqlc and sqldb/v2.
    • Modified SQLQueries interface to embed sqldb.BaseQuerier.
    • Updated BatchedSQLQueries interface to use sqldb.BatchedTx from lnd/sqldb/v2.
    • Refactored NewSQLStore to accept *sqlc.Queries and introduced SQLQueriesExecutor for transaction management.
    • Added sqldb.NoOpReset to all ExecTx calls.
  • session/test_sql.go
    • Updated imports to include db/sqlc and sqldb/v2.
    • Modified createStore function to accept *sqlc.Queries and use sqlc.NewForType for query initialization.
  • session/test_sqlite.go
    • Updated imports to use sqldb/v2.
    • Adjusted NewTestDB and NewTestDBFromPath functions to use sqldb.NewTestSqliteDB and sqldb.NewTestSqliteDBFromPath with db.MakeTestMigrationStreams().
  • terminal.go
    • Modified the call to NewStores to pass context.Context and g.basicClient.
  • tools/Dockerfile
    • Updated Go version to 1.24.11.
  • tools/go.mod
    • Updated Go version to 1.24.11.
  • tools/linters/go.mod
    • Updated Go version to 1.24.11.
Ignored Files
  • Ignored by pattern: .github/workflows/** (1)
    • .github/workflows/main.yml
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds a comprehensive benchmarking suite for the accounts, session, and firewalldb packages, comparing kvdb-bbolt, sqlite, and postgres backends. The changes include new unit-bench Makefile targets, benchmark test files for each package, and documentation on how to run them. The benchmark implementations are well-structured and correctly isolate the code under test. I have a couple of suggestions to improve the clarity of resource cleanup in the firewalldb benchmarks and to make the documentation more generic and easier to use.

Comment on lines +48 to +53
grep '^BenchmarkAccountStore/kvdb-bbolt/' /tmp/run.txt | \
sed 's#BenchmarkAccountStore/kvdb-bbolt/#BenchmarkAccountStore/#' \
> /tmp/kvdb.norm.txt
grep '^BenchmarkAccountStore/native-sqlite/' /tmp/run.txt | \
sed 's#BenchmarkAccountStore/native-sqlite/#BenchmarkAccountStore/#' \
> /tmp/sqlite.norm.txt

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The example commands for benchstat are specific to the accounts package (BenchmarkAccountStore). To make this documentation more reusable for other packages like session and firewalldb, consider using a variable for the benchmark name prefix.

For example:

# Set BENCH_PREFIX based on the package being benchmarked.
# For pkg=accounts: BENCH_PREFIX='BenchmarkAccountStore'
# For pkg=session: BENCH_PREFIX='BenchmarkSessionStore'
# For pkg=firewalldb: BENCH_PREFIX='BenchmarkFirewallDB'

grep "^${BENCH_PREFIX}/kvdb-bbolt/" /tmp/run.txt | \
  sed "s#^${BENCH_PREFIX}/kvdb-bbolt/#${BENCH_PREFIX}/#" \
  > /tmp/kvdb.norm.txt
grep "^${BENCH_PREFIX}/native-sqlite/" /tmp/run.txt | \
  sed "s#^${BENCH_PREFIX}/native-sqlite/#${BENCH_PREFIX}/#" \
  > /tmp/sqlite.norm.txt

This would make it clearer how to adapt the commands for different benchmark suites.

Comment on lines +168 to +170
require.NoError(
b, firewallStore.Close(),
)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For clarity and robustness, it's better to close the sqlStore that owns the database connection, rather than one of the stores that uses it (firewallStore). This makes it explicit that the shared resource used by both firewallStore and sessStore is being cleaned up.

Suggested change
require.NoError(
b, firewallStore.Close(),
)
require.NoError(
b, sqlStore.Close(),
)

Comment on lines +209 to +211
require.NoError(
b, firewallStore.Close(),
)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Similar to the sqlite backend, it's clearer to close the sqlStore that owns the database connection, rather than one of the stores that uses it (firewallStore). This makes it explicit that the shared resource is being cleaned up.

Suggested change
require.NoError(
b, firewallStore.Close(),
)
require.NoError(
b, sqlStore.Close(),
)

@ViktorT-11 ViktorT-11 deleted the branch lightninglabs:trigger-kvdb-to-sql-mig February 19, 2026 11:11
@ViktorT-11 ViktorT-11 closed this Feb 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-changelog This PR is does not require a release notes entry

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant