External Database
Connect Insights Plus to an external PostgreSQL instance for production deployments.
Requirements
- PostgreSQL 14+
- DDL privileges - the user must be able to create tables, indexes, and extensions
Database Setup
Create the user and database on your PostgreSQL server:
CREATE USER unifi WITH PASSWORD 'your_strong_password';
CREATE DATABASE unifi_logs OWNER unifi;Connection Configuration
Set the following environment variables in your docker-compose.yml:
| Variable | Description |
|---|---|
DB_HOST | External PostgreSQL host. When set to a non-localhost address, the embedded database is disabled |
DB_PORT | PostgreSQL port (default: 5432) |
DB_NAME | Database name (default: unifi_logs) |
DB_USER | Database user (default: unifi) |
DB_PASSWORD | Database password (falls back to POSTGRES_PASSWORD) |
DB_SSLMODE | SSL mode: require, verify-ca, verify-full |
Deployment Topologies
| Scenario | DB_HOST | Notes |
|---|---|---|
| Same Docker Compose | postgres (service name) | Easiest setup - both services share a Docker network |
| Different Docker Compose | Container IP or shared network alias | Create an external Docker network shared between stacks |
| Docker Desktop (macOS/Windows) | host.docker.internal | Built-in DNS alias for the host machine |
| Linux Docker | 172.17.0.1 or host.docker.internal | Use gateway IP or add host.docker.internal via extra_hosts |
| Cloud Database | Cloud provider hostname | Use DB_SSLMODE=require or higher for production |
SECRET_KEY Requirement
When using an external database, you should set the SECRET_KEY environment variable explicitly. Without it, stored API keys are encrypted using POSTGRES_PASSWORD as a fallback - which may not be set in external DB configurations. If the secret changes, stored keys become unrecoverable.
Migration from Embedded Database
The built-in Migration Wizard in Settings → Data & Backups can help you move data between databases.
For step-by-step migration instructions, see the External PostgreSQL Migration Guide on our GitHub wiki.