Skip to main content

DocumentDB Solution Summary

Problem​

TwinSpires needs to use AWS DocumentDB instead of MongoDB Atlas for their Bike4Mind deployment. DocumentDB requires a TLS certificate file (tlsCAFile parameter) in the connection string, but SST v2's NextjsSite doesn't support copyFiles to include the .pem file in the Lambda bundle.

Solution Overview​

We implemented a runtime certificate management approach that:

  1. Embeds the AWS global certificate bundle as a base64 string (or loads from environment variable)
  2. Writes the certificate to /tmp/certs/rds-ca-bundle.pem on Lambda cold start
  3. Automatically detects DocumentDB connections and modifies the connection string
  4. Maintains full backward compatibility with MongoDB Atlas

Key Components​

1. Certificate Manager (documentdb-cert-manager.ts)​

  • Manages certificate lifecycle
  • Detects DocumentDB connections (via environment variable or URL pattern)
  • Modifies connection strings to include certificate path
  • Writes certificate only once per Lambda cold start

2. Enhanced Database Connection (mongo.ts)​

  • Updated connectDB function to detect and handle DocumentDB
  • Transparent to existing code - no changes needed in API routes
  • Logs certificate operations for debugging

3. Configuration (sst.config.ts)​

  • Added MAIN_DB_TYPE environment variable to all functions
  • No infrastructure changes required
  • Works with existing VPC configuration

Usage​

Basic Deployment​

# Set the database type
export MAIN_DB_TYPE=DocumentDB

# Deploy
npx sst deploy --stage twinspires-staging

With External Certificate​

# Download and convert certificate
./scripts/update-documentdb-cert.sh

# Set certificate as environment variable
export DOCUMENTDB_CA_BUNDLE_BASE64=$(cat global-bundle-base64.txt)

# Deploy
MAIN_DB_TYPE=DocumentDB npx sst deploy --stage twinspires-staging

Advantages​

  1. No Breaking Changes: Feature-flagged implementation preserves existing functionality
  2. Minimal Code Changes: Only core database package modified
  3. Flexible Certificate Management: Supports embedded or environment variable certificates
  4. Automatic Detection: Can detect DocumentDB URLs without explicit configuration
  5. Performance Optimized: Certificate written once per cold start
  6. Fully Tested: Includes unit tests for all functionality

Alternative Approaches Considered​

  1. Lambda Layers: Would require significant SST configuration changes
  2. Build-time File Injection: SST v2 doesn't support this for NextjsSite
  3. Public S3 Bucket: Security concerns with certificate distribution
  4. Base64 in Connection String: Mongoose doesn't support this

Next Steps​

  1. TwinSpires team to:

    • Download actual certificate using provided script
    • Set up DocumentDB clusters
    • Configure VPC and security groups
    • Test in staging environment

  2. Future improvements:

    • Automatic certificate rotation
    • Region-specific certificate optimization
    • CloudWatch metrics for certificate operations

Files Modified​

  • b4m-core/packages/core/database/src/certs/documentdb-cert-manager.ts (new)
  • b4m-core/packages/core/database/src/utils/mongo.ts (updated)
  • b4m-core/packages/core/database/src/index.ts (updated)
  • sst.config.ts (updated)
  • Documentation and scripts (new)

This solution provides a clean, maintainable approach to supporting DocumentDB without disrupting existing MongoDB Atlas deployments.