MongoDB Atlas CLI: gerencie bancos de dados pelo terminal

MongoDB Atlas é um serviço de banco de dados na nuvem que permite implantar, gerenciar e escalar bancos de dados MongoDB. Você pode administrar o Atlas pela Atlas UI, uma interface web, ou pelo Atlas CLI, uma ferramenta de linha de comando que permite executar as mesmas tarefas via comandos.

O MongoDB Atlas CLI é uma alternativa mais ágil à Atlas UI. Com ele, você executa e automatiza tarefas de gerenciamento do banco diretamente do terminal.

Neste artigo, vou mostrar como usar o Atlas CLI para gerenciar seus bancos de dados.

Pré-requisitos

Antes de começar, confirme se você tem:

• Uma conta no MongoDB Atlas.
• Familiaridade básica com linha de comando.
• Requisitos de instalação do Atlas CLI para o seu sistema operacional.

Estrutura dos comandos do CLI

O MongoDB Atlas CLI segue uma estrutura consistente de comandos:

atlas [command] [subcommand] [flags]

Ao executar um comando sem subcomandos ou flags, o CLI exibe informações de ajuda que incluem:

• Uso: como usar o comando.
• Apelidos: nomes alternativos para o comando.
• Comandos disponíveis: subcomandos que você pode executar.
• Flags: opções específicas do comando.
• Flags globais: opções disponíveis em todos os comandos do CLI.

Por exemplo, se você executar:

atlas clusters

Você verá uma resposta semelhante a esta:

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.

Nomes de comandos, argumentos e flags no Atlas CLI diferenciam maiúsculas e minúsculas. Use exatamente a capitalização mostrada nos exemplos — por exemplo, --orgId e não --orgID.

Criar uma implantação do MongoDB

Uma implantação é uma instância em execução do MongoDB que armazena e serve seus dados. Cada implantação inclui servidores de banco de dados, armazenamento, rede e backups automatizados. O MongoDB Atlas cuida da infraestrutura, para você focar no uso do banco, não na manutenção de servidores.

Para criar uma implantação MongoDB, instale ou atualize o Atlas CLI e execute o comando:

atlas setup

O comando atlas setup conduz você por um processo interativo. Ele solicita escolhas de configuração, cria um projeto, provisiona um cluster e define configurações básicas de segurança.

Autenticar em uma implantação existente

Se você já tem uma implantação do MongoDB Atlas e quer gerenciá-la pelo CLI, é preciso se autenticar. Para fazer login, execute:

atlas auth login

Esse comando pede que você selecione o tipo de autenticação e fornece um código de verificação único. Copie o código e cole no navegador quando solicitado. Por exemplo:

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.

Após autenticar, você seleciona uma organização padrão e o formato de saída. O CLI armazena sua sessão, mas ela expira periodicamente. Quando aparecer o erro "session expired", execute atlas auth login novamente.

Gerenciar perfis para múltiplos ambientes

Perfis permitem gerenciar vários ambientes do MongoDB Atlas na mesma instalação do CLI. Cada perfil guarda as configurações de conexão de um ambiente diferente, como desenvolvimento, homologação (staging) ou produção.

Com perfis, você alterna rapidamente entre ambientes sem precisar se autenticar de novo ou alterar arquivos de configuração. Isso é útil quando você mantém projetos ou organizações separados no Atlas para diferentes etapas do seu fluxo de desenvolvimento.

Uma prática comum é criar projetos separados no Atlas para cada ambiente e usar perfis para gerenciá-los — por exemplo:

• Perfil de desenvolvimento: aponta para seu projeto de dev com um cluster M0 pequeno para testes.
• Perfil de staging: aponta para seu projeto de homologação que espelha a configuração de produção.
• Perfil de produção: aponta para seu projeto de produção com clusters de nível produtivo.

Criar perfis para diferentes ambientes

Quando você executa o atlas auth login pela primeira vez, o CLI cria um perfil padrão. Para criar perfis adicionais para outros ambientes, use a flag --profile:

atlas auth login --profile dev

Isso cria um perfil chamado "dev" e guia você pelo processo de autenticação. Repita para cada ambiente:

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

Cada perfil armazena suas próprias credenciais de autenticação, projeto padrão e configurações de organização.

Listar perfis disponíveis

Para ver todos os perfis configurados, execute:

atlas config list

Isso mostra todos os nomes de perfis que você criou.

Ver detalhes de um perfil

Para ver a configuração de um perfil específico, execute:

atlas config describe <profileName>

Por exemplo:

atlas config describe dev

Isso exibe as configurações do perfil, incluindo os IDs da organização e do projeto padrão.

