MongoDB Atlas CLI: gestire i database dalla riga di comando

MongoDB Atlas è un servizio di database basato su cloud che ti permette di distribuire, gestire e scalare database MongoDB. Puoi amministrare Atlas tramite l’Atlas UI, un’interfaccia web, oppure l’Atlas CLI, uno strumento a riga di comando che ti consente di svolgere le stesse operazioni con dei comandi.

MongoDB Atlas CLI offre un’alternativa più veloce all’Atlas UI. Puoi eseguire e automatizzare le attività di gestione del database direttamente dal terminale.

In questo articolo ti mostrerò come usare l’Atlas CLI per gestire i tuoi database.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Un account MongoDB Atlas.
• Conoscenze di base della riga di comando.
• Requisiti di installazione dell’Atlas CLI per il tuo sistema operativo.

Struttura dei comandi della CLI

MongoDB Atlas CLI segue una struttura di comando coerente:

atlas [command] [subcommand] [flags]

Quando esegui un comando senza subcommand o flag, la CLI mostra le informazioni di aiuto che includono:

• Usage: come utilizzare il comando.
• Aliases: nomi alternativi del comando.
• Available commands: i sotto-comandi disponibili.
• Flags: opzioni specifiche del comando.
• Global flags: opzioni disponibili per tutti i comandi della CLI.

Per esempio, se esegui:

atlas clusters

Otterrai una risposta simile a questa:

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.

I nomi dei comandi, gli argomenti e i nomi dei flag nell’Atlas CLI fanno distinzione tra maiuscole e minuscole. Usa esattamente le maiuscole/minuscole mostrate negli esempi — per esempio, --orgId e non --orgID.

Crea un deployment MongoDB

Un deployment è un’istanza attiva di MongoDB che archivia e serve i tuoi dati. Ogni deployment include i server di database, lo storage, il networking e i backup automatici. MongoDB Atlas gestisce l’infrastruttura, così puoi concentrarti sull’uso del database invece di mantenere i server.

Per creare un deployment MongoDB, installa o aggiorna l’Atlas CLI, poi esegui il comando:

atlas setup

Il comando atlas setup ti guida in un processo interattivo. Ti chiede di scegliere le impostazioni di configurazione e crea un progetto, effettua il provisioning di un cluster e configura le impostazioni di sicurezza di base.

Autenticati con un deployment esistente

Se hai già un deployment MongoDB Atlas e vuoi gestirlo con la CLI, devi autenticarti. Per accedere, esegui:

atlas auth login

Questo comando ti chiede di selezionare il tipo di autenticazione, quindi fornisce un codice di verifica monouso. Copia il codice e incollalo nel browser quando richiesto. Per esempio:

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.

Dopo l’autenticazione, selezionerai un’organizzazione predefinita e il formato di output. La CLI memorizza la tua sessione, ma scade periodicamente. Quando vedi un errore di "session expired", esegui di nuovo atlas auth login.

Gestisci i profili per ambienti multipli

I profili ti consentono di gestire più ambienti MongoDB Atlas dalla stessa installazione della CLI. Ogni profilo memorizza le impostazioni di connessione per un ambiente diverso, come sviluppo, staging o produzione.

Usando i profili, puoi passare rapidamente da un ambiente all’altro senza ri-autenticarti o modificare i file di configurazione. Questo è utile quando mantieni progetti o organizzazioni MongoDB Atlas separati per le diverse fasi del flusso di lavoro di sviluppo.

Una prassi comune è creare progetti Atlas separati per ogni ambiente e usare i profili per gestirli — per esempio:

• Profilo di sviluppo: punta al tuo progetto di dev con un piccolo cluster M0 per i test.
• Profilo di staging: punta al tuo progetto di staging che rispecchia la configurazione di produzione.
• Profilo di produzione: punta al tuo progetto di produzione con cluster di livello enterprise.

Crea profili per ambienti diversi

Alla prima esecuzione di atlas auth login, la CLI crea un profilo predefinito. Per creare profili aggiuntivi per altri ambienti, usa il flag --profile:

atlas auth login --profile dev

Questo crea un profilo chiamato "dev" e ti guida nel processo di autenticazione. Ripeti per ogni ambiente:

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

Ogni profilo memorizza le proprie credenziali di autenticazione, il progetto e le impostazioni dell’organizzazione predefiniti.

Elenca i profili disponibili

Per visualizzare tutti i profili configurati, esegui:

atlas config list

Questo mostra tutti i nomi dei profili che hai creato.

Visualizza i dettagli di un profilo

Per vedere la configurazione di un profilo specifico, esegui:

atlas config describe <profileName>

Per esempio:

atlas config describe dev

Questo visualizza le impostazioni del profilo, inclusi gli ID dell’organizzazione e del progetto predefiniti.

Passa da un profilo all’altro

Per usare un profilo specifico con un comando, aggiungi il flag --profile:

atlas clusters list --profile production

Questo elenca i cluster usando le credenziali e le impostazioni del profilo di produzione.

Puoi anche impostare un profilo predefinito così non devi specificarlo a ogni comando:

atlas config set --profile staging

Dopo aver impostato un predefinito, tutti i comandi useranno quel profilo a meno che tu non lo sovrascriva con il flag --profile.

Aggiorna le impostazioni di un profilo

Per modificare la configurazione di un profilo, esegui:

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

Per esempio, per impostare un progetto predefinito per il profilo dev:

atlas config set project_id 5f8e8d9a1b2c3d4e5f6g7h8i --profile dev

Rinomina i profili

Per rinominare un profilo, esegui:

atlas config rename <oldName> <newName>

Per esempio:

atlas config rename dev development

Gestisci i progetti

I progetti in MongoDB Atlas organizzano i tuoi cluster, utenti e impostazioni. Pensa a un progetto come a un contenitore che raggruppa risorse di database correlate.

Ogni progetto contiene più cluster e ha il proprio set di utenti e controlli di accesso. Questa separazione è utile quando hai applicazioni, ambienti o team diversi che necessitano di risorse di database isolate.

Crea progetti

Per creare un nuovo progetto, esegui:

atlas projects create <projectName> [options]

Usa un nome descrittivo che indichi lo scopo del progetto, come "ecommerce-transactions" o "mobile-app-staging".

[options] include flag che modificano come e dove viene creato il progetto. Per esempio, puoi specificare l’organizzazione in cui creare il progetto:

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

Il flag --orgId specifica l’organizzazione in cui creare il progetto. È obbligatorio a meno che tu non abbia impostato un’organizzazione predefinita. Puoi eseguire il comando atlas organizations list per ottenere l’elenco delle tue organizzazioni e il loro Id.

In tutti gli esempi, sostituisci i segnaposto come <projectId>, <clusterName> e <username> con i nomi e gli identificatori reali del tuo progetto, cluster o utente.

Aggiorna i progetti

Per aggiornare le impostazioni di un progetto, usa:

atlas projects update <projectId> [options]

Per esempio, puoi usare il flag --name come opzione per cambiare il nome del progetto:

atlas projects update <projectId> --name newProjectName

Elenca i progetti

Per elencare tutti i progetti nella tua organizzazione, usa:

atlas projects list [options]

Il comando precedente usa il flag --orgId come opzione per specificare da quale organizzazione elencare i progetti:

atlas projects list --orgId <organizationId>

Puoi anche controllare il formato dell’output, ad esempio visualizzando i risultati in JSON:

atlas projects list --output json

Elimina i progetti

Puoi eliminare un progetto usando un comando dell’Atlas CLI.

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

Non puoi eliminare un progetto che contiene ancora cluster attivi. Quindi, prima di eliminare un progetto, assicurati di eliminare tutti i cluster al suo interno.

Gestisci i cluster

I cluster sono gruppi di server MongoDB che archiviano i tuoi dati. Atlas gestisce per te l’infrastruttura, la replica e il backup dei cluster.

Crea cluster

Per creare un nuovo cluster, esegui:

