# Phoenix + PostgreSQL

> Elixir Phoenix framework with PostgreSQL and LiveView.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: phoenix, postgres
- Tags: phoenix, elixir, postgres, liveview
- Source: https://docker.recipes/full-stacks/phoenix-postgres

## Overview

Phoenix is a modern web framework built on the Elixir programming language and the Erlang Virtual Machine (BEAM), created by Chris McCord in 2014. Phoenix leverages the Actor Model and fault-tolerance principles of Erlang to deliver exceptional performance and reliability for web applications. The framework is particularly renowned for LiveView, a revolutionary feature that enables real-time, interactive user interfaces with server-rendered HTML, eliminating the need for complex JavaScript frameworks while maintaining rich user experiences. Phoenix applications can handle millions of concurrent connections with minimal resource usage, making it ideal for real-time applications like chat systems, collaboration tools, and live dashboards.

This stack combines Phoenix with PostgreSQL to create a robust foundation for data-intensive web applications that demand both high concurrency and strong data integrity. PostgreSQL's ACID compliance and advanced querying capabilities complement Phoenix's real-time features, enabling applications to handle complex business logic while maintaining data consistency across thousands of simultaneous users. The combination is particularly powerful for applications requiring real-time updates backed by reliable data persistence, such as financial dashboards, inventory management systems, or collaborative platforms where data accuracy is critical.

This configuration is ideal for development teams building modern web applications that need to scale efficiently while maintaining code simplicity. Elixir developers will appreciate the productive development experience with hot code reloading and pattern matching, while database administrators benefit from PostgreSQL's mature ecosystem and extensive monitoring capabilities. The stack is particularly valuable for companies transitioning from monolithic architectures to more resilient systems, as Phoenix's supervised processes and 'let it crash' philosophy provide exceptional fault tolerance without the complexity of microservices.

## Features

- LiveView real-time UI updates with server-rendered HTML and minimal JavaScript
- Phoenix Channels for WebSocket-based real-time communication and pub/sub messaging
- Ecto ORM with PostgreSQL providing compile-time query validation and database migrations
- PostgreSQL JSONB support for flexible schema design alongside relational data
- Phoenix PubSub for distributed real-time messaging across multiple server nodes
- Hot code reloading in development for instant feedback during Elixir development
- Supervision trees ensuring automatic recovery from process failures
- PostgreSQL's advanced indexing including GIN indexes for JSONB and full-text search

## Use cases

- Real-time collaboration platforms like document editors or project management tools
- Financial dashboards requiring live data updates with strict data consistency
- E-commerce platforms with real-time inventory tracking and order processing
- Chat applications and messaging systems leveraging Phoenix Channels
- IoT data collection and monitoring dashboards with live sensor updates
- Gaming leaderboards and live tournament tracking with instant score updates
- Customer support systems with real-time ticket updates and live chat functionality

## Prerequisites

- Docker and Docker Compose installed on the host system
- Minimum 1GB RAM recommended for PostgreSQL optimal performance
- Port 4000 available for Phoenix web server access
- Generated SECRET_KEY_BASE environment variable using mix phx.gen.secret
- Basic understanding of Elixir syntax and functional programming concepts
- Familiarity with PostgreSQL database concepts and SQL querying

## docker-compose.yml

```yaml
services:
  phoenix:
    build: .
    container_name: phoenix
    environment:
      DATABASE_URL: ecto://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
    ports:
      - "4000:4000"
    depends_on:
      - postgres
    networks:
      - phoenix-network

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - phoenix-network

volumes:
  postgres_data:

networks:
  phoenix-network:
    driver: bridge
```

## .env

```bash
DB_NAME=phoenix
DB_USER=phoenix
DB_PASSWORD=changeme
SECRET_KEY_BASE=your-secret-key-here
```

## Usage notes

- Docs: https://hexdocs.pm/phoenix/
- Access at http://localhost:4000
- LiveView: real-time server-rendered UIs without JavaScript
- Channels for WebSocket-based features
- Run migrations: docker compose exec phoenix mix ecto.migrate
- Generate SECRET_KEY_BASE: mix phx.gen.secret

## Troubleshooting

- Connection refused to PostgreSQL: Ensure postgres service starts before phoenix using depends_on and verify DATABASE_URL format
- LiveView not updating in real-time: Check that Phoenix.PubSub is properly configured and WebSocket connections aren't blocked by firewalls
- Ecto migration failures: Run docker compose exec phoenix mix ecto.create before running migrations if database doesn't exist
- SECRET_KEY_BASE missing error: Generate key with mix phx.gen.secret and add to environment variables in docker-compose.yml
- Phoenix server crash on startup: Verify Elixir application dependencies are properly compiled by rebuilding the Docker image
- Database encoding issues: Ensure PostgreSQL locale is set to UTF-8 compatible encoding in the postgres service environment