Alternar entre perfis

Para usar um perfil específico em um comando, adicione a flag --profile:

atlas clusters list --profile production

Isso lista os clusters usando as credenciais e configurações do perfil de produção.

Você também pode definir um perfil padrão para não precisar especificá-lo em todo comando:

atlas config set --profile staging

Depois de definir um padrão, todos os comandos usam esse perfil, a menos que você o substitua com a flag --profile.

Atualizar configurações do perfil

Para modificar a configuração de um perfil, execute:

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

Por exemplo, para definir um projeto padrão para o perfil dev:

atlas config set project_id 5f8e8d9a1b2c3d4e5f6g7h8i --profile dev

Renomear perfis

Para renomear um perfil, execute:

atlas config rename <oldName> <newName>

Por exemplo:

atlas config rename dev development

Gerenciar projetos

Projetos no MongoDB Atlas organizam seus clusters, usuários e configurações. Pense no projeto como um contêiner que agrupa recursos de banco de dados relacionados.

Cada projeto pode conter vários clusters e tem seu próprio conjunto de usuários e controles de acesso. Essa separação é útil quando você tem aplicações, ambientes ou times diferentes que precisam de recursos de banco isolados.

Criar projetos

Para criar um novo projeto, execute:

atlas projects create <projectName> [options]

Use um nome descritivo que indique o propósito do projeto, como "ecommerce-transactions" ou "mobile-app-staging".

[options] inclui flags que determinam como e onde o projeto será criado. Por exemplo, você pode especificar a organização onde criar o projeto:

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

A flag --orgId indica em qual organização o projeto será criado. Ela é obrigatória, a menos que você já tenha definido uma organização padrão. Você pode executar atlas organizations list para obter a lista das suas organizações e seus Id.

Em todos os exemplos, substitua placeholders como <projectId>, <clusterName> e <username> pelos nomes e identificadores reais do seu projeto, cluster ou usuário.

Atualizar projetos

Para atualizar as configurações de um projeto, use:

atlas projects update <projectId> [options]

Por exemplo, você pode usar a flag --name para mudar o nome do projeto:

atlas projects update <projectId> --name newProjectName

Listar projetos

Para listar todos os projetos na sua organização, use:

atlas projects list [options]

O comando acima usa a flag --orgId como opção para especificar de qual organização listar os projetos:

atlas projects list --orgId <organizationId>

Você também pode controlar o formato de saída, como exibir os resultados em JSON:

atlas projects list --output json

Excluir projetos

Você pode excluir um projeto usando um comando do Atlas CLI.

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

Não é possível excluir um projeto que ainda contenha clusters ativos. Então, antes de excluir um projeto, exclua todos os clusters dentro dele.

Gerenciar clusters

Clusters são grupos de servidores MongoDB que armazenam seus dados. O Atlas gerencia a infraestrutura, a replicação e o backup dos seus clusters.

Criar clusters

Para criar um novo cluster, execute:

atlas clusters create <clusterName> [options]

[options] inclui flags que especificam a configuração do cluster. Por exemplo, você pode definir o provedor de nuvem, a região e a camada (tier) de preços do MongoDB:

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

Neste comando, a flag --provider define o provedor de nuvem, como AWS, GCP ou Azure. A flag --region define a região onde o cluster será implantado. A flag --tier define o tamanho do cluster.

Se você não definiu um projeto padrão, inclua a flag --projectId:

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

Descrever clusters

Para ver detalhes de um cluster específico, execute:

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

Esse comando mostra a configuração do cluster, tamanho, região e strings de conexão.

Listar clusters

Para listar todos os clusters no seu projeto, execute:

atlas clusters list --projectId <projectId>

A flag --projectId é obrigatória, a menos que você já tenha definido um projeto padrão com:

atlas config set project_id <projectId>

Pausar clusters

Você pode pausar temporariamente um cluster sem excluí-lo. Isso interrompe as operações do cluster, mas preserva seus dados e configurações:

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

Excluir clusters

Para excluir um cluster permanentemente, execute:

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

Depois de criar seu cluster, você deve configurar a segurança de rede antes de se conectar a ele.

Gerenciar a configuração da lista de acesso por IP

Uma lista de acesso por IP controla quais endereços IP podem se conectar aos seus clusters do MongoDB Atlas. Cada projeto pode ter até 200 entradas. Você pode adicionar IPs individuais, faixas em notação CIDR ou IDs de security group da AWS. Uma faixa em notação CIDR define um bloco de IPs usando um IP base e um prefixo — por exemplo, 192.168.0.0/24. Um ID de security group da AWS permite acesso a partir de todos os recursos dentro daquele grupo de segurança.

