Debugging IA de Base de Données sur Databricks avec PostgreSQL: Guide Complet

1. Vue d’ensemble

Quand une application se connecte à PostgreSQL sur Databricks (via Lakebase ou Lakehouse Federation) et rencontre une erreur, analyser manuellement la stack trace, les logs HikariCP et EXPLAIN ANALYZE demande beaucoup de temps. Databricks intègre un Assistant IA capable de lire les logs, les requêtes SQL et la configuration du pool de connexions pour suggérer la cause et les solutions directement.

Cet article explique comment le debugging IA de base de données fonctionne chez Databricks, puis passe en revue trois scénarios d’erreurs PostgreSQL courants (pool épuisé, requêtes N+1, permissions manquantes) avec du code Spring Boot pour que vous puissiez reproduire et vérifier par vous-même les suggestions que l’IA fournit. Après la lecture, vous saurez comment préparer les logs et les requêtes pour que l’IA (ou vous-même) diagnostique plus vite et plus précisément.

2. Databricks Postgres (Lakebase) qu’est-ce que c’est

Lakebase est un PostgreSQL managé exécuté directement dans le workspace Databricks, conçu pour les charges de travail OLTP (transactionnelles) à côté de Delta Lake pour OLAP. Une application backend se connecte à Lakebase comme à n’importe quel PostgreSQL ordinaire — via JDBC, avec l’hôte/port/base de données fournis par Databricks.

2.1. Connexion depuis Spring Boot

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.4</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

spring.datasource.url=jdbc:postgresql://<workspace>.lakebase.databricks.com:5432/orders_db
spring.datasource.username=app_user
spring.datasource.password=${DB_PASSWORD}
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.connection-timeout=3000

Ceci est la configuration minimale : maximum-pool-size et connection-timeout sont deux paramètres qui reviendront constamment dans les cas de debugging de la section 4, car l’IA commence généralement son analyse à partir de là.

3. Comment le debugging IA de base de données fonctionne dans Databricks

3.1. Sources de données que l’IA lit

L’Assistant Databricks ne « devine » pas au hasard — il lit trois sources :

• Stack trace / logs d’exception provenant du job ou du notebook.
• Query plan (EXPLAIN ANALYZE) quand vous posez une question sur une requête lente.
• Schéma et métadonnées (tables, index, contraintes) pour vérifier la validité du SQL.

En d’autres termes, l’IA ne fonctionne bien que si vos logs sont suffisamment détaillés. Une exception qui n’affiche que "Connection is not available" donnera des suggestions beaucoup plus vagues qu’un log incluant la taille actuelle du pool et le nombre de connexions actives.

3.2. Flux de debugging typique

1. Vous collez la stack trace ou la requête SQL défaillante dans l'Assistant Databricks.
2. L'IA identifie le type d'erreur : pool de connexions, syntaxe, permission, verrou, timeout...
3. L'IA croise avec le schéma/les métadonnées présentes dans le workspace.
4. L'IA propose un correctif : changer la config, corriger le SQL, ajouter un index, exécuter GRANT...
5. Vous appliquez le correctif, relancez, l'IA confirme que les logs sont propres.

La section suivante simule exactement ce flux avec trois cas concrets.

4. Pratique : Reproduire les erreurs et lire les suggestions de debugging

4.1. Préparation des données

CREATE TABLE customers (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL
);

CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    customer_id BIGINT REFERENCES customers(id),
    total NUMERIC(12,2) NOT NULL,
    created_at TIMESTAMP DEFAULT now()
);

Et l’entité correspondante :

@Entity
@Table(name = "orders")
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id")
    private Customer customer;

    private BigDecimal total;
}

4.2. Cas 1 — Pool de connexions épuisé

Ce service présente une fuite de connexions car il crée manuellement un EntityManager sans le fermer :

@Service
public class OrderReportService {

    @PersistenceContext
    private EntityManager entityManager;

    public List<Order> findAllOrdersUnsafe() {
        EntityManager em = entityManager.getEntityManagerFactory()
                .createEntityManager(); // jamais fermé
        return em.createQuery("SELECT o FROM Order o", Order.class)
                .getResultList();
    }
}

Appeler cette API continuellement génère un log comme :

java.sql.SQLTransientConnectionException: HikariPool-1 - Connection is not available,
request timed out after 3000ms.

Quand vous fournissez cette stack trace à l’IA ainsi que le fichier application.properties, la suggestion retournée est généralement :

- La taille du pool (10) n'est probablement pas la cause principale ; le problème vient du fait que les connexions ne sont pas retournées au pool.
- Examinez tous les endroits où createEntityManager()/getConnection() est appelé manuellement.
- Assurez-vous d'utiliser try-with-resources ou de laisser Spring gérer la transaction.

Le vrai correctif est de supprimer complètement la création manuelle d’EntityManager, et d’utiliser un repository standard :

public interface OrderRepository extends JpaRepository<Order, Long> {
    List<Order> findAll();
}

@Service
public class OrderReportService {

    private final OrderRepository orderRepository;

    public OrderReportService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    public List<Order> findAllOrdersSafe() {
        return orderRepository.findAll(); // Spring gère automatiquement la connexion
    }
}

Note : Augmenter maximum-pool-size quand on rencontre cette erreur est une mauvaise approche — cela retarde juste le problème au lieu de corriger la fuite de connexions réelle.

4.3. Cas 2 — Requêtes N+1 qui ralentissent le système

