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

info PostgreSQL is the recommended database provider due to better JSON support and overall performance characteristics.

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

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:

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

Development Migrations

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

warn Only use db:migrate:dev in development environments. For production, always use db:deploy.

Migration Scripts Explained

The package.json includes several database-related scripts: