MongoDB Atlas CLI : gérer vos bases de données en ligne de commande

MongoDB Atlas est un service de base de données cloud qui vous permet de déployer, gérer et faire évoluer des bases MongoDB. Vous pouvez administrer Atlas via l'Atlas UI, une interface web, ou via l'Atlas CLI, un outil en ligne de commande qui permet d'effectuer les mêmes opérations par commandes.

MongoDB Atlas CLI constitue une alternative plus rapide à l'Atlas UI. Vous pouvez exécuter et automatiser des tâches d'administration directement depuis votre terminal.

Dans cet article, je vous guide pas à pas pour gérer vos bases avec l'Atlas CLI.

Prérequis

Avant de commencer, assurez-vous de disposer :

• D'un compte MongoDB Atlas.
• D'une familiarité de base avec la ligne de commande.
• Des prérequis d'installation de l'Atlas CLI pour votre système d'exploitation.

Structure des commandes CLI

MongoDB Atlas CLI suit une structure de commande cohérente :

atlas [command] [subcommand] [flags]

Lorsque vous exécutez une commande sans sous-commandes ni indicateurs, le CLI affiche une aide comprenant :

• Usage : comment utiliser la commande.
• Aliases : noms alternatifs de la commande.
• Available commands : sous-commandes disponibles.
• Flags : options propres à la commande.
• Global flags : options valables pour toutes les commandes du CLI.

Par exemple, si vous exécutez :

atlas clusters

Vous obtiendrez une réponse similaire :

Manage clusters for your project. The clusters command provides access to your cluster configurations. You can create, edit, and delete clusters.

Usage:
  atlas clusters [command]

Aliases:
  clusters, cluster

Available Commands:
  list              Return all clusters for your project.
  describe          Return the details for the specified cluster for your project.
  advancedSettings  Manage advanced configuration settings for your cluster.
 ...

Flags:
  -h, --help   help for clusters

Global Flags:
  -P, --profile string   Name of the profile to use from your configuration file. To learn about profiles for the Atlas CLI, see https://dochub.mongodb.org/core/atlas-cli-save-connection-settings.

Use "atlas clusters [command] --help" for more information about a command.

Les noms de commandes, d'arguments et d'indicateurs dans l'Atlas CLI sont sensibles à la casse. Respectez exactement la capitalisation indiquée dans les exemples — par exemple, --orgId et non --orgID.

Créer un déploiement MongoDB

Un déploiement est une instance MongoDB en fonctionnement qui stocke et sert vos données. Chaque déploiement inclut les serveurs de base de données, le stockage, le réseau et les sauvegardes automatisées. MongoDB Atlas gère l'infrastructure, afin que vous puissiez vous concentrer sur l'utilisation de la base de données plutôt que sur la maintenance des serveurs.

Pour créer un déploiement MongoDB, installez ou mettez à jour l'Atlas CLI, puis exécutez la commande :

atlas setup

La commande atlas setup vous guide dans un processus interactif. Elle vous demande des choix de configuration et crée un projet, provisionne un cluster et configure des paramètres de sécurité de base.

S'authentifier avec un déploiement existant

Si vous disposez déjà d'un déploiement MongoDB Atlas et souhaitez le gérer via le CLI, vous devez vous authentifier. Pour vous connecter, exécutez :

atlas auth login

Cette commande vous invite à choisir un mode d'authentification, puis fournit un code de vérification à usage unique. Copiez le code et collez-le dans le navigateur lorsqu'il vous est demandé. Par exemple :

atlas auth login
? Select authentication type: UserAccount

To verify your account, copy your one-time verification code:
QPWF-6GT4

Paste the code in the browser when prompted to activate your Atlas CLI. Your code will expire after 3 minutes.

To continue, go to https://account.mongodb.com/account/connect

Press Enter to open the browser and complete authentication...
Successfully logged in as your-email@example.com.

Après authentification, vous choisirez une organisation par défaut et un format de sortie. Le CLI conserve votre session, mais elle expire périodiquement. Si vous voyez une erreur "session expired", exécutez de nouveau atlas auth login.