Para gerenciar listas de acesso por IP, você deve ter acesso como Project Owner no projeto.

Adicionar endereços IP à lista de acesso

Para adicionar seu IP atual à lista de acesso, execute:

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

A flag --currentIp adiciona automaticamente o IP da máquina que executa o comando. Isso é útil para ter acesso rápido a partir da sua máquina de desenvolvimento.

Para adicionar um IP específico, execute:

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

<ipAddress> é o IP ao qual você quer conceder acesso. Por exemplo:

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

A flag --comment adiciona uma descrição para ajudar a identificar a entrada depois.

Para adicionar uma faixa de IPs usando notação CIDR, execute:

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

Por exemplo:

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

Criar entradas temporárias na lista de acesso

Para adicionar um IP que expira automaticamente após um período, use a flag --deleteAfter. Você pode definir prazos de até sete dias no futuro:

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

A flag --deleteAfter aceita uma data no formato ISO-8601. Por exemplo:

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

O MongoDB Atlas remove a entrada automaticamente na data e hora especificadas.

Listar entradas da lista de acesso

Para ver todas as entradas da lista de acesso por IP no seu projeto, execute:

atlas accessLists list --projectId <projectId>

Para ver detalhes de uma entrada específica, execute:

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

<entry> é o endereço IP, o bloco CIDR ou o ID do security group da AWS que você deseja visualizar.

Excluir entradas da lista de acesso

Para remover um IP da lista de acesso, execute:

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

Gerenciar usuários e papéis

Um papel concede privilégios para executar conjuntos de ações em recursos específicos. Um usuário é uma entidade que recebe um ou mais papéis que determinam o que ele pode acessar no banco.

Para configurar usuários e papéis de banco, você deve ter acesso como Organization Owner, Project Owner ou Project Database Access Admin no MongoDB Atlas.

Gerenciar usuários

Para criar um usuário de banco de dados, execute:

atlas dbusers create [builtInRole] [options]

[builtInRole] é um ou mais papéis nativos para atribuir ao usuário. [options] inclui flags que especificam as credenciais e a configuração do usuário. Por exemplo:

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

A flag --username define o nome de usuário. A --password define a senha. A --role define o papel a ser atribuído. Neste caso, o usuário é myUser e a senha é myPassword.

Para listar todos os usuários do projeto, execute:

atlas dbusers list --projectId <projectId>

Para ver detalhes de um usuário específico, execute:

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

Você também pode atualizar o usuário. Por exemplo, para alterar a senha, execute:

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

Para atualizar os papéis de um usuário, execute:

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

Para excluir um usuário específico, execute:

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

Gerenciar papéis

Há duas categorias de papéis que você pode atribuir a um usuário:

• Papéis nativos (built-in)
• Papéis personalizados

Papéis nativos

Papéis nativos são papéis predefinidos fornecidos pelo MongoDB Atlas. Eles incluem conjuntos de permissões comuns para diferentes usos, como:

• read: concede acesso somente leitura a um banco específico.
• readWrite: permite ler e modificar dados em um banco específico.
• readAnyDatabase: concede acesso somente leitura a todos os bancos, exceto local e config.
• readWriteAnyDatabase: concede acesso de leitura e escrita a todos os bancos.
• dbAdmin: fornece privilégios administrativos para um banco específico, como criar índices ou ver estatísticas.
• dbAdminAnyDatabase: concede privilégios administrativos em todos os bancos.
• clusterAdmin: permite gerenciar todo o cluster, incluindo replicação e sharding.
• userAdminAnyDatabase: permite criar e modificar contas de usuário e papéis em todos os bancos.

Você não pode editar ou excluir papéis nativos. Apenas atribuí-los a usuários. Para atribuir papéis nativos ao criar usuários, especifique o papel com a flag --role:

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

Para atribuir ou alterar o papel de um usuário existente, execute:

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

Veja Built-In Roles and Privileges para mais papéis nativos que você pode atribuir aos usuários.

Papéis personalizados

O MongoDB Atlas permite criar papéis personalizados quando os papéis nativos não atendem às suas necessidades. Um papel personalizado define um conjunto de ações de privilégio específicas que combinam com os requisitos da sua aplicação ou do seu time.

Ao criar um papel personalizado, decida a quais coleções os usuários devem acessar e quais ações nos recursos eles poderão executar — por exemplo, ler, inserir, atualizar ou excluir dados.

Nas definições de privilégio do MongoDB, você deve usar o nome da ação em maiúsculas no comando do CLI, como FIND, e não find. Veja Privilege Actions para conhecer mais ações de privilégio que um usuário pode executar em um recurso.

