Database Workflows

Common database operations and workflows in Genbox.

Database Modes

When creating environments, you can choose how to set up the database:

Mode	Description	Use Case
`none`	No database	Frontend-only work
`local`	Empty database	Fresh starts, testing
`copy`	Copy from environment	Real data for development
`snapshot`	Restore from backup	Specific point in time
`remote`	Connect to remote	Read-only access

Creating with Database Options

No Database


gb create my-env --db none

Empty Local Database


gb create my-env --db local

Copy from Staging


gb create my-env --db copy --db-source staging

Copy from Production


gb create my-env --db copy --db-source production

Syncing Data

Full Sync

Sync all collections from staging:


gb db sync --source staging

Selective Sync

Only sync specific collections:


gb db sync --source staging --include users,products,orders

Exclude large collections:


gb db sync --source staging --exclude logs,analytics,sessions

Preview Before Sync


gb db sync --source staging --dry-run

Working with Local Data

Restore Local Backup

Upload and restore a local MongoDB dump:


# Create local dump first
mongodump --db myapp --out ./backup
 
# Restore to Genbox
gb restore-db --path ./backup/myapp

Export from Genbox

Connect and export data:


gb connect -c "mongodump --db myapp --out /tmp/export"
 
# Then download
scp -r my-env.genbox.dev:/tmp/export ./local-backup

Using Local Tools

Port Forwarding for MongoDB Compass


# Forward MongoDB port
gb forward --ports 27017
 
# Connect with Compass:
# mongodb://localhost:27017/mydb

Port Forwarding for TablePlus


gb forward --ports 27017
 
# Connection settings:
# Host: localhost
# Port: 27017
# Database: mydb

Using mongosh


# Via SSH
gb connect -c "mongosh mydb"
 
# Or forward and use locally
gb forward --ports 27017
mongosh mongodb://localhost:27017/mydb

Database Configuration in genbox.yaml

Basic Setup


provides:
  mongodb:
    type: database
    image: mongo:7
    port: 27017

With Authentication


provides:
  mongodb:
    type: database
    image: mongo:7
    port: 27017
    env:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}

With Replica Set (for transactions)


provides:
  mongodb:
    type: database
    image: mongo:7
    port: 27017
    replicaSet: rs0

Profile-Specific Database Settings


profiles:
  quick:
    database:
      mode: none              # No database for quick testing
 
  with-data:
    database:
      mode: copy
      source: staging
      exclude:
        - logs
        - audit_history
 
  fresh:
    database:
      mode: local             # Empty database

Environment Connection Strings

Configure source connection strings:


environments:
  staging:
    env:
      MONGODB_URI: ${STAGING_MONGODB_URI}
 
  production:
    env:
      MONGODB_URI: ${PROD_MONGODB_URI}
    safety:
      read_only: true

.env.genbox:


STAGING_MONGODB_URI=mongodb+srv://user:pass@staging-cluster.mongodb.net/mydb
PROD_MONGODB_URI=mongodb+srv://user:pass@prod-cluster.mongodb.net/mydb

Common Workflows

Debug Production Issue


# 1. Create with production data
gb create debug --db copy --db-source production
 
# 2. Forward for local tools
gb forward --ports 27017
 
# 3. Investigate with Compass/mongosh
# ...
 
# 4. Clean up
gb destroy debug

Test Data Migration


# 1. Create with staging data
gb create migration-test --db copy --db-source staging
 
# 2. Run migration
gb connect -c "pnpm db:migrate"
 
# 3. Verify migration
gb connect -c "pnpm test:migration"
 
# 4. If successful, run on staging

Reset to Clean State


# Rebuild with empty database
gb rebuild my-env --fresh-db

Best Practices

Use staging for development: Avoid production unless necessary
Exclude large collections: Save time and storage
Create backups before destructive operations
Use read-only for production: Prevent accidental writes
Test migrations on copies: Never on production directly