MongoDB: Configurando o ambiente e o Mongosh
Última atualização: 2026-08-26
O mongosh é o cliente oficial de linha de comando do MongoDB — é a ferramenta mais direta para interagir com o MongoDB.
Este tutorial foi elaborado para desenvolvedores sem experiência prévia e abrange tudo, desde a instalação local até a conexão com o Atlas, e desde os comandos básicos do mongosh até o seu primeiro teste de ping.
1. O que você vai aprender
- Instalar o MongoDB Community Edition no Windows, macOS ou Linux
- Implemente rapidamente um contêiner do MongoDB usando o Docker
- Criar um cluster gratuito do MongoDB Atlas na nuvem
- Usos básicos do cliente de linha de comando do Mongosh
- Configuração do plugin do VSCode para MongoDB
- Primeiro teste de conexão com o banco de dados (
db.runCommand({ ping: 1 })) - Resolução de problemas comuns de instalação
2. A história real de um engenheiro full-stack
(1) Desafio: Configurar um ambiente MongoDB do zero em um novo computador
Bob acabou de comprar um novo MacBook Pro M3 e quer configurar um ambiente de desenvolvimento do MongoDB em seu computador novinho em folha:
“Quero conectar meu código Node.js ao MongoDB e ter minha primeira operação CRUD funcionando em 30 minutos. Mas eu costumava usar o Windows e agora mudei para um Mac com arquitetura ARM e chip M3 — nenhum dos tutoriais que encontrei funciona.”
Ele tentou três abordagens, todas as quais fracassaram:
| Solução | Problema |
|---|---|
| ❌ brew install mongodb | A arquitetura M3 ARM não possui uma fórmula oficial no homebrew/core |
| ❌ Baixar o instalador .dmg | Mensagem: “Não é possível abrir porque não foi possível verificar o desenvolvedor” |
| ❌ Na página de download do MongoDB | Não foi encontrada nenhuma versão para macOS ARM |
(2) Uma solução utilizando o MongoDB e o Docker
Use o Docker para contornar todos os problemas de compilação local.
# 1. Installation Docker Desktop for Mac (Apple Silicon)
# Download from https://www.docker.com/products/docker-desktop/
# 2. Pull MongoDB image
docker pull mongo:7.0
# 3. Start MongoDB Container(Port Forwarding + Data Volume)
docker run -d \
--name mongodb-dev \
-p 27017:27017 \
-v ~/mongodb-data:/data/db \
mongo:7.0
# 4. Use mongosh to connect
mongosh "mongodb://localhost:27017/admin"
# 5. Test Connection
db.runCommand({ ping: 1 })
# { ok: 1 }
(3) Receita
| Dimensão | Instalação nativa | Instalação no Docker |
|---|---|---|
| Multiplataforma | ❌ Varia de acordo com a plataforma | ✅ Compile uma vez, execute em qualquer lugar |
| Coexistência de várias versões | ❌ Difícil | ✅ Inicialização de vários contêineres |
| Desinstalação completa | ❌ Configuração residual | ✅ Basta excluir o contêiner |
| Consenso da equipe | ⚠️ Depende da versão do sistema operacional | ✅ Versão da imagem fixada |
| Tempo de inicialização | 1–3 minutos | 5–10 segundos |
3. Comparação dos métodos de instalação
Visão geral do conceito: O MongoDB oferece quatro métodos de instalação — contêineres Docker, serviço em nuvem Atlas, instalação nativa (brew/apt/msi) e gerenciadores de pacotes. O método escolhido depende do seu caso de uso: o Docker é recomendado para ambientes de desenvolvimento (multiplataforma, isolado, rápido); o Atlas é recomendado para colaboração em equipe (sem manutenção, implantação global); e a instalação nativa é recomendada para ambientes de produção (melhor desempenho).
Como funciona: Os contêineres do Docker isolam o processo do MongoDB usando namespaces do Linux, e os dados são armazenados na máquina host por meio da montagem de volumes. O serviço em nuvem Atlas implanta automaticamente conjuntos de réplicas na AWS, no Azure e no GCP, oferecendo backups e monitoramento automáticos. Uma instalação nativa executa o processo mongod diretamente, oferecendo desempenho ideal, mas exigindo gerenciamento manual.
graph TB
A[MongoDB Installation Methods] --> B[Native Installation<br/>brew/apt/dmg/exe]
A --> C[Docker Container<br/>Recommended for Rapid Development]
A --> D[Atlas Cloud Services<br/>Zero Local Configuration]
A --> E[Package Manager<br/>Homebrew/Chocolatey]
style C fill:#d4edda
style D fill:#d4edda
| Método | Aplicabilidade | Dificuldade | Cenários recomendados | Desempenho |
|---|---|---|---|---|
| Docker | Multiplataforma | ⭐ | ⭐⭐⭐ Desenvolvimento rápido | ⚠️ Ligeira sobrecarga |
| Atlas | Serviços em nuvem | ⭐⭐ | ⭐⭐⭐ Colaboração em equipe | ✅ Otimização gerenciada |
| brew/apt Native | Plataforma única | ⭐⭐ | ⭐⭐ Ambiente de produção | ✅ Melhor |
| .dmg/.exe oficial | Gráfico | ⭐⭐⭐ | ⭐ Uso único | ✅ Melhor |
(1) Quatro métodos de instalação
graph TB
A[MongoDB Installation Methods] --> B[Native Installation<br/>brew/apt/dmg/exe]
A --> C[Docker Container<br/>Recommended for Rapid Development]
A --> D[Atlas Cloud Services<br/>Zero Local Configuration]
A --> E[Package Manager<br/>Homebrew/Chocolatey]
style C fill:#d4edda
style D fill:#d4edda
| Método | Aplicabilidade | Dificuldade | Cenários recomendados |
|---|---|---|---|
| Docker | Multiplataforma | ⭐ | ⭐⭐⭐ Desenvolvimento rápido |
| Atlas | Serviços em nuvem | ⭐⭐ | ⭐⭐⭐ Colaboração em equipe |
| brew/apt Native | Plataforma única | ⭐⭐ | ⭐⭐ Ambiente de produção |
| Arquivo oficial .dmg/.exe | Gráfico | ⭐⭐⭐ | ⭐ Uso único |
(2) Escolhendo uma versão do MongoDB
Explicação do conceito: O MongoDB segue uma estratégia de lançamento LTS (Suporte de Longo Prazo), em que cada versão principal recebe suporte por um período de 3 a 5 anos. Ao escolher uma versão, você deve dar prioridade às versões LTS em vez da versão mais recente — as versões LTS foram exaustivamente testadas e contam com uma garantia de longo prazo de atualizações de segurança.
| Versão | Data de lançamento | Status | Casos de uso recomendados |
|---|---|---|---|
| MongoDB 8.0 | 2024 | Última versão candidata LTS | Novo projeto |
| MongoDB 7.0 | 2023 | LTS atual | Utilizado neste tutorial |
| MongoDB 6.0 | 2022 | LTS anterior | Prioridade à compatibilidade |
| MongoDB 5.0 | 2021 | Perto do fim da vida útil (EOL) | Não recomendado |
▶ Exemplo 1: Comando para verificar a versão
# Inspection mongosh Version
mongosh --version
# mongosh 2.1.0
# Inspection mongod Server Version
mongod --version
# db version v7.0.5
# Through mongosh Check the server version
mongosh "mongodb://localhost:27017" --eval "db.version()"
# 7.0.5
4. Instalação via Docker (recomendado)
Visão geral do conceito: O Docker é a forma mais recomendada de configurar um ambiente de desenvolvimento do MongoDB. O Docker empacota o MongoDB e suas dependências em um contêiner, isolando-os do sistema de arquivos e da rede da máquina hospedeira, permitindo assim que o código seja “compilado uma vez e executado em qualquer lugar”. Em comparação com uma instalação nativa, o Docker oferece as seguintes vantagens: consistência entre plataformas, suporte a várias versões, desinstalação limpa e inicialização extremamente rápida (5 a 10 segundos).
Como funciona: Um contêiner Docker é, essencialmente, um ambiente de execução isolado para processos do Linux. O contêiner do MongoDB usa a imagem oficial (mongo:7.0), que executa o processo mongod internamente. O mapeamento de portas (-p 27017:27017) expõe as portas do contêiner à máquina host, e a montagem de volumes (-v ~/mongodb-data:/data/db) mantém os dados na máquina host — garantindo que os dados não sejam perdidos quando o contêiner for excluído.
graph LR
A[Host Machine] --> B[Docker Engine]
B --> C[mongodb-dev Container]
C --> D[mongod Process<br/>Port 27017]
A --> E[~/mongodb-data<br/>Mounting Data Volumes]
E --> D
A --> F[mongosh Client<br/>Connect localhost:27017]
F --> D
style C fill:#d4edda
(1) 4.1 Pré-requisitos
# Installation Docker Desktop
# macOS: Download https://www.docker.com/products/docker-desktop/
# Windows: Download + Enable WSL 2 Backend
# Linux: sudo apt install docker.io docker-compose
# Verification Docker Installation
docker --version
# Docker version 24.0.7, build afdd53b
(2) 4.2 Baixar a imagem do MongoDB
# Get the latest stable version
docker pull mongo:7.0
# Pull a specific version(Recommendations)
docker pull mongo:7.0.5
# Pull an image with authentication(Recommended Production Environments)
docker pull mongo:7.0-auth
(3) 4.3 Iniciando o contêiner do MongoDB
# Standalone Development Mode(Not certified)
docker run -d \
--name mongodb-dev \
-p 27017:27017 \
-v ~/mongodb-data:/data/db \
--restart unless-stopped \
mongo:7.0
# Certified Production Model
docker run -d \
--name mongodb-prod \
-p 27017:27017 \
-v ~/mongodb-data:/data/db \
-e MONGO_INITDB_ROOT_USERNAME=admin \
-e MONGO_INITDB_ROOT_PASSWORD=YourSecurePass123 \
--restart unless-stopped \
mongo:7.0
# Verify the container's running status
docker ps
# CONTAINER ID IMAGE STATUS PORTS
# a1b2c3d4e5f6 mongo:7.0 Up 2 minutes 0.0.0.0:27017->27017/tcp
(4) 4.4 Verificação da conexão
# Use mongosh to connect
mongosh "mongodb://localhost:27017"
# In mongosh
db.runCommand({ ping: 1 })
# { ok: 1 }
(5) 4.5 Comandos comuns do Docker
# View container logs
docker logs mongodb-dev
# Stop the container
docker stop mongodb-dev
# Start the container
docker start mongodb-dev
# Restart the container
docker restart mongodb-dev
# Enter the container
docker exec -it mongodb-dev mongosh
# Delete Container(Data Volume Retention)
docker rm mongodb-dev
# Delete Containers and Data Volumes(Use with caution! Data Loss)
docker rm -v mongodb-dev
5. Instalação nativa no macOS
(1) 5.1 Instalando o Homebrew
# Add MongoDB Official Tap
brew tap mongodb/brew
# Install the latest stable version
brew install mongodb-community@7.0
# Start MongoDB Services
brew services start mongodb-community@7.0
# Verification
mongosh --version
mongosh "mongodb://localhost:27017" --eval "db.runCommand({ ping: 1 })"
(2) 5.2 Inicialização manual (sem usar brew services)
# Start mongod(Specify the data directory and log files)
mongod --dbpath ~/mongodb-data --logpath ~/mongodb.log --fork
# Verification
ps aux | grep mongod
# mongodb 12345 ... mongod --dbpath /Users/.../mongodb-data
▶ Exemplo 2: Processo completo de instalação do macOS
# === 1. Installation Xcode Command Line Tools ===
xcode-select --install
# === 2. Installation Homebrew(If not yet) ===
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# === 3. Add MongoDB Tap ===
brew tap mongodb/brew
# === 4. Installation MongoDB ===
brew install mongodb-community@7.0
# === 5. Start the service ===
brew services start mongodb-community@7.0
# === 6. Connection Test ===
mongosh "mongodb://localhost:27017"
# === 7. The First Command ===
db.runCommand({ ping: 1 })
# { ok: 1 }
6. Instalação do Linux
Ubuntu / Debian
# 1. Import MongoDB GPG key
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
# 2. Add MongoDB repository
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
# 3. Update Package Index
sudo apt update
# 4. Installation MongoDB
sudo apt install -y mongodb-org
# 5. Start the service
sudo systemctl start mongod
sudo systemctl enable mongod
# 6. Verification
sudo systemctl status mongod
mongosh --eval "db.runCommand({ ping: 1 })"
CentOS / RHEL / Fedora
# 1. Add MongoDB Yum repository
sudo tee /etc/yum.repos.d/mongodb-org-7.0.repo << 'EOF'
[mongodb-org-7.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/7.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-7.0.asc
EOF
# 2. Installation
sudo yum install -y mongodb-org
# 3. Start
sudo systemctl start mongod
sudo systemctl enable mongod
7. Instalação no Windows
(1) 7.1 Instalador MSI (gráfico)
1. Visit https://www.mongodb.com/try/download/community
2. Select "Windows" + "msi" + Version 7.0
3. Download MongoDB-windows-x86_64-7.0.x-signed.msi
4. Double-click to install:
✅ Complete Installation Type
✅ Install MongoDB as a Service
✅ Install MongoDB Compass(GUI Tools)
5. After installation is complete,MongoDB Automatic Action Windows Service Start
(2) 7.2 Instalando o Chocolatey
# 1. Installation Chocolatey(If not yet)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
# 2. Installation MongoDB
choco install mongodb
# 3. Start
mongod --dbpath C:\data\db
# 4. Connect
mongosh "mongodb://localhost:27017"
▶ Exemplo 3: Processo completo de instalação do Windows
# === 1. Create a data directory ===
mkdir C:\data\db
# === 2. Start MongoDB ===
mongod --dbpath C:\data\db
# === 3. Connecting Another Device ===
mongosh "mongodb://localhost:27017"
# === 4. Test ===
db.runCommand({ ping: 1 })
# { ok: 1 }
8. Configurando o serviço em nuvem MongoDB Atlas
Visão geral do conceito: O MongoDB Atlas é um serviço oficial de banco de dados em nuvem totalmente gerenciado, disponível nas três principais plataformas de nuvem: AWS, Azure e GCP. O Atlas é a melhor opção para colaboração em equipe e cenários de implantação internacional — não requer manutenção, oferece backups automáticos, suporta implantação global e inclui monitoramento integrado. O Atlas oferece um plano gratuito permanente de 512 MB (M0 Sandbox), o que é suficiente para aprendizado e pequenos projetos.
Como funciona: O Atlas implanta automaticamente um conjunto de réplicas de três nós na plataforma em nuvem. O nó primário lida com as solicitações de gravação, enquanto os dois nós secundários fornecem redundância de leitura e failover automático. Os usuários gerenciam o cluster, configuram listas de permissões de rede e criam usuários do banco de dados por meio do console web do Atlas. As cadeias de conexão suportam o formato mongodb+srv://, e os nós do cluster são descobertos automaticamente por meio de registros SRV do DNS.
graph LR
A[Your App] --> B[Atlas Global Clusters<br/>3 Node Replica Set]
B --> C[Primary<br/>Reading and Writing]
B --> D[Secondary 1<br/>Read Redundancy]
B --> E[Secondary 2<br/>Read Redundancy]
B --> F[Automatic Backup<br/>PITR]
B --> G[Monitoring Alerts<br/>Performance Recommendations]
style B fill:#d4edda
(1) 8.1 Criação de um cluster livre
1. Visit https://www.mongodb.com/cloud/atlas/register
2. Sign Up(Google / GitHub OAuth Fastest)
3. Select "Build a Cluster" → "Shared" → "M0 Sandbox"(Free)
4. Cloud Provider:AWS(Recommendations)
5. Region:
- Users in the Middle East:me-central-1 (UAE)
- Users in Brazil:sa-east-1 (São Paulo)
- Japanese users:ap-northeast-1 (Tokyo)
6. Cluster Name:Cluster0
7. Click "Create Cluster"(Waiting 1-3 minutes)
(2) 8.2 Configuração das permissões de acesso
Steps 1:Create a Database User
- Database Access → Add New Database User
- Username: alice
- Password: YourSecurePass123
- Database User Privileges: Read and write to any database
Steps 2:Configure the Network Whitelist
- Network Access → Add IP Address
- Select "Allow Access from Anywhere"(0.0.0.0/0)
⚠️ For development use only,The production environment should be limited to application servers. IP
(3) 8.3 Recuperação da string de conexão
1. Database → Connect → Connect your application
2. Driver: Node.js
3. Version: 5.5 or later
4. Concatenate Strings:
mongodb+srv://alice:YourSecurePass123@cluster0.mongodb.net/mydb?retryWrites=true&w=majority
▶ Exemplo 4: Conectando-se a um cluster do Atlas
# Use mongosh to connect Atlas
mongosh "mongodb+srv://cluster0.mongodb.net/mydb" --username alice
# Password: ********
# In mongosh
db.runCommand({ ping: 1 })
# { ok: 1 }
# Insert the first document
db.users.insertOne({ name: "Alice", email: "alice@example.com" })
# Search
db.users.find()
# { _id: ObjectId('...'), name: 'Alice', email: 'alice@example.com' }
9. O cliente de linha de comando mongosh
Visão geral do conceito: o mongosh é o cliente oficial de linha de comando do MongoDB (que substituiu o antigo shell mongo a partir de 2020). Ele é executado no Node.js e oferece suporte à sintaxe moderna do JavaScript, realce de sintaxe, autocompletar e rastreamento de pilha de erros. O mongosh é a ferramenta mais direta para interagir com o MongoDB — todas as operações no banco de dados podem ser realizadas usando o mongosh.
Como funciona: o mongosh se comunica com o servidor mongod por meio do MongoDB Wire Protocol. Por padrão, ele se conecta à porta 27017 na máquina local, mas também suporta cadeias de conexão do Atlas e conexões criptografadas por TLS. O mongosh inclui o objeto db (o banco de dados atual) e métodos globais (show dbs, use, etc.); todas as operações são executadas usando a sintaxe do JavaScript.
graph LR
A[mongosh Client] --> B[Wire Protocol]
B --> C[mongod Server-side]
C --> D[WiredTiger Engine]
A --> A1[JavaScript Runtime]
A --> A2[Auto-Complete]
A --> A3[Syntax Highlighting]
style A fill:#cce5ff
| Categoria do comando | Comandos comuns | Descrição |
|---|---|---|
| Banco de dados | show dbs / use db / db.dropDatabase() |
Visualizar, Alternar, Excluir |
| Coleção | show collections / db.createCollection() / db.col.drop() |
Criar |
| Documento | insertOne/find/updateOne/deleteOne |
Operações CRUD |
| Ajuda | help / db.help() / db.col.help() |
Documentação integrada |
(1) Inicie o mongosh
# Connect to the default local port
mongosh
# Connect to a specified host and port
mongosh "mongodb://localhost:27017"
# Connect Atlas
mongosh "mongodb+srv://cluster0.mongodb.net/mydb" --username alice
# Connect and execute a single command
mongosh "mongodb://localhost:27017" --eval "db.runCommand({ ping: 1 })"
# Enable verbose Pattern(View the time taken by each command)
mongosh --verbose
(2) Comandos básicos do Mongosh
// === Database Operations ===
show dbs // List all databases
use shopdb // Switch to shopdb Database(If it doesn't exist, create it implicitly)
db // Display the current database
db.dropDatabase() // Delete the current database
// === Set Operations ===
show collections // List all collections in the current database
db.createCollection("products") // Explicitly Creating Sets
db.products.drop() // Delete Set
// === Document Operations ===
db.products.insertOne({ sku: "PHONE-001", price: 599.99 })
db.products.find() // Search All Documents
db.products.find().pretty() // Formatted Output
db.products.countDocuments() // Count the number of documents
// === Help Command ===
help // mongosh Built-in Help
db.help() // Database Command Help
db.products.help() // Set Operations Help
(3) Atalhos de teclado do Mongosh
| Tecla de atalho | Função |
|---|---|
↑ / ↓ |
Exibir histórico de comandos |
Tab |
Preenchimento automático |
Ctrl + A |
Ir para o topo |
Ctrl + E |
Pular para o final da linha |
Ctrl + U |
Excluir linha inteira |
Ctrl + L Limpar tela |
|
Ctrl + C |
Cancelar o comando atual |
Ctrl + D / exit |
Sair do mongosh |
▶ Exemplo 5: arquivo de script do mongosh
# === Writing Scripts(setup-mongosh.js) ===
cat > setup-mongosh.js << 'EOF'
// Switch to shopdb
use shopdb;
// Create a User Set
db.users.insertMany([
{ name: "Alice", email: "alice@example.com", age: 28 },
{ name: "Bob", email: "bob@example.com", age: 32 },
{ name: "Charlie", email: "charlie@example.com", age: 25 }
]);
// Create a Product Collection
db.products.insertMany([
{ sku: "PHONE-001", title: "Phone X", price: 599.99, stock: 50 },
{ sku: "LAPTOP-001", title: "Laptop Y", price: 1299.99, stock: 20 }
]);
// Search All Users
print("Users:");
db.users.find().forEach(printjson);
// Search All Products
print("Products:");
db.products.find().forEach(printjson);
EOF
# === Run the script ===
mongosh "mongodb://localhost:27017" setup-mongosh.js
10. Plug-in do VSCode para MongoDB
(1) 10.1 Instalação de plug-ins
1. Open VSCode
2. Extensions (Ctrl+Shift+X)
3. Search "MongoDB for VS Code"
4. Click Install(Official Plug-in,provided by MongoDB Inc.)
(2) 10.2 Conexão com o banco de dados
1. Click the sidebar MongoDB Icon
2. Click "Add Connection"
3. Enter the connection string:
- Local:mongodb://localhost:27017
- Atlas:mongodb+srv://cluster0.mongodb.net/mydb
4. Enter your username and password
5. Select a Database,Browse Collections
(3) 10.3 Operações comuns
- Right-Click Menu → "View Documents":Browsing Data
- Right-Click Menu → "Insert Document":Insert Document
- Right-click the document → "Edit Document":Edit
- Right-click the document → "Delete Document":Delete
- Top Toolbar → "Playgrounds":Run mongosh Screenplay
▶ Exemplo 6: Executando consultas nos Playgrounds do VSCode
// VSCode MongoDB Playground
use('shopdb');
db.users.aggregate([
{ $group: { _id: '$age', count: { $sum: 1 } } },
{ $sort: { _id: 1 } }
]);
11. O primeiro teste de ping
Explicação do conceito: db.runCommand({ ping: 1 }) é o comando “heartbeat” do MongoDB, usado para verificar se a conexão entre o cliente e o servidor está funcionando corretamente. Um teste de ping é o primeiro passo para estabelecer uma conexão com o MongoDB — antes de escrever qualquer lógica de negócios, você deve primeiro usar um ping para confirmar se a conexão foi bem-sucedida. Esse é um princípio fundamental da depuração de bancos de dados.
Como funciona: O comando ping envia um ping ao servidor por meio do MongoDB Wire Protocol. O servidor retorna { ok: 1 } para indicar que a conexão foi bem-sucedida. O tempo de resposta do ping é igual ao atraso de ida e volta da rede mais o tempo de processamento do servidor, e pode ser usado para monitorar a qualidade da rede. No Node.js, o comando ping é usado para verificações de integridade de endpoints (/healthz) e testes de pré-conexão em CI/CD.
sequenceDiagram
participant App as Client
participant Mongo as MongoDB
App->>Mongo: db.runCommand({ ping: 1 })
Mongo-->>App: { ok: 1 }
Note over App,Mongo: Response Time = Network Latency
App->>Mongo: db.runCommand({ ping: 1 })
Mongo-->>App: { ok: 1, operationTime: ... }
| Finalidade do ping | Descrição |
|---|---|
| Verificação da conexão | Confirme a disponibilidade do serviço após a primeira conexão |
| Monitoramento de latência | Medir o tempo de ida e volta da rede |
| Verificação de integridade | /healthz Verificação periódica do terminal |
| Verificações pré-implantação de CI/CD | Verificar a disponibilidade do banco de dados antes da implantação |
(1) 11.1 Por que o ping é importante?
db.runCommand({ ping: 1 }) é o comando “heartbeat” do MongoDB:
- ✅ Verifique se a conexão com o banco de dados foi bem-sucedida
- ✅ Medir o tempo de resposta (monitorar a latência da rede)
- ✅ Para pontos finais de verificação de integridade (
/healthz) - ✅ Para testes de pré-conexão em CI/CD
(2) 11.2 Execução no Mongosh
// In mongosh
db.runCommand({ ping: 1 });
// Output:
// { ok: 1 }
// Timestamped ping
const start = Date.now();
const result = db.runCommand({ ping: 1 });
const duration = Date.now() - start;
print(`Ping successful in ${duration}ms`);
printjson(result);
(3) 11.3 Testando conexões no Node.js
// ping-test.js
const { MongoClient } = require('mongodb');
async function testConnection() {
const client = new MongoClient('mongodb://localhost:27017');
try {
const start = Date.now();
await client.connect();
const result = await client.db('admin').command({ ping: 1 });
const duration = Date.now() - start;
console.log(`✅ Connected in ${duration}ms`);
console.log('Ping result:', result);
if (result.ok === 1) {
console.log('🎉 MongoDB connection is healthy!');
} else {
console.error('❌ Ping failed:', result);
}
} catch (err) {
console.error('❌ Connection error:', err.message);
process.exit(1);
} finally {
await client.close();
}
}
testConnection();
▶ Exemplo 7: Script completo de verificação de integridade
// health-check.js
const { MongoClient } = require('mongodb');
const mongoose = require('mongoose');
async function healthCheck() {
const results = {
native_driver: false,
mongoose: false,
timestamp: new Date().toISOString()
};
// 1. Testing Native Drivers
try {
const client = new MongoClient('mongodb://localhost:27017');
await client.connect();
const ping = await client.db('admin').command({ ping: 1 });
results.native_driver = ping.ok === 1;
await client.close();
console.log('✅ Native driver ping:', ping.ok === 1);
} catch (err) {
console.error('❌ Native driver ping failed:', err.message);
}
// 2. Test mongoose
try {
await mongoose.connect('mongodb://localhost:27017/test');
const adminDb = mongoose.connection.db.admin();
const ping = await adminDb.command({ ping: 1 });
results.mongoose = ping.ok === 1;
await mongoose.disconnect();
console.log('✅ Mongoose ping:', ping.ok === 1);
} catch (err) {
console.error('❌ Mongoose ping failed:', err.message);
}
console.log('\nHealth check results:', JSON.stringify(results, null, 2));
return results;
}
healthCheck();
12. Resolução de problemas comuns de instalação
(1) 12.1 Problemas relacionados a falhas de conexão
| Mensagem de erro | Causa | Solução |
|---|---|---|
ECONNREFUSED 127.0.0.1:27017 |
mongod não está em execução | brew services start mongodb-community@7.0 |
MongoServerSelectionError: connection timeout |
Problema de rede ou lista de permissões do Atlas não configurada | Adicionar IP no Acesso à Rede do Atlas |
Authentication failed |
Nome de usuário ou senha incorretos | Redefinir senha ou criar uma nova conta |
getaddrinfo ENOTFOUND cluster0.mongodb.net |
Falha na resolução de DNS | Verifique sua conexão de rede ou use o endereço IP |
Operation timed out |
Bloqueado pelo firewall | Abrir a porta 27017 |
(2) 12.2 Falha na inicialização do contêiner do Docker
# Check the container logs to find the cause
docker logs mongodb-dev
# Common Mistakes:Port is in use
# Error: bind: address already in use
# Solutions 1:Processes that are occupying ports
lsof -i :27017
kill -9 <PID>
# Solutions 2:Switch to a different port
docker run -d --name mongodb-dev -p 27018:27017 mongo:7.0
mongosh "mongodb://localhost:27018"
(3) 12.3 Espaço em disco insuficiente
# Check Disk Space
df -h
# MongoDB Default disk space used by the data directory
du -sh ~/mongodb-data
# Cleanup Plan:Settings oplogSize Restrictions(Raid Mode)
mongod --oplogSize 1024
# or use WiredTiger Compression(Enabled by default)
mongod --wiredTigerCollectionConfig blockCompressor=zstd
▶ Exemplo 8: O processo completo de resolução de problemas
# === Steps 1:Inspection mongod Is it running? ===
ps aux | grep mongod | grep -v grep
# === Steps 2:Check Port Listening ===
lsof -iTCP:27017 -sTCP:LISTEN
# === Steps 3:Try connecting ===
mongosh "mongodb://localhost:27017"
# === Steps 4:View mongod Log ===
tail -50 /usr/local/var/log/mongodb/mongo.log
# === Steps 5:Restart the service ===
brew services restart mongodb-community@7.0
# === Steps 6:Test Again ===
mongosh "mongodb://localhost:27017" --eval "db.runCommand({ ping: 1 })"
❓ Perguntas Frequentes
P: O que é melhor: o Docker ou uma instalação nativa? R: O Docker é recomendado para desenvolvimento local (multiplataforma, isolado, rápido). A instalação nativa é recomendada para ambientes de produção (melhor desempenho, mais fácil de depurar). Este tutorial utiliza o Docker para fins de demonstração, para que todos os leitores possam acompanhá-lo facilmente.
P: Os clusters gratuitos do Atlas têm prazo de validade? R: Não. O M0 Sandbox (512 MB) no MongoDB Atlas é gratuito para sempre, sem data de validade. No entanto, você deve fazer login uma vez a cada 90 dias para evitar que ele seja recuperado.
P: Qual é a diferença entre o mongosh e o antigo Mongo shell? R: O mongosh é o sucessor do Mongo shell (recomendado para uso desde 2020). O mongosh é baseado no Node.js e oferece suporte à sintaxe moderna do JavaScript, realce de sintaxe e pilhas de erros, o que o torna mais adequado para o desenvolvimento.
P: Por que não há uma versão 8.0 LTS após o MongoDB 7.0? R: O MongoDB 8.0 foi lançado em 2024 e, atualmente, está se tornando um candidato a versão LTS. Este tutorial se baseia na versão estável 7.0 LTS, que abrange a grande maioria dos cenários de produção.
P: É possível implantar o MongoDB usando o Docker em um ambiente de produção? R: Sim, mas lembre-se do seguinte: (1) Use uma rede do host ou um IP estático; (2) Os volumes de dados devem ser montados na máquina física; (3) Configure os limites de recursos (
--memory --cpus); (4) Recomenda-se o uso do Kubernetes + StatefulSet para ambientes de produção.
P: O que significa
+srvna string de conexão? R:mongodb+srv://é um formato de registro SRV do DNS usado pelo MongoDB Atlas para detectar automaticamente os nós do cluster.mongodb://é o formato tradicional, que exige que você especifique manualmente o host e a porta.
P: Como faço para implantar isso na intranet da empresa (se não conseguir acessar o Atlas)? R: Use o Docker ou uma instalação nativa para configurar sua própria instância do MongoDB na porta 27017 e configure o firewall para permitir o acesso a partir do endereço IP do servidor de aplicativos. Você não precisa do serviço em nuvem do Atlas.
📖 Resumo
- Métodos de instalação do MongoDB: Docker (recomendado) / Atlas (serviço em nuvem) / instalação nativa
- Iniciando o Docker:
docker run -d --name mongodb-dev -p 27017:27017 mongo:7.0 - O Atlas oferece um cluster M0 de 512 MB que é gratuito para sempre
- O mongosh é o cliente oficial de linha de comando do MongoDB (substituindo o antigo shell do mongo)
db.runCommand({ ping: 1 })é o comando padrão para verificar uma conexão- O plug-in do VSCode para MongoDB oferece suporte à navegação gráfica e à execução de scripts nos Playgrounds
- Problemas comuns de instalação: conflitos de porta, espaço em disco, firewalls e configuração da lista de permissões
📝 Exercícios
-
Exercício básico (⭐): Inicie um contêiner do MongoDB 7.0 usando o Docker, mapeie a porta 27017 e conecte-se com sucesso usando o mongosh para executar
db.runCommand({ ping: 1 }). -
Exercício básico (⭐): Crie um cluster M0 gratuito no MongoDB Atlas, configure uma lista de endereços IP permitidos (0.0.0.0/0) e um usuário do banco de dados, e conecte-se ao Atlas usando o mongosh.
-
Exercício avançado (⭐⭐): Execute
use shopdb,db.products.insertOne({...})edb.products.find().pretty()no mongosh para compreender o mecanismo implícito de criação de bancos de dados e coleções. -
Problema avançado (⭐⭐): Escreva um script em Node.js
ping-test.jsque utilize o driver nativomongodbpara se conectar a uma instância local do MongoDB, execute o comando ping e exiba o tempo de resposta. -
Exercício avançado (⭐⭐): Instale o plug-in do MongoDB no VS Code, conecte-se a um cluster do Atlas e execute uma consulta de agregação no Playgrounds
db.users.aggregate([{$group: {_id: '$age', count: {$sum: 1}}}]). -
Desafio (⭐⭐⭐): Use o Docker Compose para iniciar um conjunto de réplicas do MongoDB com três nós (consulte a documentação oficial), configure um script de inicialização para criar usuários e inicializar dados automaticamente e verifique o status do conjunto de réplicas
rs.status().