atlas clusters create <clusterName> [options]

[options] include flag che specificano la configurazione del cluster. Per esempio, puoi includere opzioni per configurare il cloud provider, la regione e il tier di prezzo di MongoDB:

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

In questo comando, il flag --provider specifica il cloud provider, come AWS, GCP o Azure. Il flag --region specifica la regione in cui verrà distribuito il cluster. Il flag --tier specifica la dimensione del cluster.

Se non hai impostato un progetto predefinito, includi il flag --projectId:

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

Descrivi i cluster

Per visualizzare i dettagli di un cluster specifico, esegui:

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

Questo comando mostra la configurazione del cluster, dimensione, regione e stringhe di connessione.

Elenca i cluster

Per elencare tutti i cluster nel tuo progetto, esegui:

atlas clusters list --projectId <projectId>

Il flag --projectId è obbligatorio a meno che tu non abbia impostato un progetto predefinito usando:

atlas config set project_id <projectId>

Metti in pausa i cluster

Puoi mettere temporaneamente in pausa un cluster senza eliminarlo. Questo interrompe le operazioni del cluster ma preserva i tuoi dati e la configurazione:

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

Elimina i cluster

Per eliminare definitivamente un cluster, esegui:

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

Dopo aver creato il tuo cluster, devi configurare la sicurezza di rete prima di poterti connettere.

Gestisci la configurazione della lista di accesso IP

Una lista di accesso IP controlla quali indirizzi IP possono connettersi ai tuoi cluster MongoDB Atlas. Ogni progetto può avere fino a 200 voci nella lista. Puoi aggiungere singoli indirizzi IP, intervalli in notazione CIDR o ID di gruppi di sicurezza AWS. Un intervallo in notazione CIDR definisce un blocco di indirizzi IP usando un IP di base e un prefisso — per esempio, 192.168.0.0/24. Un ID di gruppo di sicurezza AWS consente l’accesso da tutte le risorse all’interno del gruppo di sicurezza AWS specificato.

Per gestire le liste di accesso IP, devi avere accesso come Project Owner al progetto.

Aggiungi indirizzi IP alla lista di accesso

Per aggiungere il tuo indirizzo IP corrente alla lista di accesso, esegui:

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

Il flag --currentIp aggiunge automaticamente l’indirizzo IP della macchina da cui esegui il comando. È utile quando ti serve un accesso rapido dalla tua macchina di sviluppo.

Per aggiungere un indirizzo IP specifico, esegui:

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

<ipAddress> è l’indirizzo IP che vuoi consentire. Per esempio:

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

Il flag --comment aggiunge una descrizione per aiutarti a identificare la voce in seguito.

Per aggiungere un intervallo di indirizzi IP usando la notazione CIDR, esegui:

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

Per esempio:

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

Crea voci temporanee nella lista di accesso

Per aggiungere un indirizzo IP che scade automaticamente dopo un certo tempo, usa il flag --deleteAfter. Puoi impostare date di scadenza fino a sette giorni nel futuro:

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

Il flag --deleteAfter accetta una data in formato ISO-8601. Per esempio:

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

MongoDB Atlas rimuove automaticamente la voce dopo la data e l’ora specificate.

Elenca le voci della lista di accesso IP

Per visualizzare tutte le voci della lista di accesso IP nel tuo progetto, esegui:

atlas accessLists list --projectId <projectId>

Per visualizzare i dettagli di una voce specifica, esegui:

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

<entry> è l’indirizzo IP, il blocco CIDR o l’ID del gruppo di sicurezza AWS che vuoi visualizzare.

Elimina voci della lista di accesso IP

Per rimuovere un indirizzo IP dalla lista di accesso, esegui:

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

Gestisci utenti e ruoli

Un ruolo concede privilegi per eseguire insiemi di azioni su risorse specifiche. Un utente è un’entità a cui vengono assegnati uno o più ruoli che determinano a cosa può accedere nel database.