Gérer des profils pour plusieurs environnements

Les profils vous permettent de gérer plusieurs environnements MongoDB Atlas depuis la même installation du CLI. Chaque profil stocke des paramètres de connexion pour un environnement différent, comme développement, préproduction ou production.

Grâce aux profils, vous pouvez basculer rapidement d'un environnement à l'autre sans vous ré-authentifier ni modifier des fichiers de configuration. C'est utile si vous maintenez des projets ou organisations Atlas séparés selon les étapes de votre cycle de développement.

Une pratique courante consiste à créer des projets Atlas distincts pour chaque environnement et à les gérer via des profils — par exemple :

• Profil de développement : pointe vers votre projet de dev avec un petit cluster M0 pour les tests.
• Profil de préproduction : pointe vers votre projet de staging qui reflète la configuration de production.
• Profil de production : pointe vers votre projet de production avec des clusters calibrés pour la prod.

Créer des profils par environnement

Lors de la première exécution de atlas auth login, le CLI crée un profil par défaut. Pour créer des profils supplémentaires pour d'autres environnements, utilisez l'indicateur --profile :

atlas auth login --profile dev

Cela crée un profil nommé "dev" et vous guide dans le processus d'authentification. Répétez pour chaque environnement :

atlas auth login --profile staging
atlas auth login --profile production

Chaque profil conserve ses propres identifiants d'authentification ainsi que les paramètres d'organisation et de projet par défaut.

Lister les profils disponibles

Pour afficher tous les profils configurés, exécutez :

atlas config list

Vous verrez alors tous les noms de profils que vous avez créés.

Afficher le détail d'un profil

Pour consulter la configuration d'un profil spécifique, exécutez :

atlas config describe <profileName>

Par exemple :

atlas config describe dev

Cela affiche les paramètres du profil, y compris les IDs d'organisation et de projet par défaut.

Basculer entre les profils

Pour utiliser un profil spécifique pour une commande, ajoutez l'indicateur --profile :

atlas clusters list --profile production

Cette commande liste les clusters en utilisant les informations d'identification et les paramètres du profil de production.

Vous pouvez aussi définir un profil par défaut pour éviter de le préciser à chaque commande :

atlas config set --profile staging

Une fois défini, ce profil sera utilisé par défaut, sauf si vous le remplacez avec l'indicateur --profile.

Mettre à jour les paramètres d'un profil

Pour modifier la configuration d'un profil, exécutez :

atlas config set <setting> <value> --profile <profileName>

Par exemple, pour définir un projet par défaut pour le profil dev :

atlas config set project_id 5f8e8d9a1b2c3d4e5f6g7h8i --profile dev

Renommer des profils

Pour renommer un profil, exécutez :

atlas config rename <oldName> <newName>

Par exemple :

atlas config rename dev development

Gérer les projets

Dans MongoDB Atlas, les projets organisent vos clusters, utilisateurs et paramètres. Considérez un projet comme un conteneur regroupant des ressources de base de données liées.

Chaque projet peut contenir plusieurs clusters et dispose de ses propres utilisateurs et contrôles d'accès. Cette séparation est utile lorsque vous avez des applications, environnements ou équipes différents nécessitant des ressources isolées.

Créer des projets

Pour créer un nouveau projet, exécutez :

atlas projects create <projectName> [options]

Utilisez un nom explicite qui reflète l'objectif du projet, comme "ecommerce-transactions" ou "mobile-app-staging".

[options] comprend des indicateurs qui modifient le mode et l'emplacement de création du projet. Par exemple, vous pouvez préciser l'organisation dans laquelle créer le projet :

atlas projects create mobile-app-staging --orgId <organizationId>

L'indicateur --orgId spécifie l'organisation où créer le projet. Il est requis sauf si vous avez défini une organisation par défaut. Vous pouvez exécuter la commande atlas organizations list pour obtenir la liste de vos organisations et leur Id.

In all examples, replace placeholders like <projectId>, <clusterName>, and <username> with your actual project, cluster, or user names and identifiers.

