@mamoorali295/rbac/docs/DATABASE_COMPARISON.md

Complete RBAC (Role-Based Access Control) system for Node.js with Express middleware, NestJS integration, GraphQL support, MongoDB & PostgreSQL support, modern admin dashboard, TypeScript support, and dynamic permission management

# Database Support Comparison

The RBAC package supports both MongoDB and PostgreSQL with identical functionality through a unified adapter pattern.

## Quick Configuration Comparison

### MongoDB Configuration
```javascript
const mongoose = require('mongoose');

await RBAC.init({
  database: {
    type: 'mongodb',
    connection: mongoose.connection
  },
  authAdapter: async (req) => ({ user_id: req.user.id }),
  defaultRole: 'user'
});
```

### PostgreSQL Configuration
```javascript
const { Pool } = require('pg');

const pgPool = new Pool({
  user: 'username',
  host: 'localhost', 
  database: 'dbname',
  password: 'password',
  port: 5432,
});

await RBAC.init({
  database: {
    type: 'postgresql',
    connection: pgPool
  },
  authAdapter: async (req) => ({ user_id: req.user.id }),
  defaultRole: 'user'
});
```

## Schema Comparison

### MongoDB Collections
- `RbacUsers` - User references with role ObjectId
- `RbacRoles` - Roles with nested features array
- `RbacFeatures` - Application features/modules  
- `RbacPermissions` - Permission definitions

### PostgreSQL Tables
- `rbac_users` - User references with role UUID
- `rbac_roles` - Role definitions
- `rbac_features` - Application features/modules
- `rbac_permissions` - Permission definitions
- `rbac_role_feature_permissions` - Junction table for many-to-many relationships

## Data Structure Differences

### MongoDB (Document-based)
```javascript
// UserRole document
{
  _id: ObjectId("..."),
  name: "admin",
  description: "Administrator role",
  features: [
    {
      feature: ObjectId("feature1"),
      permissions: [ObjectId("perm1"), ObjectId("perm2")]
    }
  ]
}
```

### PostgreSQL (Relational)
```sql
-- Normalized tables with junction table
SELECT r.name, f.name as feature, p.name as permission
FROM rbac_roles r
JOIN rbac_role_feature_permissions rfp ON r.id = rfp.role_id
JOIN rbac_features f ON rfp.feature_id = f.id  
JOIN rbac_permissions p ON rfp.permission_id = p.id
WHERE r.name = 'admin';
```

## Performance Characteristics

### MongoDB
- ✅ **Faster Reads**: Single document queries with populated data
- ✅ **Flexible Schema**: Easy to add new fields without migration
- ✅ **JSON Native**: Direct object mapping
- ❌ **Complex Queries**: Limited aggregation capabilities
- ❌ **Data Consistency**: No foreign key constraints

### PostgreSQL  
- ✅ **Data Integrity**: Foreign key constraints ensure consistency
- ✅ **Complex Queries**: Advanced SQL capabilities and joins
- ✅ **ACID Compliance**: Strong consistency guarantees
- ✅ **Mature Ecosystem**: Extensive tooling and optimization
- ❌ **Schema Rigid**: Requires migrations for changes
- ❌ **Setup Complexity**: More configuration required

## Migration Guide

### From MongoDB to PostgreSQL

1. **Install Dependencies**
   ```bash
   npm install pg @types/pg
   ```

2. **Update Configuration**
   ```javascript
   // Old (MongoDB)
   await RBAC.init({
     db: mongoose.connection,  // Deprecated but still supported
     // ... other options
   });
   
   // New (PostgreSQL)  
   await RBAC.init({
     database: {
       type: 'postgresql',
       connection: pgPool
     },
     // ... other options
   });
   ```

3. **Run Schema Setup**
   ```javascript
   // Schema is automatically created during RBAC.init()
   // Or run src/postgres/schema.sql manually
   ```

4. **Migrate Data** (if needed)
   ```javascript
   // Export from MongoDB and import to PostgreSQL
   // Custom migration scripts needed for data transfer
   ```

### From PostgreSQL to MongoDB

1. **Install Dependencies**
   ```bash
   npm install mongoose
   ```

2. **Update Configuration**
   ```javascript
   // New (MongoDB)
   await RBAC.init({
     database: {
       type: 'mongodb', 
       connection: mongoose.connection
     },
     // ... other options
   });
   ```

## Deployment Recommendations

### Development
- **MongoDB**: Easier setup, good for prototyping
- **PostgreSQL**: Better for learning SQL and data modeling

### Production
- **MongoDB**: Choose for flexible schemas and rapid development
- **PostgreSQL**: Choose for data integrity and complex reporting

### Hybrid Approach
You can even use different databases in different environments:

```javascript
const dbConfig = process.env.NODE_ENV === 'production' 
  ? { type: 'postgresql', connection: pgPool }
  : { type: 'mongodb', connection: mongoConnection };

await RBAC.init({
  database: dbConfig,
  // ... other options
});
```

## API Compatibility

**All RBAC methods work identically regardless of database:**

```javascript
// These work the same with MongoDB or PostgreSQL
await RBAC.checkPermissions()
await RBAC.registerUser()  
await RBAC.registerUserManual()
await RBAC.updateUser()
await RBAC.assignRole()
await RBAC.getUserRole()
await RBAC.getFeaturePermissions()
RBAC.adminDashboard()
```

The admin dashboard UI and all functionality is identical between databases.