Merge pull request #1048 from cardano-foundation/fix/tx-out-address-index

fix: tx out address index

Author: VladislavKudrin

packages/index-service/README.md

@@ -7,7 +7,7 @@ A Docker service for creating performance indexes on the cardano-db-sync Postgre
 The index service creates additional database indexes to improve query performance. These indexes are **optional** but **recommended for production** because:
 
 - `idx_ma_tx_mint_ident` is required for efficient asset polling (without it polls degrade from <1ms to 500ms+)
-- `idx_tx_out_address` significantly speeds up payment address queries
+- `idx_tx_out_address_texthash` is required for payment address / UTXO-by-address queries; without it these do a full sequential scan of `tx_out` (hundreds of millions of rows), which can saturate the connection pool under concurrent load
 - `idx_asset_fingerprint` speeds up asset fingerprint lookups
 
 Index creation is not enabled by default because:
@@ -68,7 +68,7 @@ docker compose ps index-service
 | Index | Table | Speeds up |
 |-------|-------|-----------|
 | `idx_ma_tx_mint_ident` | `ma_tx_mint.ident` | New asset polling (critical for background service) |
-| `idx_tx_out_address` | `tx_out.address` | Payment address queries |
+| `idx_tx_out_address_texthash` | `tx_out.address` | Payment address / UTXO-by-address queries (prevents full-table scans) |
 | `idx_asset_fingerprint` | `Asset.fingerprint` | Asset fingerprint lookups |
 
 ## Operations
@@ -117,6 +117,7 @@ docker compose exec postgres psql -U $(cat placeholder-secrets/postgres_user) \
 
 # Drop all custom indexes
 DROP INDEX CONCURRENTLY IF EXISTS idx_ma_tx_mint_ident;
+DROP INDEX CONCURRENTLY IF EXISTS idx_tx_out_address_texthash;
 DROP INDEX CONCURRENTLY IF EXISTS idx_tx_out_address;
 DROP INDEX CONCURRENTLY IF EXISTS idx_asset_fingerprint;
 ```

packages/index-service/indexes.sql

@@ -17,9 +17,10 @@
 \echo '======================================================================'
 \echo ''
 
-\echo '[1/3] Creating index on tx_out.address (hash)...'
-CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_tx_out_address ON tx_out USING hash (address);
-\echo '✓ Completed: idx_tx_out_address'
+\echo '[1/3] Creating index on tx_out.address (hash on text expression)...'
+DROP INDEX CONCURRENTLY IF EXISTS idx_tx_out_address;
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_tx_out_address_texthash ON tx_out USING hash ((address::text));
+\echo '✓ Completed: idx_tx_out_address_texthash'
 \echo ''
 
 \echo '[2/3] Creating index on asset.fingerprint...'
@@ -48,7 +49,7 @@ CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_ma_tx_mint_ident ON ma_tx_mint(ident
 \echo '  docker compose exec postgres psql -U <user> -d <db> -c "\\di idx_*"'
 \echo ''
 \echo 'Indexes created:'
-\echo '  idx_tx_out_address      - speeds up payment address queries'
+\echo '  idx_tx_out_address_texthash - speeds up payment address / UTXO-by-address queries'
 \echo '  idx_asset_fingerprint   - speeds up asset fingerprint lookups'
 \echo '  idx_ma_tx_mint_ident    - speeds up new asset polling'
 \echo ''