Mettre à jour des projets

Pour mettre à jour les paramètres d'un projet, utilisez :

atlas projects update <projectId> [options]

Par exemple, vous pouvez utiliser l'option --name pour changer le nom du projet :

atlas projects update <projectId> --name newProjectName

Lister les projets

Pour lister tous les projets de votre organisation, utilisez :

atlas projects list [options]

La commande ci-dessus utilise l'option --orgId pour préciser l'organisation à lister :

atlas projects list --orgId <organizationId>

Vous pouvez aussi contrôler le format de sortie, par exemple afficher les résultats en JSON :

atlas projects list --output json

Supprimer des projets

Vous pouvez supprimer un projet via une commande Atlas CLI.

atlas projects delete <projectId> --orgId <organizationId>

Vous ne pouvez pas supprimer un projet qui contient encore des clusters actifs. Avant la suppression, supprimez donc tous les clusters qu'il renferme.

Gérer les clusters

Les clusters sont des groupes de serveurs MongoDB qui stockent vos données. Atlas gère pour vous l'infrastructure, la réplication et les sauvegardes.

Créer des clusters

Pour créer un nouveau cluster, exécutez :

atlas clusters create <clusterName> [options]

[options] comprend des indicateurs de configuration du cluster. Par exemple, vous pouvez préciser le fournisseur cloud, la région et le palier tarifaire MongoDB :

atlas clusters create myCluster --provider AWS --region US_EAST_1 --tier M0

Ici, l'indicateur --provider définit le fournisseur cloud, tel qu'AWS, GCP ou Azure. --region spécifie la région de déploiement. --tier définit la taille du cluster.

Si vous n'avez pas défini de projet par défaut, ajoutez l'indicateur --projectId :

atlas clusters create myCluster --projectId <projectId> --provider AWS --region US_EAST_1 --tier M0

Décrire des clusters

Pour afficher le détail d'un cluster, exécutez :

atlas clusters describe <clusterName> --projectId <projectId>

Cette commande précise la configuration, la taille, la région et les chaînes de connexion du cluster.

Lister les clusters

Pour lister tous les clusters d'un projet, exécutez :

atlas clusters list --projectId <projectId>

L'indicateur --projectId est requis sauf si vous avez défini un projet par défaut avec :

atlas config set project_id <projectId>

Mettre en pause des clusters

Vous pouvez mettre temporairement en pause un cluster sans le supprimer. Cela arrête ses opérations tout en préservant vos données et sa configuration :

atlas clusters pause <clusterName> --projectId <projectId>

Supprimer des clusters

Pour supprimer définitivement un cluster, exécutez :

atlas clusters delete <clusterName> --projectId <projectId>

Après avoir créé votre cluster, vous devez configurer la sécurité réseau avant de pouvoir vous y connecter.

Gérer la configuration de la liste d'accès IP

Une liste d'accès IP contrôle quelles adresses IP peuvent se connecter à vos clusters MongoDB Atlas. Chaque projet peut contenir jusqu'à 200 entrées. Vous pouvez ajouter des adresses IP individuelles, des plages en notation CIDR ou des IDs de groupes de sécurité AWS. Une plage CIDR définit un bloc d'adresses à partir d'une IP de base et d'un préfixe — par exemple, 192.168.0.0/24. Un ID de groupe de sécurité AWS autorise l'accès pour toutes les ressources de ce groupe.

Pour gérer les listes d'accès IP, vous devez avoir le rôle Project Owner sur le projet.

Ajouter des adresses IP à la liste d'accès

Pour ajouter votre adresse IP actuelle à la liste, exécutez :

atlas accessLists create --currentIp --projectId <projectId>

L'indicateur --currentIp ajoute automatiquement l'adresse IP de la machine qui exécute la commande. Pratique pour un accès rapide depuis votre poste de développement.

Pour ajouter une adresse IP précise, exécutez :

atlas accessLists create <ipAddress> --type ipAddress --projectId <projectId>

<ipAddress> est l'adresse à autoriser. Par exemple :

