Key benefits of this architecture:
* **n8n main process** handles the web UI and API requests.
* **Worker processes** execute workflows independently, preventing long-running jobs from blocking the main application.
* **PostgreSQL** stores all workflow definitions, executions, credentials, and history.
* **Redis** manages the job queue, ensuring tasks are processed reliably and can be retried if needed.
## Step 1: Create an environment for PostgreSQL and Redis
As we never push major changes in production directly, we will first create a staging environment to test the new
configuration before applying it to production.
```bash title="Terminal" theme={null}
upsun branch add-postgresql-redis
```
This will create a new branch and environment named `add-postgresql-redis` where we will be able to test the new
configuration without affecting the production environment.
## Step 2: Add PostgreSQL and Redis services
First, update your `.upsun/config.yaml` to include PostgreSQL and Redis services:
```yaml .upsun/config.yaml theme={null}
services:
database:
type: postgresql:16
redis:
type: redis:8.0
```
This minimal configuration creates:
* A PostgreSQL 16 database for persistent workflow storage.
* A Redis 8.0 instance for caching and the job queue.
## Step 3: Configure n8n application
Update your n8n application configuration in `.upsun/config.yaml` to connect to PostgreSQL and use Redis:
```yaml title=".upsun/config.yaml" {5-11} theme={null}
applications:
app-n8n:
type: 'nodejs:22'
#...
relationships:
database:
redis:
workers:
worker:
commands:
start: "n8n worker --concurrency=${N8N_WORKER_CONCURRENCY:-1}"
```
Key configuration points:
* **`relationships`** link n8n to PostgreSQL (as `database`) and Redis as a job queue.
* **`workers`** handle background job processing—scale the concurrency setting as needed.
* n8n auto-detects PostgreSQL and Redis via [services variables](/docs/development/variables#service-environment-variables) Upsun injects.
## Step 4: Add `.environment` specific environment variables
```ini location=".environment" theme={null}
# Config PostgreSQL
export DB_TYPE=postgresdb
export DB_POSTGRESDB_HOST=${DATABASE_HOST}
export DB_POSTGRESDB_PORT=${DATABASE_PORT}
export DB_POSTGRESDB_DATABASE=${DATABASE_PATH}
export DB_POSTGRESDB_USER=${DATABASE_USERNAME}
export DB_POSTGRESDB_PASSWORD=${DATABASE_PASSWORD}
# Config Redis
export N8N_CACHE_ENABLED=true
export N8N_CACHE_BACKEND=redis
export N8N_CACHE_REDIS_HOST=${REDIS_HOST}
export N8N_CACHE_REDIS_PORT=${REDIS_PORT}
export N8N_CACHE_REDIS_PASSWORD=${REDIS_PASSWORD}
export N8N_CACHE_REDIS_TTL=3600 # default to 1h
# Queue on Redis
export QUEUE_BULL_REDIS_HOST=${REDIS_HOST}
export QUEUE_BULL_REDIS_PORT=${REDIS_PORT}
export QUEUE_BULL_REDIS_PASSWORD=${REDIS_PASSWORD}
export QUEUE_HEALTH_CHECK_ACTIVE=true
```
Once you've updated the configuration:
```bash {filename="Terminal"} theme={null}
git add .upsun/config.yaml
git commit -m "Add PostgreSQL and Redis services"
```
## Step 5: Migrate existing data
User accounts can't be migrated automatically. The `export:entities` / `import:entities` CLI commands are still
experimental and unreliable across different n8n versions — attempts may fail with migration timestamp mismatches.
## Performance tuning tips
Now that you're using PostgreSQL and Redis with dedicated workers, optimize further:
### Worker concurrency
Adjust the `N8N_WORKER_CONCURRENCY` environment variable to control how many jobs a worker processes simultaneously:
```yaml .upsun/config.yaml {8} theme={null}
applications:
app-n8n:
type: 'nodejs:22'
#...
variables:
env:
#...
N8N_WORKER_CONCURRENCY: "2" # Default is 1
```
Higher concurrency handles more workflows in parallel, but requires more memory—that's why `container_profile: HIGHER_MEMORY` is recommended.
### PostgreSQL optimization
* **Backup regularly**: Enable automatic backups in your Upsun environment to protect your workflow data.
* **Monitor disk usage**: As your execution history grows, the database will expand. Allocate enough disk space or set retention policies.
* **Monitor slow queries**: Check PostgreSQL logs if workflow execution feels sluggish.
### Redis optimization
* **Monitor queue depth**: Use `upsun ssh` to check Redis memory and queue depth during peak times:
```bash title="Terminal" theme={null}
upsun ssh
redis-cli
> INFO stats
```
## Troubleshooting
### **Workers not processing jobs**
* Verify worker process logs: `upsun logs worker`
* Check Redis is running: `upsun logs redis`
* Ensure `N8N_WORKER_CONCURRENCY` is set to a reasonable value.
### **High memory usage**
* Confirm `container_profile: HIGHER_MEMORY` is set in your n8n app config.
* Lower `N8N_WORKER_CONCURRENCY` if workers exceed available memory.
* Monitor via: `upsun ssh` → `top` or check environment metrics in the console.
### **PostgreSQL connection errors**
* Check app logs: `upsun logs app`
* Ensure the relationship names match in both `applications` and services.
* Verify environment variables are correctly set and injected.
### **Workflows not appearing after migration**
* Verify credentials were correctly re-entered (they don't auto-migrate).
* Check that all imports completed successfully in the UI.
* Ensure `.n8n` mount has enough storage space.
## Next steps
You now have a production-ready n8n setup on Upsun. From here, you can:
* **Add more workflows** without performance concerns.
* **Enable API access** for external integrations.
* **Set up monitoring** with Upsun's observability tools.
* **Integrate with your CI/CD pipeline** for workflow deployment.
Want to share how you're using n8n on Upsun? Tweet us [@Upsun](https://twitter.com/upsun).
***
## Resources
* [n8n Documentation](https://docs.n8n.io/)
* [Upsun PostgreSQL Service](https://developer.upsun.com/docs/add-services/postgresql)
* [Upsun Redis Service](https://developer.upsun.com/docs/add-services/redis)
* [n8n on Upsun Tutorial](/posts/hands-on/nocode-n8n)