Database Configuration
Cherry Studio Enterprise uses PostgreSQL as its database, supporting both managed cloud databases and self-hosted deployments.
Recommended Options
Option 1: Use a Managed Cloud Database (Recommended)
Use a managed database service from a cloud provider to avoid self-maintenance:
- Alibaba Cloud RDS PostgreSQL
- Tencent Cloud PostgreSQL
- Huawei Cloud RDS for PostgreSQL
- AWS RDS PostgreSQL
- Azure Database for PostgreSQL
Option 2: Use an Existing PostgreSQL Server
If your organization already has a PostgreSQL server, you can use it directly.
Database Preparation
Regardless of the option, prepare the following:
- Create database: Create a database named
cherry-studio-enterprise - Create user: Create a dedicated database user and grant permissions
- Get connection details:
- Host
- Port (default 5432)
- Database name
- Username
- Password
Environment Variable Configuration
Based on the Docker deployment guide, configure the following database-related variables:
Required Configuration
# Database type
DB_TYPE=postgres
# Database connection details
DB_HOST=your-database-host.com # Database host
DB_PORT=5432 # Database port, default 5432
DB_USERNAME=cherry-studio-enterprise # Database username
DB_PASSWORD=your_secure_password # Database password
DB_NAME=cherry-studio-enterprise # Database name
# SSL connection (often required by cloud services)
DB_SSL=true # Enable SSLConfiguration Examples
Example 1: Alibaba Cloud RDS
DB_TYPE=postgres
DB_HOST=rm-xxxxxx.pg.rds.aliyuncs.com
DB_PORT=5432
DB_USERNAME=cherry-studio-enterprise
DB_PASSWORD=Al1yun_Secure_Pwd_2024
DB_NAME=cherry-studio-enterprise
DB_SSL=trueExample 2: Tencent Cloud PostgreSQL
DB_TYPE=postgres
DB_HOST=postgres-xxxxxx.ap-shanghai.postgres.tencentcloudmysql.com
DB_PORT=5432
DB_USERNAME=cherry-studio-enterprise
DB_PASSWORD=Tencent_DB_Pwd_2024
DB_NAME=cherry-studio-enterprise
DB_SSL=trueExample 3: Private PostgreSQL Server
DB_TYPE=postgres
DB_HOST=192.168.1.100
DB_PORT=5432
DB_USERNAME=cherry-studio-enterprise
DB_PASSWORD=Internal_Secure_Pwd
DB_NAME=cherry-studio-enterprise
DB_SSL=false # SSL can be disabled for internal networksDocker Compose Configuration
Configure in docker-compose.yml:
services:
cherry-studio-enterprise-api:
image: cherrystudio/cherry-studio-enterprise-api:latest
container_name: cherry-studio-enterprise-api
environment:
# Database configuration
- DB_TYPE=postgres
- DB_HOST=your-database-host.com
- DB_PORT=5432
- DB_USERNAME=cherry-studio-enterprise
- DB_PASSWORD=${DB_PASSWORD} # Recommended to use env vars or .env file
- DB_NAME=cherry-studio-enterprise
- DB_SSL=true
# Other required configuration omitted here
ports:
- '3670:3670'
- '3680:3680'
volumes:
- ./data:/app/data
- ./logs:/app/logs
restart: unless-stoppedUse a .env File (Recommended)
Create a .env file to manage sensitive information:
# .env file
DB_TYPE=postgres
DB_HOST=your-database-host.com
DB_PORT=5432
DB_USERNAME=cherry-studio-enterprise
DB_PASSWORD=your_secure_password
DB_NAME=cherry-studio-enterprise
DB_SSL=true
# Other required configuration omitted hereThen reference it in docker-compose.yml:
services:
cherry-studio-enterprise-api:
image: cherrystudio/cherry-studio-enterprise-api:latest
container_name: cherry-studio-enterprise-api
env_file:
- .env
ports:
- '3670:3670'
- '3680:3680'
volumes:
- ./data:/app/data
- ./logs:/app/logs
restart: unless-stoppedConnection Testing
After starting the service, verify the database connection:
# View container logs
docker logs cherry-studio-enterprise-api
# Successful connection will show similar messages:
# [Database] Connected to PostgreSQL successfully
# [Database] Database initializedNotes
- Database naming convention: Use
cherry-studio-enterprisefor database name and username - Strong password policy: Use strong passwords and avoid defaults
- SSL connection:
- Cloud services usually require SSL (
DB_SSL=true) - For internal networks, decide based on security requirements
- Cloud services usually require SSL (
- Data backup: Back up databases regularly, especially in production
- Version requirement: PostgreSQL 12.0 or later (15.x recommended)
Troubleshooting
Connection failures
- Check host and port
- Verify username and password
- Confirm firewall allows connections
- For cloud services, check IP allowlist/whitelist settings
SSL connection issues
- Cloud services often require SSL, ensure
DB_SSL=true - Some cloud services require downloading SSL certificates
- For internal networks, set
DB_SSL=falseif not needed
Insufficient permissions
Ensure the database user has:
- CREATE (create tables)
- SELECT, INSERT, UPDATE, DELETE (data operations)
- ALTER (modify table schema)
For technical support, contact: support@cherry-ai.com