Você pode gerenciar papéis personalizados pelo Atlas CLI.

Para criar um papel personalizado, execute:

atlas customDbRoles create <roleName> [options]

<roleName> é o nome do papel personalizado que você quer criar. [options] inclui flags que especificam as permissões do papel — por exemplo:

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

No comando acima:

• customAnalyticsRole é o nome do novo papel personalizado. Escolha um nome descritivo que reflita o propósito do papel.
• A flag --privilege especifica quais ações em recursos o papel pode executar.
• O formato é action@database.collection, em que @ separa a ação do recurso.
• FIND é uma ação de privilégio reconhecida pelo MongoDB.
• myDatabase.users é o recurso ao qual o privilégio se aplica — neste caso, a coleção users no banco myDatabase.

Para ver detalhes sobre um papel personalizado, execute:

atlas customDbRoles list --projectId <projectId>

O comando acima mostra todos os papéis personalizados e suas permissões.

Para atualizar um papel personalizado, execute:

atlas customDbRoles update <roleName> [options]

[options] inclui flags que especificam o que atualizar. Por exemplo, para adicionar novos privilégios a um papel existente, execute:

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

O comando acima atualiza o customAnalyticsRole para conceder privilégios adicionais. FIND@myDatabase.analytics permite ler documentos da coleção analytics, e INSERT@myDatabase.logs permite inserir documentos na coleção logs do banco myDatabase.

A flag --projectId especifica a qual projeto do MongoDB Atlas o papel pertence.

Para excluir um papel personalizado, execute:

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

O processo de atribuir um papel personalizado a um usuário é semelhante ao de atribuir um papel nativo. Use a flag --role com os comandos atlas dbusers create ou atlas dbusers update:

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

Depois de criar usuários de banco e atribuir papéis, você já pode se conectar ao seu cluster.

Obter strings de conexão

Uma string de conexão contém as informações de que suas aplicações precisam para se conectar ao cluster do Atlas. A string inclui o hostname do cluster, o banco de autenticação e opções de conexão.

Antes de usar uma string de conexão, confirme que você configurou a lista de acesso por IP e criou ao menos um usuário de banco.

Obter a string de conexão de um cluster

Para recuperar a string de conexão de um cluster, execute:

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

Esse comando retorna a string de conexão SRV do seu cluster.

Formatos de string de conexão

O MongoDB Atlas fornece dois tipos de strings de conexão:

String de conexão padrão (mongodb://): lista explicitamente todos os nós do cluster. Use esse formato quando precisar especificar endereços de servidores individuais.

String de conexão SRV (mongodb+srv://): usa DNS para recuperar as informações do cluster automaticamente. Esse é o formato recomendado, pois se atualiza automaticamente se a configuração do cluster mudar.

Usar a string de conexão

Substitua <username> e <password> na string de conexão pelas credenciais do seu usuário de banco:

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

Por exemplo, se seu usuário for appUser e a senha for securePass123:

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

Você pode usar essa string com os MongoDB Drivers, o MongoDB Shell ou outras ferramentas do MongoDB para se conectar ao cluster.

Gerenciar backups

Backups são cópias dos dados do seu banco que você pode usar para restaurar o cluster se houver perda ou corrupção de dados. O Atlas cria backups automaticamente em um cronograma regular.

Backups contínuos automatizados estão disponíveis apenas para clusters dedicados M10+. Clusters M0 (nível gratuito) não têm recursos de backup. Clusters compartilhados M2/M5 têm backups básicos em nuvem, mas não backup contínuo. Para mais informações, veja [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).

Para gerenciar backups, você deve ter acesso como Organization Owner ou Project Owner no Atlas.

Criar backups sob demanda

Para criar um backup imediato, execute:

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

No comando acima, --desc é uma flag obrigatória que descreve o snapshot.

Listar backups disponíveis

Para listar todos os backups de um cluster, execute:

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

Descrever configurações de backup

Para ver as configurações de backup de um cluster, execute:

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

Restaurar a partir de backups

Para restaurar dados de um backup, execute:

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

A flag --snapshotId especifica qual backup restaurar. A flag --targetClusterName especifica o nome do cluster onde os dados serão restaurados — por exemplo:

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

Excluir backups

Para excluir um backup, execute:

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

Conclusão

Neste artigo, você viu a estrutura dos comandos do CLI, como criar implantações, gerenciar projetos e clusters, configurar usuários e papéis e administrar backups. Você pode automatizar essas operações combinando-as em scripts, o que facilita gerenciar múltiplos ambientes e integrar o gerenciamento de banco de dados ao seu fluxo de desenvolvimento.