Per configurare gli utenti e i ruoli del database, devi avere accesso in MongoDB Atlas come Organization Owner, Project Owner o Project Database Access Admin.

Gestisci gli utenti

Per creare un utente del database, esegui:

atlas dbusers create [builtInRole] [options]

[builtInRole] è uno o più ruoli predefiniti da assegnare all’utente. [options] include flag che specificano le credenziali e la configurazione dell’utente. Per esempio:

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

Il flag --username specifica il nome utente. Il flag --password specifica la password. Il flag --role specifica il ruolo da assegnare. In questo caso, lo username è myUser, mentre la password è myPassword.

Per elencare tutti gli utenti del database nel tuo progetto, esegui:

atlas dbusers list --projectId <projectId>

Per visualizzare i dettagli di un utente specifico, esegui:

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

Puoi anche aggiornare l’utente del database. Per esempio, per aggiornare la password di un utente, esegui:

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

Per aggiornare i ruoli di un utente, esegui:

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

Per eliminare un utente specifico del database, esegui:

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

Gestisci i ruoli

Ci sono due categorie di ruoli che puoi assegnare a un utente:

• Ruoli predefiniti (built-in)
• Ruoli personalizzati

Ruoli predefiniti

I ruoli predefiniti sono ruoli già pronti forniti da MongoDB Atlas. Includono insiemi di permessi comuni per diversi casi d’uso del database, come:

• read: concede accesso in sola lettura a un database specifico.
• readWrite: consente di leggere e modificare i dati in un database specifico.
• readAnyDatabase: concede accesso in sola lettura a tutti i database tranne i database local e config.
• readWriteAnyDatabase: concede accesso in lettura e scrittura a tutti i database.
• dbAdmin: fornisce privilegi amministrativi per un database specifico, come creare indici o visualizzare statistiche.
• dbAdminAnyDatabase: concede privilegi amministrativi su tutti i database.
• clusterAdmin: consente di gestire l’intero cluster, inclusi replica e sharding.
• userAdminAnyDatabase: consente di creare e modificare account utente e ruoli su tutti i database.

Non puoi modificare o eliminare i ruoli predefiniti. Puoi solo assegnarli agli utenti. Per assegnare ruoli predefiniti quando crei utenti, specifica il ruolo con il flag --role:

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

Per assegnare o cambiare il ruolo di un utente esistente, esegui:

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

Consulta [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) per altri ruoli predefiniti assegnabili agli utenti.

Ruoli personalizzati

MongoDB Atlas ti permette di creare ruoli personalizzati quando i ruoli predefiniti non soddisfano le tue esigenze. Un ruolo personalizzato definisce un set di azioni privilegiate specifiche che corrispondono ai requisiti della tua applicazione o del tuo team.

Quando crei un ruolo personalizzato, decidi a quali collezioni gli utenti debbano accedere e quali azioni sulle risorse possano effettuare — per esempio, leggere, inserire, aggiornare o eliminare dati.

Nelle definizioni dei privilegi in MongoDB, devi usare il nome dell’azione privilegiata in MAIUSCOLO nel comando CLI, ad esempio FIND, non find. Vedi Privilege Actions per ulteriori azioni privilegiate che un utente può eseguire su una risorsa.

Puoi gestire i ruoli personalizzati con l’Atlas CLI.

Per creare un ruolo personalizzato, esegui:

atlas customDbRoles create <roleName> [options]

<roleName> è il nome del ruolo personalizzato che vuoi creare. [options] include flag che specificano i permessi del ruolo — per esempio:

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

Nel comando precedente:

• customAnalyticsRole è il nome del nuovo ruolo personalizzato. Puoi scegliere qualsiasi nome descrittivo che rifletta lo scopo del ruolo.
• Il flag --privilege specifica quali azioni sulle risorse può eseguire il ruolo.
• Il formato è action@database.collection, dove @ separa l’azione dalla risorsa.
• FIND è un’azione privilegiata riconosciuta da MongoDB.
• myDatabase.users è la risorsa a cui si applica il privilegio — in questo caso, la collezione users nel database myDatabase.