public List<OrderSummary> summarize(List<Order> orders) {
    return orders.stream()
            .map(o -> new OrderSummary(o.getId(), o.getCustomer().getName())) // chargement lazy
            .toList();
}

Parce que customer est FetchType.LAZY, chaque élément génère une requête séparée vers customers. Exécuter EXPLAIN ANALYZE sur les logs Databricks montrera des centaines de fois :

SELECT * FROM customers WHERE id = $1;

L’IA en lisant le plan de requête détecte généralement :

- 200 requêtes répétant le même pattern SELECT ... WHERE id = $1 dans une seule demande.
- Suspicion de N+1 queries dû au chargement lazy sans JOIN FETCH.
- Suggestion : utiliser JOIN FETCH ou @EntityGraph pour fusionner en une seule requête.

Le correctif avec JPQL JOIN FETCH :

@Query("SELECT o FROM Order o JOIN FETCH o.customer")
List<Order> findAllWithCustomer();

Résultat : seulement une requête SELECT ... JOIN customers ... au lieu de N+1 requêtes séparées.

4.4. Cas 3 — Permissions manquantes

SELECT * FROM orders WHERE total > 1000;

ERROR: permission denied for table orders

L’IA croise les métadonnées du rôle dans Databricks et retourne la suggestion GRANT appropriée :

GRANT SELECT ON orders TO app_user;

Note : Vérifiez toujours les suggestions GRANT avant de les exécuter en production — l’IA connaît la syntaxe nécessaire pour que la requête s’exécute, mais pas votre politique de sécurité interne. Ne donnez jamais des permissions plus larges que le minimum nécessaire (principe du moindre privilège).

5. Écrire un test pour confirmer le correctif

Après avoir corrigé le N+1 du cas 4.3, testez pour vous assurer qu’il n’y a pas de régression :

@DataJpaTest
class OrderRepositoryTest {

    @Autowired
    private OrderRepository orderRepository;

    @Autowired
    private TestEntityManager entityManager;

    @Test
    void shouldFetchOrdersWithCustomerInOneQuery() {
        Customer customer = new Customer();
        customer.setName("Nón Lá Dev");
        entityManager.persist(customer);

        Order order = new Order();
        order.setCustomer(customer);
        order.setTotal(new BigDecimal("150.00"));
        entityManager.persist(order);
        entityManager.flush();

        List<Order> orders = orderRepository.findAllWithCustomer();

        assertThat(orders)
                .hasSize(1)
                .first()
                .extracting(o -> o.getCustomer().getName())
                .isEqualTo("Nón Lá Dev");
    }
}

Ce test ne « compte » pas directement le nombre de requêtes, mais combiné avec les statistiques Hibernate (spring.jpa.properties.hibernate.generate_statistics=true) vous pouvez logger le nombre de requêtes exécutées et vérifier qu’il égale 1 — c’est exactement le type de log que l’IA utilise pour confirmer qu’un correctif est efficace.

6. Surveillance pour un debugging IA plus efficace

Pour que l’IA (ou un collègue lisant le log plus tard) diagnostique rapidement, loggez de manière structurée au lieu d’un simple e.printStackTrace() :

@RestControllerAdvice
public class DatabaseExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(DatabaseExceptionHandler.class);

    @ExceptionHandler(DataAccessException.class)
    public ResponseEntity<String> handle(DataAccessException ex) {
        log.error("db_error_type={}, sql_state={}, message={}",
                ex.getClass().getSimpleName(),
                extractSqlState(ex),
                ex.getMostSpecificCause().getMessage());
        return ResponseEntity.status(503).body("Database error, retry later");
    }

    private String extractSqlState(DataAccessException ex) {
        if (ex.getCause() instanceof SQLException sqlEx) {
            return sqlEx.getSQLState();
        }
        return "unknown";
    }
}

Un logging au format clé-valeur (db_error_type=, sql_state=) est bien plus facile à parser qu’une stack trace brute, et c’est l’input idéal quand vous collez le log dans l’Assistant Databricks pour demander « d’où vient cette erreur ».

7. Quand NE PAS utiliser le debugging IA

• Erreurs impliquant des données sensibles : ne collez pas les logs contenant les vraies données client dans l’assistant IA, même en interne — masquez-les d’abord.
• Problèmes de performance au niveau infrastructure (latence disque, latence réseau entre régions) : l’IA peut lire le plan de requête mais ne voit pas la couche infrastructure physique, elle risque de donner de mauvaises suggestions (par exemple « ajouter un index » alors que la cause est réseau).
• Erreur transiente unique : si l’exception s’est produite une seule fois à cause d’une petite coupure réseau, déboguer avec l’IA coûte plus de temps que simplement faire un retry et surveiller ensuite.
• Remplacer la revue de code : les suggestions de l’IA sur les GRANT ou les changements de pool size doivent être confirmées par quelqu’un ayant l’autorité infrastructure, ce ne sont pas à appliquer automatiquement en production.

8. Conclusion

Le debugging IA de base de données sur Databricks excelle à lire rapidement la stack trace, le plan de requête et les métadonnées pour cibler la cause — fuite de connexions, requêtes N+1, permissions manquantes sont trois cas très communs que l’article a reproduits avec Spring Boot et PostgreSQL. La vraie valeur réside dans un logging structuré et des tests confirmant le correctif, car l’IA n’est performante que selon la qualité des données que vous fournissez. Vérifiez toujours les suggestions — en particulier les GRANT ou les changements infrastructure — avant de les appliquer au système en production.