Back to Details

mongodb-atlas

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MongoDB Atlas Skill

MongoDB Atlas Skill

Provides comprehensive MongoDB and MongoDB Atlas capabilities for the Alpha Members Platform.
为Alpha Members平台提供全面的MongoDB和MongoDB Atlas功能支持。

When to Use This Skill

何时使用该Skill

Activate this skill when working with:
  • MongoDB query development
  • Schema design and modeling
  • Aggregation pipelines
  • Index optimization
  • Prisma MongoDB integration
  • Atlas cluster management
  • Database performance tuning
在进行以下操作时激活此Skill：
  • MongoDB查询开发
  • 模式设计与建模
  • 聚合管道开发
  • 索引优化
  • Prisma MongoDB集成
  • Atlas集群管理
  • 数据库性能调优

Quick Reference

快速参考

Docker Commands

Docker 命令

bash
undefined
bash
undefined

Start local MongoDB

启动本地MongoDB

docker-compose up mongodb -d
docker-compose up mongodb -d

Connect to MongoDB shell

连接到MongoDB Shell

docker exec -it mongodb mongosh -u root -p rootpassword
docker exec -it mongodb mongosh -u root -p rootpassword

Check MongoDB logs

查看MongoDB日志

docker logs mongodb -f --tail=100
undefined
docker logs mongodb -f --tail=100
undefined

MongoDB Shell Commands

MongoDB Shell 命令

javascript
// Switch to database
use member_db

// List collections
show collections

// Find documents
db.members.find({ status: "ACTIVE" }).limit(10)

// Insert document
db.members.insertOne({ email: "test@example.com", status: "PENDING" })

// Update document
db.members.updateOne(
  { email: "test@example.com" },
  { $set: { status: "ACTIVE" } }
)

// Aggregation
db.members.aggregate([
  { $match: { status: "ACTIVE" } },
  { $group: { _id: "$profile.company", count: { $sum: 1 } } }
])
javascript
// 切换数据库
use member_db

// 列出集合
show collections

// 查询文档
db.members.find({ status: "ACTIVE" }).limit(10)

// 插入文档
db.members.insertOne({ email: "test@example.com", status: "PENDING" })

// 更新文档
db.members.updateOne(
  { email: "test@example.com" },
  { $set: { status: "ACTIVE" } }
)

// 聚合查询
db.members.aggregate([
  { $match: { status: "ACTIVE" } },
  { $group: { _id: "$profile.company", count: { $sum: 1 } } }
])

Connection Strings

连接字符串

bash
undefined
bash
undefined

Local Docker

本地Docker环境

mongodb://root:rootpassword@localhost:27017/member_db?authSource=admin
mongodb://root:rootpassword@localhost:27017/member_db?authSource=admin

Atlas (example)

Atlas示例

mongodb+srv://user:password@cluster.mongodb.net/member_db?retryWrites=true&w=majority
undefined
mongodb+srv://user:password@cluster.mongodb.net/member_db?retryWrites=true&w=majority
undefined

Schema Design

模式设计

Prisma MongoDB Schema

Prisma MongoDB 模式

prisma
datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

model Member {
  id              String          @id @default(auto()) @map("_id") @db.ObjectId
  keycloakUserId  String          @unique
  email           String          @unique
  firstName       String
  lastName        String
  status          MemberStatus    @default(PENDING)
  profile         MemberProfile?  // Embedded
  addresses       MemberAddress[] // Embedded array
  memberships     Membership[]    // Relation
  createdAt       DateTime        @default(now())
  updatedAt       DateTime        @updatedAt

  @@index([status])
  @@index([email])
}

type MemberProfile {
  jobTitle    String?
  company     String?
  timezone    String  @default("UTC")
}

type MemberAddress {
  type        AddressType
  street1     String
  city        String
  state       String
  postalCode  String
}
prisma
datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

model Member {
  id              String          @id @default(auto()) @map("_id") @db.ObjectId
  keycloakUserId  String          @unique
  email           String          @unique
  firstName       String
  lastName        String
  status          MemberStatus    @default(PENDING)
  profile         MemberProfile?  // 嵌入式文档
  addresses       MemberAddress[] // 嵌入式数组
  memberships     Membership[]    // 关联关系
  createdAt       DateTime        @default(now())
  updatedAt       DateTime        @updatedAt

  @@index([status])
  @@index([email])
}

type MemberProfile {
  jobTitle    String?
  company     String?
  timezone    String  @default("UTC")
}

type MemberAddress {
  type        AddressType
  street1     String
  city        String
  state       String
  postalCode  String
}

Collections

集合结构

members

members集合