atlas accessLists create 192.0.2.15 --type ipAddress --comment "Office network" --projectId <projectId>

L'indicateur --comment ajoute une description pour retrouver l'entrée plus facilement.

Pour ajouter une plage d'adresses en notation CIDR, exécutez :

atlas accessLists create <cidrBlock> --type cidrBlock --projectId <projectId>

Par exemple :

atlas accessLists create 73.231.201.0/24 --type cidrBlock --comment "Development servers" --projectId <projectId>

Créer des entrées temporaires

Pour ajouter une adresse IP avec expiration automatique, utilisez l'indicateur --deleteAfter. Vous pouvez définir une date d'expiration jusqu'à sept jours plus tard :

atlas accessLists create <ipAddress> --type ipAddress --deleteAfter <isoDateTime> --projectId <projectId>

L'indicateur --deleteAfter accepte une date au format ISO-8601. Par exemple :

atlas accessLists create 192.0.2.20 --type ipAddress --deleteAfter 2025-12-31T23:59:59Z --comment "Temporary contractor access" --projectId <projectId>

MongoDB Atlas supprime automatiquement l'entrée à la date et l'heure indiquées.

Lister les entrées de la liste d'accès IP

Pour afficher toutes les entrées de liste d'accès IP du projet, exécutez :

atlas accessLists list --projectId <projectId>

Pour consulter le détail d'une entrée spécifique, exécutez :

atlas accessLists describe <entry> --projectId <projectId>

<entry> est l'adresse IP, le bloc CIDR ou l'ID de groupe de sécurité AWS à afficher.

Supprimer des entrées de liste d'accès IP

Pour retirer une adresse IP de la liste, exécutez :

atlas accessLists delete <entry> --projectId <projectId>

Gérer les utilisateurs et les rôles

Un rôle accorde des privilèges pour exécuter un ensemble d'actions sur des ressources spécifiques. Un utilisateur est une entité à laquelle on attribue un ou plusieurs rôles déterminant ses droits dans la base.

Pour configurer les utilisateurs et rôles de base de données, vous devez disposer des accès Organization Owner, Project Owner ou Project Database Access Admin dans MongoDB Atlas.

Gérer les utilisateurs

Pour créer un utilisateur de base de données, exécutez :

atlas dbusers create [builtInRole] [options]

[builtInRole] correspond à un ou plusieurs rôles intégrés à attribuer. [options] comprend les indicateurs pour définir ses identifiants et sa configuration. Par exemple :

atlas dbusers create --username myUser --password myPassword --role readWriteAnyDatabase --projectId <projectId>

L'indicateur --username définit le nom d'utilisateur. --password définit le mot de passe. --role précise le rôle à attribuer. Ici, le nom d'utilisateur est myUser et le mot de passe myPassword.

Pour lister tous les utilisateurs de base de données du projet, exécutez :

atlas dbusers list --projectId <projectId>

Pour afficher le détail d'un utilisateur précis, exécutez :

atlas dbusers describe <username> --projectId <projectId>

Vous pouvez aussi mettre à jour l'utilisateur. Par exemple, pour changer son mot de passe :

atlas dbusers update myUser --password newPassword --projectId <projectId>

Pour mettre à jour ses rôles :

atlas dbusers update myUser --role readWriteAnyDatabase --role dbAdmin --projectId <projectId>

Pour supprimer un utilisateur précis :

atlas dbusers delete <username> --projectId <projectId>

Gérer les rôles

Deux catégories de rôles peuvent être attribuées à un utilisateur :

• Rôles intégrés
• Rôles personnalisés

Rôles intégrés

Les rôles intégrés sont des rôles prédéfinis fournis par MongoDB Atlas. Ils regroupent des permissions usuelles selon les cas d'usage, par exemple :

