@aventii/db (1.2.1)
Installation
@aventii:registry=npm install @aventii/db@1.2.1"@aventii/db": "1.2.1"About this package
@aventii/db
Primitives génériques de connexion aux bases de données pour les services Aventii.
Le package fournit une abstraction légère permettant de gérer le cycle de vie d'une connexion à une base de données sans imposer :
- un moteur de base de données unique ;
- une méthode unique de récupération de la chaîne de connexion ;
- une structure particulière de bases, collections ou modèles.
Il prend actuellement en charge MongoDB natif et Mongoose.
Installation
Le package est distribué sur le registre npm privé Aventii.
npm install @aventii/db
L'accès au registre nécessite une configuration npm Aventii valide.
Principes
@aventii/db sépare trois responsabilités :
- le gestionnaire de connexion ;
- l'adapter correspondant au moteur utilisé ;
- le provider fournissant la chaîne de connexion.
Le service consommateur reste responsable de ses bases, collections, modèles et règles métier.
Gestionnaire de connexion
createDatabaseManager crée un gestionnaire générique à partir d'un
adapter et d'un secret provider.
const { createDatabaseManager } = require('@aventii/db');
const database = createDatabaseManager({
adapter,
secretProvider
});
await database.initialize();
Le gestionnaire récupère la chaîne de connexion, établit la connexion, conserve son état, effectue un nombre borné de tentatives au démarrage, peut vérifier périodiquement si la chaîne de connexion a changé et permet une fermeture propre.
Initialisation et politique d'échec
const database = createDatabaseManager({
adapter,
secretProvider,
retry: {
attempts: 3,
delayMs: 1000,
timeoutMs: 20000
}
});
Si aucune connexion ne peut être établie dans les limites configurées,
initialize() lève une erreur.
État et accès à la connexion
const status = database.getStatus();
const connection = database.getConnection();
const db = database.getDb('Auth');
L'état contient notamment connected, lastAttempt, lastSuccess,
lastError et attempts.
Le package ne décide pas quelles bases ou collections doivent être utilisées.
MongoDB natif
createMongoAdapter utilise le driver officiel MongoDB.
const {
createDatabaseManager,
createMongoAdapter
} = require('@aventii/db');
const database = createDatabaseManager({
adapter: createMongoAdapter(),
secretProvider
});
await database.initialize();
const users = database.getDb('Auth').collection('Users');
Des options du MongoClient peuvent être fournies :
const { ServerApiVersion } = require('mongodb');
const adapter = createMongoAdapter({
clientOptions: {
serverApi: {
version: ServerApiVersion.v1,
strict: true,
deprecationErrors: true
}
}
});
Mongoose
createMongooseAdapter utilise une connexion Mongoose.
const {
createDatabaseManager,
createMongooseAdapter
} = require('@aventii/db');
const database = createDatabaseManager({
adapter: createMongooseAdapter(),
secretProvider
});
await database.initialize();
const authDb = database.getDb('Auth');
La connexion obtenue peut être utilisée avec les modèles Mongoose :
const User = authDb.model('User', userSchema, 'Users');
ou directement avec les collections :
const users = authDb.collection('Users');
Secret provider HTTP
createHttpSecretProvider permet de récupérer la chaîne de connexion
depuis un service HTTP de gestion des secrets.
const { createHttpSecretProvider } = require('@aventii/db');
const secretProvider = createHttpSecretProvider({
baseUrl: process.env.KEY_API_URL,
secretName: {
production: 'MONGO_URI',
stage: 'MONGO_URI_STAGE',
default: 'MONGO_URI_PREPROD'
},
environment: process.env.NODE_ENV,
getAuthToken
});
Le package connaît le mécanisme générique de récupération du secret sans connaître l'adresse du service ni le mécanisme d'authentification du produit.
URI fournie directement
L'utilisation d'un service de secrets n'est pas obligatoire.
const { createDirectSecretProvider } = require('@aventii/db');
const secretProvider = createDirectSecretProvider(process.env.MONGO_URI);
Rafraîchissement de la chaîne de connexion
const database = createDatabaseManager({
adapter,
secretProvider,
refreshIntervalMs: 15 * 60 * 1000
});
Lorsqu'une nouvelle chaîne de connexion est détectée, une nouvelle connexion est créée avant la fermeture de l'ancienne.
Le rafraîchissement peut être désactivé :
refreshIntervalMs: 0
Cela est notamment utile lorsque le consommateur conserve des objets liés à une connexion particulière, par exemple certains modèles Mongoose.
Hook de connexion
const database = createDatabaseManager({
adapter,
secretProvider,
onConnected: async connection => {
// Initialisation propre au consommateur.
}
});
Ce hook peut notamment servir à créer ou vérifier des index. S'il échoue, la nouvelle connexion n'est pas considérée comme valide.
Fermeture propre
await database.close();
Par exemple :
async function gracefulShutdown() {
await database.close();
process.exit(0);
}
process.on('SIGINT', gracefulShutdown);
process.on('SIGTERM', gracefulShutdown);
Plusieurs moteurs dans un même service
Plusieurs gestionnaires indépendants peuvent être créés. Un même microservice peut donc utiliser simultanément MongoDB natif, Mongoose ou d'autres adapters futurs.
Chaque gestionnaire possède sa propre connexion et son propre cycle de vie.
API
Le package expose actuellement :
createDatabaseManager
createMongoAdapter
createMongooseAdapter
createHttpSecretProvider
createDirectSecretProvider
Une instance créée par createDatabaseManager expose :
initialize
refresh
close
getStatus
getConnection
getDb
Hors périmètre
@aventii/db ne décide pas :
- quelles bases doivent être utilisées ;
- quelles collections doivent être utilisées ;
- quels modèles ou schémas doivent être créés ;
- comment les données métier sont structurées ;
- quelles routes accèdent aux données ;
- si un service doit utiliser MongoDB natif ou Mongoose ;
- si le rafraîchissement dynamique d'une connexion est approprié au consommateur.
Ces décisions appartiennent au service consommateur.
Tests
npm test
Les tests couvrent séparément :
- le gestionnaire de connexion ;
- l'adapter MongoDB natif ;
- l'adapter Mongoose ;
- le provider HTTP ;
- le provider direct ;
- les politiques d'initialisation et d'échec.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| jest | ^30.0.0 |
| mongodb | ^6.0.0 |
| mongoose | ^8.0.0 |
Peer Dependencies
| ID | Version |
|---|---|
| mongodb | >=6 |
| mongoose | >=8 |