fix: database documentation

Author: tip-dteller

docs/database.md

@@ -12,18 +12,18 @@ Work directly with MongoDB databases, collections, users, roles, and indexes thr
 ## Important Distinction: Database vs Atlas Management
 
 **Database Commands** (`matlas database`) operate directly on MongoDB databases via connection strings:
-- Create database-level users and custom roles directly in MongoDB
+- Create and manage custom roles with granular privileges
+- Manage databases, collections, and indexes
 - Require database connection (direct connection string or Atlas cluster with temp user)
-- Support granular, collection-level permissions
-- Use MongoDB's native `createUser`, `createRole` commands
+- Support collection-level permissions and custom role definitions
 
 **Atlas Commands** (`matlas atlas`) operate via Atlas Admin API:
-- Manage Atlas-level database users with built-in roles
-- Use Atlas API authentication (API keys)
-- Assign built-in MongoDB roles (read, readWrite, dbAdmin, etc.)
-- Project-level user management
+- **All user management** happens through Atlas API (there is no direct MongoDB user creation)
+- Users created via Atlas API automatically propagate to MongoDB databases
+- Assign built-in MongoDB roles (read, readWrite, dbAdmin, etc.) and custom roles
+- Project-level user management with centralized authentication
 
-Use `database` commands for granular database-specific operations and `atlas` commands for centralized Atlas project management.
+**User Management**: All database users must be created through `matlas atlas users` commands. Users created in Atlas automatically become available in MongoDB databases after propagation.
 
 
 
@@ -292,7 +292,7 @@ kind: ApplyDocument
 metadata:
   name: custom-roles-example
 resources:
-  # Custom database role
+  # Custom database role (created directly in MongoDB)
   - apiVersion: matlas.mongodb.com/v1
     kind: DatabaseRole
     metadata:
@@ -320,7 +320,8 @@ resources:
         - roleName: read
           databaseName: myapp
 
-  # User that uses the custom role
+  # Atlas database user that uses the custom role
+  # Note: All users must be created via Atlas API - they propagate to MongoDB databases
   - apiVersion: matlas.mongodb.com/v1
     kind: DatabaseUser
     metadata:
@@ -375,97 +376,75 @@ matlas database roles delete myCustomRole \
   --yes
 ```
 
-## Database Users
+## Database Users (Atlas-Managed)
 
-Manage MongoDB database users directly in databases. These users are created using MongoDB's `createUser` command and can be assigned both built-in roles and custom roles created with `matlas database roles`.
+**Important**: In MongoDB Atlas, all database users must be created and managed through the Atlas API. Direct MongoDB `createUser` commands are not supported.
 
-**Note**: These are different from Atlas database users managed via `matlas atlas users`. Database users exist only within specific MongoDB databases, while Atlas users are managed centrally via the Atlas API.
+All database user management is handled via `matlas atlas users` commands. Users created through Atlas automatically propagate to MongoDB databases and can access databases according to their assigned roles.
 
-### List database users
-```bash
-# Using connection string
-matlas database users list \
-  --connection-string "mongodb+srv://user:pass@host/" \
-  --database myapp
+### User Management via Atlas API
 
-# Using Atlas cluster with temporary user (recommended)
-matlas database users list \
-  --cluster my-cluster \
-  --project-id abc123 \
-  --database myapp \
-  --use-temp-user
-```
+For complete user management documentation, see the [Atlas Commands](/atlas/) documentation. Here are the essential commands:
 
-### Create database user
 ```bash
-# Create user with built-in roles
-matlas database users create dbuser \
-  --cluster my-cluster \
+# Create Atlas database user (propagates to MongoDB databases)
+matlas atlas users create \
   --project-id abc123 \
-  --database myapp \
-  --use-temp-user \
+  --username dbuser \
+  --database-name admin \
   --password "SecurePass123!" \
   --roles "readWrite@myapp,read@logs"
 
-# Create user with custom roles and display password
-matlas database users create appuser \
-  --cluster my-cluster \
-  --project-id abc123 \
-  --database myapp \
-  --use-temp-user \
-  --password "SecurePass123!" \
-  --roles "customRole@myapp" \
-  --show-password
-```
+# List all Atlas database users
+matlas atlas users list --project-id abc123
 
-### Update database user
-```bash
-# Update password
-matlas database users update dbuser \
-  --cluster my-cluster \
+# Update user roles
+matlas atlas users update \
   --project-id abc123 \
-  --database myapp \
-  --use-temp-user \
-  --password "NewPass123!"
-
-# Replace all roles
-matlas database users update dbuser \
-  --cluster my-cluster \
-  --project-id abc123 \
-  --database myapp \
-  --use-temp-user \
+  --username dbuser \
+  --database-name admin \
   --roles "read@myapp,read@logs"
 
-# Add roles incrementally
-matlas database users update dbuser \
-  --cluster my-cluster \
+# Get user details
+matlas atlas users get \
   --project-id abc123 \
-  --database myapp \
-  --use-temp-user \
-  --add-roles "write@logs"
-```
+  --username dbuser \
+  --database-name admin
 
-### Get database user details
-```bash
-matlas database users get dbuser \
-  --cluster my-cluster \
+# Delete user
+matlas atlas users delete \
   --project-id abc123 \
-  --database myapp \
-  --use-temp-user
+  --username dbuser \
+  --database-name admin
 ```
 
-### Delete database user
+### Role Assignment with Custom Roles
+
+Users created via Atlas can be assigned both built-in MongoDB roles and custom roles created with `matlas database roles`:
+
 ```bash
-matlas database users delete dbuser \
+# Create custom role first
+matlas database roles create appRole \
   --cluster my-cluster \
   --project-id abc123 \
   --database myapp \
   --use-temp-user \
-  --yes
+  --privileges "read@myapp,[email protected]"
+
+# Create user with custom role via Atlas
+matlas atlas users create \
+  --project-id abc123 \
+  --username appuser \
+  --database-name admin \
+  --password "SecurePass123!" \
+  --roles "appRole@myapp,read@admin"
 ```
 
-**Important Notes:**
-- Database users are scoped to specific databases
-- When using `--use-temp-user`, the CLI creates a temporary Atlas user with `userAdmin` privileges for user management
-- Database users can be assigned custom roles created with `matlas database roles create`
-- Use `--verbose` flag to see detailed operation information
+### Propagation and Access
+
+- Users created via Atlas API automatically propagate to all clusters in the project
+- Role assignments determine which databases and collections the user can access
+- Custom roles created with `matlas database roles` can be assigned to Atlas users
+- Use `--verbose` with Atlas commands to see detailed operation information
+
+**Note**: The `matlas database users` commands are not functional in Atlas environments and will redirect you to use `matlas atlas users` instead.

tracking/documentation.md

@@ -63,3 +63,34 @@ This ensures all developers follow the established workspace rules and maintain
 
 ---
 
+## [2025-01-27] Database User Management Documentation Correction
+
+**Status**: Completed  
+**Developer**: Assistant  
+**Related Issues**: User feedback about incorrect documentation  
+
+### Summary
+Corrected misleading documentation in `docs/database.md` that incorrectly claimed there were two different types of user management (Atlas vs Database). Fixed to reflect actual implementation where all users are created via Atlas API and propagate to MongoDB databases.
+
+### Tasks
+- [x] Correct main distinction section between Atlas and Database commands
+- [x] Remove false separation between "Atlas users" and "Database users"
+- [x] Rewrite Database Users section to clarify Atlas-managed nature
+- [x] Update examples to show correct Atlas user creation patterns
+- [x] Add clarifying comments in YAML examples
+
+### Files Modified
+- `docs/database.md` - Major revision to Database Users section and command distinction explanation
+
+### Notes
+The original documentation incorrectly suggested that `matlas database users` commands would create users directly in MongoDB using `createUser` commands. However, the actual implementation shows:
+
+1. All user management goes through Atlas API (`internal/services/atlas/users.go`)
+2. The `cmd/database/users/users.go` commands are stubs that redirect to Atlas commands
+3. Tests in `database-operations.sh` correctly use `matlas atlas users create`
+4. Users created via Atlas automatically propagate to MongoDB databases
+
+This correction eliminates confusion and aligns documentation with the actual codebase behavior. The user management model is: **Atlas API → User Creation → Propagation to MongoDB Databases**.
+
+---
+