• read : accès en lecture seule à une base spécifique.
• readWrite : lecture et modification des données d'une base spécifique.
• readAnyDatabase : lecture seule sur toutes les bases sauf local et config.
• readWriteAnyDatabase : lecture et écriture sur toutes les bases.
• dbAdmin : privilèges d'administration pour une base spécifique (création d'index, consultation de statistiques, etc.).
• dbAdminAnyDatabase : privilèges d'administration sur toutes les bases.
• clusterAdmin : gestion du cluster dans son ensemble, y compris réplication et sharding.
• userAdminAnyDatabase : création et modification des comptes utilisateurs et rôles sur toutes les bases.

Vous ne pouvez pas modifier ni supprimer les rôles intégrés : vous pouvez seulement les attribuer. Pour attribuer des rôles intégrés à la création d'utilisateurs, spécifiez le rôle avec l'indicateur --role :

atlas dbusers create --username app-reader --password myPassword --role readAnyDatabase --projectId <projectId>

Pour attribuer ou changer le rôle d'un utilisateur existant, exécutez :

atlas dbusers update app-reader --role readWriteAnyDatabase --projectId <projectId>

Consultez [Built-In Roles and Privileges](https://www.mongodb.com/docs/atlas/mongodb-users-roles-and-privileges/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=atlas-cli-datacamp&utm_term=megan.grant) pour d'autres rôles intégrés attribuables.

Rôles personnalisés

Lorsque les rôles intégrés ne suffisent pas, MongoDB Atlas permet de créer des rôles personnalisés. Un rôle personnalisé définit un ensemble d'actions de privilège correspondant à vos besoins applicatifs ou d'équipe.

Lors de la création d'un rôle personnalisé, déterminez les collections auxquelles les utilisateurs doivent accéder et les actions autorisées sur les ressources — par exemple lire, insérer, mettre à jour ou supprimer des données.

Dans les définitions de privilèges MongoDB, vous devez utiliser le nom d'action en MAJUSCULES dans votre commande CLI, par exemple FIND et non find. Voir Privilege Actions pour la liste des actions possibles sur une ressource.

Vous pouvez gérer les rôles personnalisés avec l'Atlas CLI.

Pour créer un rôle personnalisé, exécutez :

atlas customDbRoles create <roleName> [options]

<roleName> est le nom du rôle personnalisé. [options] comprend les indicateurs définissant ses permissions — par exemple :

atlas customDbRoles create customAnalyticsRole --privilege FIND@myDatabase.users

Dans la commande ci-dessus :

• customAnalyticsRole est le nom du nouveau rôle personnalisé. Choisissez un nom explicite reflétant son objectif.
• L'indicateur --privilege précise les actions autorisées sur les ressources.
• Le format est action@database.collection, où @ sépare l'action de la ressource.
• FIND est une action de privilège reconnue par MongoDB.
• myDatabase.users est la ressource ciblée — ici, la collection users de la base myDatabase.

Pour afficher les rôles personnalisés, exécutez :

atlas customDbRoles list --projectId <projectId>

Cette commande liste tous les rôles personnalisés et leurs permissions.

Pour mettre à jour un rôle personnalisé, exécutez :

atlas customDbRoles update <roleName> [options]

[options] précise ce qui doit être modifié. Par exemple, pour ajouter de nouveaux privilèges :

atlas customDbRoles update customAnalyticsRole --privilege FIND@myDatabase.analytics --privilege INSERT@myDatabase.logs --projectId <projectId>

Cette commande met à jour customAnalyticsRole en lui accordant des privilèges supplémentaires. FIND@myDatabase.analytics autorise la lecture dans la collection analytics, et INSERT@myDatabase.logs l'insertion dans la collection logs de myDatabase.

L'indicateur --projectId spécifie le projet Atlas auquel le rôle appartient.

Pour supprimer un rôle personnalisé, exécutez :

atlas customDbRoles delete <roleName> --projectId <projectId>

L'attribution d'un rôle personnalisé à un utilisateur se fait comme pour un rôle intégré. Utilisez l'indicateur --role avec les commandes atlas dbusers create ou atlas dbusers update :

atlas dbusers create --username analytics-user --password myPassword --role customAnalyticsRole --projectId <projectId>

Une fois vos utilisateurs créés et leurs rôles attribués, vous pouvez vous connecter à votre cluster.

Récupérer les chaînes de connexion

Une chaîne de connexion contient les informations nécessaires pour connecter vos applications à votre cluster Atlas : hôte du cluster, base d'authentification et options de connexion.

Avant de l'utiliser, assurez-vous d'avoir configuré votre liste d'accès IP et créé au moins un utilisateur de base.

Obtenir la chaîne de connexion d'un cluster

Pour récupérer la chaîne de connexion d'un cluster, exécutez :

atlas clusters connectionStrings describe <clusterName> --projectId <projectId>

Cette commande renvoie la chaîne de connexion SRV de votre cluster.

Formats de chaîne de connexion

MongoDB Atlas propose deux types de chaînes de connexion :

Chaîne standard (mongodb://) : liste explicitement tous les nœuds du cluster. Utilisez ce format si vous devez spécifier des adresses serveur individuelles.

Chaîne SRV (mongodb+srv://) : utilise le DNS pour récupérer automatiquement les informations du cluster. C'est le format recommandé, car il s'adapte automatiquement en cas de changement de configuration.

Utiliser la chaîne de connexion

Remplacez <username> et <password> dans la chaîne par les identifiants de votre utilisateur de base :

mongodb+srv://<username>:<password>@cluster0.example.mongodb.net/

Par exemple, si votre nom d'utilisateur est appUser et votre mot de passe securePass123 :

mongodb+srv://appUser:securePass123@cluster0.example.mongodb.net/

Vous pouvez ensuite utiliser cette chaîne avec les MongoDB Drivers, le MongoDB Shell ou d'autres outils MongoDB pour vous connecter à votre cluster.

Gérer les sauvegardes

Les sauvegardes sont des copies de vos données permettant de restaurer un cluster en cas de perte ou de corruption. Atlas crée automatiquement des sauvegardes à intervalles réguliers.

Automated continuous backups are only available for M10+ dedicated clusters. M0 free-tier clusters do not have backup capabilities. M2/M5 shared clusters have basic cloud backups, but not continuous backup. For more information, see [Snapshots for Flex Clusters](https://www.mongodb.com/docs/atlas/backup-restore-cluster/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=atlas-cli-datacamp&utm_term=megan.grant#snapshots-for-flex-clusters).

Pour gérer les sauvegardes, vous devez avoir les accès Organization Owner ou Project Owner dans Atlas.

Créer des sauvegardes à la demande

Pour créer immédiatement une sauvegarde, exécutez :

atlas backups snapshots create <clusterName> --desc "Backup description" --projectId <projectId>

Dans cette commande, --desc est un indicateur requis décrivant le snapshot.

Lister les sauvegardes disponibles

Pour lister toutes les sauvegardes d'un cluster, exécutez :

atlas backups snapshots list <clusterName> --projectId <projectId>

Décrire la configuration de sauvegarde

Pour afficher les paramètres de sauvegarde d'un cluster, exécutez :

atlas backups schedule describe <clusterName> --projectId <projectId>

Restaurer depuis une sauvegarde

Pour restaurer des données à partir d'une sauvegarde, exécutez :

atlas backups restores start <clusterName> --snapshotId <snapshotId> --targetClusterName <targetClusterName> --projectId <projectId>

L'indicateur --snapshotId précise la sauvegarde à restaurer. --targetClusterName indique le nom du cluster cible — par exemple :

atlas backups restores start myCluster --snapshotId 5f8e8d9a1b2c3d4e5f6g7h8i --targetClusterName myCluster-restored --projectId <projectId>

Supprimer des sauvegardes

Pour supprimer une sauvegarde, exécutez :

atlas backups snapshots delete <snapshotId> --projectId <projectId>

Conclusion

Dans cet article, nous avons parcouru la structure des commandes CLI, la création de déploiements, la gestion des projets et des clusters, la configuration des utilisateurs et des rôles, ainsi que la gestion des sauvegardes. Vous pouvez automatiser ces opérations en les combinant dans des scripts pour faciliter la gestion de multiples environnements et intégrer l'administration de la base à votre flux de développement.