Database Configuration - Evolution API

Evolution API requires a database to store instance data, messages, contacts, and configuration. This guide covers database setup, connection configuration, and schema management.

Supported Databases

Evolution API supports three database configurations:

PostgreSQL - Recommended for production deployments
MySQL - Alternative for MySQL-based infrastructures
PostgreSQL with PgBouncer - For high-concurrency deployments

Database Provider

Set the database provider in your .env file:

DATABASE_PROVIDER

enum

required

Database provider to use. Options:

postgresql - Standard PostgreSQL connection
mysql - MySQL/MariaDB connection
psql_bouncer - PostgreSQL with PgBouncer connection pooling

DATABASE_PROVIDER=postgresql

PostgreSQL Setup

Installation

Docker
Ubuntu/Debian
macOS

Use the official PostgreSQL Docker image:

docker run -d \
  --name evolution_postgres \
  -e POSTGRES_DB=evolution_db \
  -e POSTGRES_USER=evolution \
  -e POSTGRES_PASSWORD=your_secure_password \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql/data \
  postgres:15

Install PostgreSQL from the official repository:

# Add PostgreSQL repository
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# Install PostgreSQL
sudo apt update
sudo apt install -y postgresql-15

# Create database and user
sudo -u postgres psql -c "CREATE DATABASE evolution_db;"
sudo -u postgres psql -c "CREATE USER evolution WITH PASSWORD 'your_secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE evolution_db TO evolution;"

Install PostgreSQL using Homebrew:

# Install PostgreSQL
brew install postgresql@15

# Start PostgreSQL service
brew services start postgresql@15

# Create database and user
createdb evolution_db
psql evolution_db -c "CREATE USER evolution WITH PASSWORD 'your_secure_password';"
psql evolution_db -c "GRANT ALL PRIVILEGES ON DATABASE evolution_db TO evolution;"

Connection URI Format

Configure the PostgreSQL connection in your .env file:

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://user:password@host:port/database?schema=schema_name'

Example:

DATABASE_CONNECTION_URI='postgresql://evolution:your_password@localhost:5432/evolution_db?schema=evolution_api'

URI Components:

evolution - Database username
your_password - Database password
localhost - Database host (use container name in Docker)
5432 - PostgreSQL port
evolution_db - Database name
evolution_api - Prisma schema name

Performance Tuning

For production deployments, optimize PostgreSQL configuration:

-- Increase max connections
ALTER SYSTEM SET max_connections = 1000;

-- Optimize for Evolution API workload
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
ALTER SYSTEM SET maintenance_work_mem = '64MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
ALTER SYSTEM SET wal_buffers = '16MB';
ALTER SYSTEM SET default_statistics_target = 100;
ALTER SYSTEM SET random_page_cost = 1.1;

-- Reload configuration
SELECT pg_reload_conf();

MySQL Setup

Installation

Docker
Ubuntu/Debian

Use the official MySQL Docker image:

docker run -d \
  --name evolution_mysql \
  -e MYSQL_DATABASE=evolution_db \
  -e MYSQL_USER=evolution \
  -e MYSQL_PASSWORD=your_secure_password \
  -e MYSQL_ROOT_PASSWORD=root_password \
  -p 3306:3306 \
  -v mysql_data:/var/lib/mysql \
  mysql:8

Install MySQL from the official repository:

# Install MySQL
sudo apt update
sudo apt install -y mysql-server

# Secure installation
sudo mysql_secure_installation

# Create database and user
sudo mysql -e "CREATE DATABASE evolution_db;"
sudo mysql -e "CREATE USER 'evolution'@'%' IDENTIFIED BY 'your_secure_password';"
sudo mysql -e "GRANT ALL PRIVILEGES ON evolution_db.* TO 'evolution'@'%';"
sudo mysql -e "FLUSH PRIVILEGES;"

Connection URI Format

Configure the MySQL connection in your .env file:

DATABASE_PROVIDER=mysql
DATABASE_CONNECTION_URI='mysql://user:password@host:port/database'

Example:

DATABASE_CONNECTION_URI='mysql://evolution:your_password@localhost:3306/evolution_db'

PgBouncer Configuration

PgBouncer provides connection pooling for high-concurrency deployments.

Setup with Docker Compose

docker-compose.yaml

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: evolution_db
      POSTGRES_USER: evolution
      POSTGRES_PASSWORD: your_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  pgbouncer:
    image: edoburu/pgbouncer:latest
    environment:
      DATABASE_URL: postgres://evolution:your_password@postgres:5432/evolution_db
      POOL_MODE: transaction
      MAX_CLIENT_CONN: 1000
      DEFAULT_POOL_SIZE: 20
    depends_on:
      - postgres
    ports:
      - "5432:5432"

Connection Configuration

Use both connection URIs when using PgBouncer:

DATABASE_PROVIDER=psql_bouncer
DATABASE_CONNECTION_URI='postgresql://evolution:your_password@postgres:5432/evolution_db?schema=evolution_api'
DATABASE_BOUNCER_CONNECTION_URI='postgresql://evolution:your_password@pgbouncer:5432/evolution_db?pgbouncer=true&schema=evolution_api'

Database Migrations

Evolution API uses Prisma for database schema management.

Environment Setup

Always set DATABASE_PROVIDER before running migration commands.

# Set database provider
export DATABASE_PROVIDER=postgresql  # or mysql

Generate Prisma Client

Generate the Prisma client for your database provider:

npm run db:generate

This reads the schema from:

prisma/postgresql-schema.prisma for PostgreSQL
prisma/mysql-schema.prisma for MySQL

Run Migrations

Development
Production

For development environments:

# Unix/Linux/macOS
npm run db:migrate:dev

# Windows
npm run db:migrate:dev:win

This creates migration files and applies them to the database.

For production deployments:

# Unix/Linux/macOS
npm run db:deploy

# Windows
npm run db:deploy:win

This applies pending migrations without creating new ones.

Docker Automatic Migrations

When using the official Docker image, migrations run automatically on startup:

ENTRYPOINT ["/bin/bash", "-c", ". ./Docker/scripts/deploy_database.sh && npm run start:prod" ]

The deploy_database.sh script:

Detects the database provider from DATABASE_PROVIDER
Generates the correct Prisma client
Runs pending migrations
Starts the application

Database Schema

Evolution API’s database schema includes tables for:

Core Tables

Instance - WhatsApp instance information

model Instance {
  id                      String                   @id @default(cuid())
  name                    String                   @unique
  connectionStatus        InstanceConnectionStatus @default(open)
  ownerJid                String?
  profileName             String?
  profilePicUrl           String?
  number                  String?
  token                   String?
  createdAt               DateTime?                @default(now())
  updatedAt               DateTime?                @updatedAt
}

Message - WhatsApp messages

model Message {
  id                           String          @id @default(cuid())
  key                          Json
  pushName                     String?
  messageType                  String
  message                      Json
  messageTimestamp             Int
  instanceId                   String
  Instance                     Instance        @relation(fields: [instanceId], references: [id], onDelete: Cascade)
}

Contact - WhatsApp contacts

model Contact {
  id            String    @id @default(cuid())
  remoteJid     String
  pushName      String?
  profilePicUrl String?
  instanceId    String
  Instance      Instance  @relation(fields: [instanceId], references: [id], onDelete: Cascade)
}

Chat - WhatsApp conversations

model Chat {
  id             String    @id @default(cuid())
  remoteJid      String
  name           String?
  unreadMessages Int       @default(0)
  instanceId     String
  Instance       Instance  @relation(fields: [instanceId], references: [id], onDelete: Cascade)
}

Integration Tables

Webhook - Webhook configurations
Chatwoot - Chatwoot CRM integration
Typebot - Typebot chatbot integration
OpenaiBot - OpenAI chatbot integration
Dify - Dify AI integration
Rabbitmq - RabbitMQ event configuration
Sqs - AWS SQS event configuration
Websocket - WebSocket event configuration

Prisma Studio

Browse and edit your database with Prisma Studio:

npm run db:studio

This opens a web interface at http://localhost:5555 for database management.

Data Storage Options

Control what data is saved to the database:

.env

# Save all data types (recommended)
DATABASE_SAVE_DATA_INSTANCE=true
DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=true
DATABASE_SAVE_DATA_CONTACTS=true
DATABASE_SAVE_DATA_CHATS=true
DATABASE_SAVE_DATA_LABELS=true
DATABASE_SAVE_DATA_HISTORIC=true

# WhatsApp number verification cache
DATABASE_SAVE_IS_ON_WHATSAPP=true
DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7

# Delete messages when deleted in WhatsApp
DATABASE_DELETE_MESSAGE=true

Disabling data storage options reduces database size but limits API functionality like message history and contact retrieval.

Client Name Separation

When running multiple Evolution API installations on the same database:

DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange

This separates data between installations sharing the same database instance.

Backup and Restore

PostgreSQL Backup

# Backup database
pg_dump -U evolution -h localhost evolution_db > backup.sql

# Backup with Docker
docker exec evolution_postgres pg_dump -U evolution evolution_db > backup.sql

# Restore database
psql -U evolution -h localhost evolution_db < backup.sql

# Restore with Docker
docker exec -i evolution_postgres psql -U evolution evolution_db < backup.sql

MySQL Backup

# Backup database
mysqldump -u evolution -p evolution_db > backup.sql

# Backup with Docker
docker exec evolution_mysql mysqldump -u evolution -p evolution_db > backup.sql

# Restore database
mysql -u evolution -p evolution_db < backup.sql

# Restore with Docker
docker exec -i evolution_mysql mysql -u evolution -p evolution_db < backup.sql

Automated Backups

Set up automated daily backups with cron:

# Add to crontab
0 2 * * * /usr/bin/docker exec evolution_postgres pg_dump -U evolution evolution_db | gzip > /backups/evolution-$(date +\%Y\%m\%d).sql.gz

Troubleshooting

Connection refused errors

If Evolution API cannot connect to the database:

Verify the database is running:

docker ps | grep postgres
# or
sudo systemctl status postgresql

Check connection URI format is correct
Verify username and password
Ensure the database exists:
```
psql -U evolution -l
```
Check firewall rules allow connections on port 5432/3306

Migration errors

If migrations fail:

Ensure DATABASE_PROVIDER is set correctly:
```
echo $DATABASE_PROVIDER
```

Verify database connection before running migrations:

psql -U evolution -h localhost -d evolution_db -c "SELECT 1;"

Check migration files exist:
```
ls prisma/postgresql-migrations/
```
Reset migrations (development only):
```
npx prisma migrate reset
```

Authentication failed errors

For authentication errors:

Verify username and password in connection URI

Check user permissions:

-- PostgreSQL
\du evolution

-- MySQL
SHOW GRANTS FOR 'evolution'@'%';

Ensure user has necessary privileges:

-- PostgreSQL
GRANT ALL PRIVILEGES ON DATABASE evolution_db TO evolution;

-- MySQL
GRANT ALL PRIVILEGES ON evolution_db.* TO 'evolution'@'%';
FLUSH PRIVILEGES;

Slow query performance

To optimize query performance:

Enable query logging:

-- PostgreSQL
ALTER SYSTEM SET log_min_duration_statement = 1000;
SELECT pg_reload_conf();

Analyze slow queries:

EXPLAIN ANALYZE SELECT * FROM "Message" WHERE "instanceId" = 'xxx';

Create indexes for frequently queried columns
Increase shared_buffers and effective_cache_size
Consider using PgBouncer for connection pooling

Security Best Practices

Use strong passwords - Generate random passwords for database users
Limit network access - Bind database to localhost or private network only
Enable SSL/TLS - Use encrypted connections in production
Regular backups - Implement automated backup strategies
Update regularly - Keep database software up to date
Monitor access - Enable and review database audit logs
Principle of least privilege - Grant only necessary permissions

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

​Supported Databases

​Database Provider

​PostgreSQL Setup

​Installation

​Connection URI Format

​Performance Tuning

​MySQL Setup

​Installation

​Connection URI Format

​PgBouncer Configuration

​Setup with Docker Compose

​Connection Configuration

​Database Migrations

​Environment Setup

​Generate Prisma Client

​Run Migrations

​Docker Automatic Migrations

​Database Schema

​Core Tables

​Integration Tables

​Prisma Studio

​Data Storage Options

​Client Name Separation

​Backup and Restore

​PostgreSQL Backup

​MySQL Backup

​Automated Backups

​Troubleshooting

​Security Best Practices

​Next Steps

Environment Variables

Docker Deployment

Build docs developers (and LLMs) love

Supported Databases

Database Provider

PostgreSQL Setup

Installation

Connection URI Format

Performance Tuning

MySQL Setup

Installation

Connection URI Format

PgBouncer Configuration

Setup with Docker Compose

Connection Configuration

Database Migrations

Environment Setup

Generate Prisma Client

Run Migrations

Docker Automatic Migrations

Database Schema

Core Tables

Integration Tables

Prisma Studio

Data Storage Options

Client Name Separation

Backup and Restore

PostgreSQL Backup

MySQL Backup

Automated Backups

Troubleshooting

Security Best Practices

Next Steps