javascript
{
  _id: ObjectId("..."),
  keycloakUserId: "uuid",
  email: "user@example.com",
  firstName: "John",
  lastName: "Doe",
  status: "ACTIVE",
  profile: {
    jobTitle: "Engineer",
    company: "Acme Corp"
  },
  addresses: [
    { type: "HOME", street1: "123 Main St", ... }
  ],
  createdAt: ISODate("..."),
  updatedAt: ISODate("...")
}
javascript
{
  _id: ObjectId("..."),
  keycloakUserId: "uuid",
  email: "user@example.com",
  firstName: "John",
  lastName: "Doe",
  status: "ACTIVE",
  profile: {
    jobTitle: "Engineer",
    company: "Acme Corp"
  },
  addresses: [
    { type: "HOME", street1: "123 Main St", ... }
  ],
  createdAt: ISODate("..."),
  updatedAt: ISODate("...")
}

memberships

memberships集合

javascript
{
  _id: ObjectId("..."),
  memberId: ObjectId("..."),
  type: "INDIVIDUAL",
  level: "PREMIUM",
  status: "ACTIVE",
  startDate: ISODate("..."),
  payment: {
    method: "card",
    amount: 99.99,
    currency: "USD"
  }
}
javascript
{
  _id: ObjectId("..."),
  memberId: ObjectId("..."),
  type: "INDIVIDUAL",
  level: "PREMIUM",
  status: "ACTIVE",
  startDate: ISODate("..."),
  payment: {
    method: "card",
    amount: 99.99,
    currency: "USD"
  }
}

member_activities

member_activities集合

javascript
{
  _id: ObjectId("..."),
  memberId: ObjectId("..."),
  action: "LOGIN",
  category: "AUTH",
  ipAddress: "192.168.1.1",
  createdAt: ISODate("...")
}
javascript
{
  _id: ObjectId("..."),
  memberId: ObjectId("..."),
  action: "LOGIN",
  category: "AUTH",
  ipAddress: "192.168.1.1",
  createdAt: ISODate("...")
}

Indexing

索引配置

Recommended Indexes

推荐索引

javascript
// Members collection
db.members.createIndex({ keycloakUserId: 1 }, { unique: true })
db.members.createIndex({ email: 1 }, { unique: true })
db.members.createIndex({ status: 1, createdAt: -1 })
db.members.createIndex({ "profile.company": 1 })

// Text search
db.members.createIndex({
  firstName: "text",
  lastName: "text",
  email: "text",
  "profile.company": "text"
})

// Memberships
db.memberships.createIndex({ memberId: 1 })
db.memberships.createIndex({ status: 1, endDate: 1 })

// Activities (with TTL)
db.member_activities.createIndex({ memberId: 1, createdAt: -1 })
db.member_activities.createIndex(
  { createdAt: 1 },
  { expireAfterSeconds: 31536000 } // 1 year TTL
)
javascript
// Members集合索引
db.members.createIndex({ keycloakUserId: 1 }, { unique: true })
db.members.createIndex({ email: 1 }, { unique: true })
db.members.createIndex({ status: 1, createdAt: -1 })
db.members.createIndex({ "profile.company": 1 })

// 全文搜索索引
db.members.createIndex({
  firstName: "text",
  lastName: "text",
  email: "text",
  "profile.company": "text"
})

// Memberships集合索引
db.memberships.createIndex({ memberId: 1 })
db.memberships.createIndex({ status: 1, endDate: 1 })

// Activities集合（带TTL）
db.member_activities.createIndex({ memberId: 1, createdAt: -1 })
db.member_activities.createIndex(
  { createdAt: 1 },
  { expireAfterSeconds: 31536000 } // 1年TTL过期
)

Aggregation Pipelines

聚合管道示例

Member Statistics

会员统计

javascript
db.members.aggregate([
  { $facet: {
      byStatus: [
        { $group: { _id: "$status", count: { $sum: 1 } } }
      ],
      byMonth: [
        { $group: {
            _id: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
            count: { $sum: 1 }
          }
        },
        { $sort: { _id: 1 } }
      ],
      total: [{ $count: "count" }]
    }
  }
])
javascript
db.members.aggregate([
  { $facet: {
      byStatus: [
        { $group: { _id: "$status", count: { $sum: 1 } } }
      ],
      byMonth: [
        { $group: {
            _id: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
            count: { $sum: 1 }
          }
        },
        { $sort: { _id: 1 } }
      ],
      total: [{ $count: "count" }]
    }
  }
])

Member with Memberships

关联会员与会员资格

javascript
db.members.aggregate([
  { $match: { _id: ObjectId("...") } },
  { $lookup: {
      from: "memberships",
      localField: "_id",
      foreignField: "memberId",
      as: "memberships"
    }
  }
])
javascript
db.members.aggregate([
  { $match: { _id: ObjectId("...") } },
  { $lookup: {
      from: "memberships",
      localField: "_id",
      foreignField: "memberId",
      as: "memberships"
    }
  }
])

Prisma Operations

Prisma 操作示例

typescript
// Find member
const member = await prisma.member.findUnique({
  where: { email: "user@example.com" },
  include: { memberships: true }
});

// Create member with embedded profile
const newMember = await prisma.member.create({
  data: {
    email: "new@example.com",
    firstName: "Jane",
    lastName: "Doe",
    keycloakUserId: "uuid",
    profile: {
      jobTitle: "Manager",
      company: "Acme"
    }
  }
});

// Update with push to array
const updated = await prisma.member.update({
  where: { id: "..." },
  data: {
    addresses: {
      push: {
        type: "WORK",
        street1: "456 Office Blvd",
        city: "Boston",
        state: "MA",
        postalCode: "02102"
      }
    }
  }
});

// Aggregation with Prisma
const stats = await prisma.member.groupBy({
  by: ['status'],
  _count: true
});
typescript
// 查询会员
const member = await prisma.member.findUnique({
  where: { email: "user@example.com" },
  include: { memberships: true }
});

// 创建带嵌入式profile的会员
const newMember = await prisma.member.create({
  data: {
    email: "new@example.com",
    firstName: "Jane",
    lastName: "Doe",
    keycloakUserId: "uuid",
    profile: {
      jobTitle: "Manager",
      company: "Acme"
    }
  }
});

// 向数组添加元素
const updated = await prisma.member.update({
  where: { id: "..." },
  data: {
    addresses: {
      push: {
        type: "WORK",
        street1: "456 Office Blvd",
        city: "Boston",
        state: "MA",
        postalCode: "02102"
      }
    }
  }
});

// 使用Prisma进行聚合
const stats = await prisma.member.groupBy({
  by: ['status'],
  _count: true
});

Performance Optimization

性能优化

Query Optimization

查询优化

javascript
// Use projection to limit returned fields
db.members.find(
  { status: "ACTIVE" },
  { firstName: 1, lastName: 1, email: 1 }
)

// Use covered queries
db.members.find(
  { email: "user@example.com" },
  { _id: 0, email: 1, status: 1 }
).hint({ email: 1, status: 1 })

// Explain query plan
db.members.find({ status: "ACTIVE" }).explain("executionStats")
javascript
// 使用投影限制返回字段
db.members.find(
  { status: "ACTIVE" },
  { firstName: 1, lastName: 1, email: 1 }
)

// 使用覆盖查询
db.members.find(
  { email: "user@example.com" },
  { _id: 0, email: 1, status: 1 }
).hint({ email: 1, status: 1 })

// 查看查询执行计划
db.members.find({ status: "ACTIVE" }).explain("executionStats")

Index Analysis

索引分析

javascript
// Get index usage stats
db.members.aggregate([{ $indexStats: {} }])

// Find unused indexes
db.members.aggregate([
  { $indexStats: {} },
  { $match: { "accesses.ops": 0 } }
])
javascript
// 获取索引使用统计
db.members.aggregate([{ $indexStats: {} }])

// 查找未使用的索引
db.members.aggregate([
  { $indexStats: {} },
  { $match: { "accesses.ops": 0 } }
])

Atlas CLI Commands

Atlas CLI 命令

bash
undefined
bash
undefined

Login to Atlas

登录Atlas

atlas auth login
atlas auth login

List clusters

列出集群

atlas clusters list --projectId <projectId>
atlas clusters list --projectId <projectId>

Create cluster

创建集群

atlas clusters create alpha-dev
--projectId <projectId>
--provider AWS
--region US_EAST_1
--tier M10
atlas clusters create alpha-dev
--projectId <projectId>
--provider AWS
--region US_EAST_1
--tier M10

Get connection string

获取连接字符串

atlas clusters connectionStrings describe alpha-dev
undefined
atlas clusters connectionStrings describe alpha-dev
undefined

Project Files

项目文件

  • Prisma Schema: 
    prisma/schema.prisma
  • MongoDB Init: 
    infrastructure/mongo-init/01-init-db.js
  • Docker: 
    docker/docker-compose.yml
    (mongodb service)
  • Prisma 模式文件: 
    prisma/schema.prisma
  • MongoDB 初始化脚本: 
    infrastructure/mongo-init/01-init-db.js
  • Docker 配置: 
    docker/docker-compose.yml
    （mongodb服务）

Related Agents

相关Agent

  • mongodb-atlas-admin - Cluster management
  • mongodb-schema-designer - Schema design
  • mongodb-query-optimizer - Performance tuning
  • mongodb-aggregation-specialist - Complex queries
  • mongodb-atlas-admin - 集群管理
  • mongodb-schema-designer - 模式设计
  • mongodb-query-optimizer - 性能调优
  • mongodb-aggregation-specialist - 复杂查询

Troubleshooting

故障排查

bash
undefined
bash
undefined

Check MongoDB connection

检查MongoDB连接

docker exec mongodb mongosh --eval "db.adminCommand('ping')"
docker exec mongodb mongosh --eval "db.adminCommand('ping')"

Check replication status

检查复制状态

docker exec mongodb mongosh --eval "rs.status()"
docker exec mongodb mongosh --eval "rs.status()"

Analyze slow queries

分析慢查询

db.setProfilingLevel(1, { slowms: 100 }) db.system.profile.find().sort({ millis: -1 }).limit(10)
undefined
db.setProfilingLevel(1, { slowms: 100 }) db.system.profile.find().sort({ millis: -1 }).limit(10)
undefined