Per visualizzare i dettagli di un ruolo personalizzato, esegui:

atlas customDbRoles list --projectId <projectId>

Il comando precedente mostra tutti i ruoli personalizzati e i loro permessi.

Per aggiornare un ruolo personalizzato, esegui:

atlas customDbRoles update <roleName> [options]

[options] include flag che specificano cosa aggiornare. Per esempio, per aggiungere un nuovo privilegio a un ruolo esistente, esegui:

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

Il comando precedente aggiorna l’esistente customAnalyticsRole per concedere privilegi aggiuntivi. FIND@myDatabase.analytics consente al ruolo di leggere i documenti dalla collezione analytics, e INSERT@myDatabase.logs gli permette di aggiungere documenti alla collezione logs nel database myDatabase.

Il flag --projectId specifica a quale progetto MongoDB Atlas appartiene il ruolo.

Per eliminare un ruolo personalizzato, esegui:

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

L’assegnazione di un ruolo personalizzato a un utente è simile all’assegnazione di un ruolo predefinito. Usa il flag --role con i comandi atlas dbusers create o atlas dbusers update:

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

Dopo aver creato gli utenti del database e assegnato i ruoli, sei pronto per connetterti al tuo cluster.

Recupera le stringhe di connessione

Una stringa di connessione contiene le informazioni di cui le tue applicazioni hanno bisogno per connettersi al tuo cluster Atlas. La stringa include l’hostname del cluster, il database di autenticazione e le opzioni di connessione.

Prima di poter usare una stringa di connessione, assicurati di aver configurato la tua lista di accesso IP e creato almeno un utente del database.

Ottieni la stringa di connessione di un cluster

Per recuperare la stringa di connessione di un cluster, esegui:

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

Questo comando restituisce la stringa di connessione SRV del tuo cluster.

Formati della stringa di connessione

MongoDB Atlas fornisce due tipi di stringhe di connessione:

Stringa di connessione standard (mongodb://): elenca esplicitamente tutti i nodi del cluster. Usa questo formato quando devi specificare singoli indirizzi dei server.

Stringa di connessione SRV (mongodb+srv://): usa il DNS per recuperare automaticamente le informazioni del cluster. È il formato consigliato perché si aggiorna automaticamente se la configurazione del cluster cambia.

Usa la stringa di connessione

Sostituisci <username> e <password> nella stringa di connessione con le credenziali del tuo utente del database:

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

Per esempio, se il tuo username è appUser e la password è securePass123:

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

Puoi quindi usare questa stringa di connessione con i MongoDB Driver, la MongoDB Shell o altri strumenti MongoDB per connetterti al tuo cluster.

Gestisci i backup

I backup sono copie dei dati del tuo database che puoi usare per ripristinare il cluster in caso di perdita o danneggiamento dei dati. Atlas crea automaticamente backup a una cadenza regolare.

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).

Per gestire i backup, devi avere accesso come Organization Owner o Project Owner in Atlas.

Crea backup on-demand

Per creare un backup immediato, esegui:

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

Nel comando precedente, --desc è un flag obbligatorio che descrive lo snapshot.

Elenca i backup disponibili

Per elencare tutti i backup di un cluster, esegui:

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

Descrivi le configurazioni di backup

Per visualizzare le impostazioni di backup di un cluster, esegui:

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

Ripristina dai backup

Per ripristinare i dati da un backup, esegui:

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

Il flag --snapshotId specifica quale backup ripristinare. Il flag --targetClusterName specifica il nome del cluster in cui verranno ripristinati i dati — per esempio:

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

Elimina i backup

Per eliminare un backup, esegui:

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

Conclusione

In questo articolo ti ho illustrato la struttura dei comandi CLI, la creazione dei deployment, la gestione di progetti e cluster, la configurazione di utenti e ruoli e la gestione dei backup. Puoi automatizzare queste operazioni combinandole in script, il che rende più semplice gestire ambienti multipli e integrare la gestione del database nel tuo flusso di lavoro di sviluppo.