Database Configuration

Evolution API Lite uses Prisma as its ORM and supports both PostgreSQL and MySQL databases. This guide covers database setup, schema understanding, and migration management.

Supported Database Providers

Evolution API Lite supports two database providers:

PostgreSQL (recommended)
MySQL

Database Setup

1. Choose Your Database Provider

Set the database provider in your .env file:

# For PostgreSQL (recommended)
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://username:password@localhost:5432/evolution_db?schema=public

# For MySQL
DATABASE_PROVIDER=mysql
DATABASE_CONNECTION_URI=mysql://username:password@localhost:3306/evolution_db

2. Database Connection Configuration

Variable	Description	Example
DATABASE_PROVIDER	Database type (postgresql or mysql)	postgresql
DATABASE_CONNECTION_URI	Full database connection string	postgresql://user:pass@localhost:5432/evolution?schema=public
DATABASE_CONNECTION_CLIENT_NAME	Client name for connection separation	evolution_exchange

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution_user:secure_password@localhost:5432/evolution_db?schema=public
DATABASE_CONNECTION_CLIENT_NAME=evolution_prod

DATABASE_PROVIDER=mysql
DATABASE_CONNECTION_URI=mysql://evolution_user:secure_password@localhost:3306/evolution_db
DATABASE_CONNECTION_CLIENT_NAME=evolution_prod

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://postgres:postgres@postgres:5432/evolution?schema=public
DATABASE_CONNECTION_CLIENT_NAME=evolution_docker

Database Schema Overview

The Evolution API Lite database schema is designed to efficiently store WhatsApp instance data, messages, contacts, and configuration. Here are the core models:

Core Models

Instance

The central model that represents a WhatsApp connection.

Key Fields:

id - Unique instance identifier
name - Human-readable instance name (unique)
connectionStatus - Current connection state (open, close, connecting)
ownerJid - WhatsApp JID of the instance owner
profileName - Display name from WhatsApp
profilePicUrl - Profile picture URL
token - Instance authentication token
number - Phone number associated with the instance

Message

Stores all WhatsApp messages with full metadata.

Key Fields:

id - Unique message identifier
key - WhatsApp message key (JSON)
messageType - Type of message (text, image, video, etc.)
message - Message content (JSON)
messageTimestamp - Unix timestamp of the message
source - Device source (ios, android, web, desktop)
instanceId - Reference to the Instance

Contact

Stores contact information for each instance.

Key Fields:

id - Unique contact identifier
remoteJid - WhatsApp JID of the contact
pushName - Contact’s display name
profilePicUrl - Contact’s profile picture URL
instanceId - Reference to the Instance

Chat

Represents individual or group conversations.

Key Fields:

id - Unique chat identifier
remoteJid - WhatsApp JID of the chat
name - Chat name (for groups)
labels - Associated labels (JSON)
unreadMessages - Count of unread messages
instanceId - Reference to the Instance

Integration Models

Webhook

Stores webhook configuration for each instance.

Key Fields:

url - Webhook endpoint URL
events - Enabled events (JSON)
enabled - Whether webhook is active
webhookByEvents - Use separate URLs per event
instanceId - Reference to the Instance

Session

Stores WhatsApp session credentials.

Key Fields:

sessionId - Links to Instance ID
creds - Encrypted session credentials

Bot Integration Models

The schema includes support for various bot integrations:

Typebot - Typebot.io integration
OpenaiBot - OpenAI/ChatGPT integration
Dify - Dify.ai integration
EvolutionBot - Evolution Bot integration
Flowise - Flowise integration

Event Integration Models

Rabbitmq - RabbitMQ event configuration
Sqs - Amazon SQS event configuration
Websocket - WebSocket event configuration
Pusher - Pusher event configuration

Database Migrations

Running Migrations

Evolution API Lite uses Prisma migrations to manage database schema changes. The migration process is automated through package scripts.

Deploy Migrations (Production)

# Deploy migrations to your database
npm run db:deploy

This command:

Copies the appropriate migration files for your database provider
Runs prisma migrate deploy to apply migrations
Generates the Prisma client

Development Migrations

# Create and apply new migrations (development only)
npm run db:migrate:dev

Migration Scripts Explained

The package.json includes several database-related scripts: