From b00d6294a14943f7266c38211345a7555a187fa4 Mon Sep 17 00:00:00 2001 From: Hampus Lavin Date: Tue, 29 Oct 2024 15:02:01 +0100 Subject: [PATCH] feat: add advanced example for database connections limit --- .../18-testing/03-advanced-examples.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/06-concepts/18-testing/03-advanced-examples.md b/docs/06-concepts/18-testing/03-advanced-examples.md index 27078416..f2162090 100644 --- a/docs/06-concepts/18-testing/03-advanced-examples.md +++ b/docs/06-concepts/18-testing/03-advanced-examples.md @@ -113,3 +113,37 @@ withServerpod('Given CommunicationExampleEndpoint', (sessionBuilder, endpoints) }); }); ``` + +## Optimising number of database connections + +By default Dart runs tests concurrently. The number of concurrent tests depends on the running hosts's available CPU cores. If the host has a lot of cores it could trigger a case where the number of connections to the database exceeeds the maximum connections limit set for the database, which will cause tests to fail. + +Each `withServerpod` call will lazily create its own Serverpod instance which will connect to the database. Specifically, the code that causes the Serverpod instance to be created is `sessionBuilder.build()`, which happens at the latest in an endpoint call if not called by the test before. + +If a test needs a session before the endpoint call (e.g. to seed the database), `sessionBuilder.build()` has to be called which then triggers a database connection attempt. + +If the max connection limit is hit, there are two options: + +- Raise the max connections limit on the database. +- Build out the session in `setUp`/`setUpAll` instead of the top level scope: + +```dart +withServerpod('Given example test', (sessionBuilder, endpoints) { + // Instead of this + var session = sessionBuilder.build(); + + + // Do this to postpone connecting to the database until the test group is running + late Session session; + setUpAll(() { + session = sessionBuilder.build(); + }); + // ... +}); +``` + +:::info + +This case should be rare and the above example is not a recommended best practice unless this problem is anticipated, or it has started happening. + +:::