# Elysia + PostgreSQL

> Bun-first web framework with end-to-end type safety.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: elysia, postgres
- Tags: elysia, bun, postgres, typescript
- Source: https://docker.recipes/full-stacks/elysia-postgres

## Overview

Elysia is a modern TypeScript web framework built specifically for Bun runtime, focusing on end-to-end type safety and exceptional performance. Created as a Bun-first alternative to Express and Fastify, Elysia leverages Bun's native APIs and optimizations to achieve significantly faster request handling while maintaining full TypeScript support throughout the entire application stack. The framework emphasizes developer experience with features like automatic OpenAPI generation, built-in validation, and the Eden client for type-safe API consumption.

This stack combines Elysia's high-performance web server capabilities with PostgreSQL's robust relational database features, creating a powerful foundation for building scalable web applications. Elysia's integration with PostgreSQL through ORMs like Drizzle enables compile-time type checking of database queries, ensuring that schema changes are caught during development rather than runtime. The combination leverages PostgreSQL's advanced features like JSON/JSONB support, full-text search, and ACID compliance while maintaining the performance benefits of Bun's optimized runtime.

Developers building modern web applications who prioritize both performance and type safety will find this stack particularly valuable. Teams transitioning from Node.js-based frameworks can benefit from Bun's faster startup times and reduced memory usage, while PostgreSQL's mature ecosystem and reliability make it ideal for applications requiring complex data relationships, transactions, or compliance requirements. This combination is especially suited for API-heavy applications, real-time services, and projects where end-to-end type safety is crucial.

## Features

- Bun runtime optimization with up to 4x faster startup times compared to Node.js
- End-to-end type safety from database schema to API responses using TypeScript
- Automatic OpenAPI/Swagger documentation generation from route definitions
- Eden client for type-safe API consumption with full IntelliSense support
- PostgreSQL JSONB support for hybrid relational-document data models
- Built-in request validation and serialization with compile-time type checking
- Hot reload development server with Bun's native watch mode
- Plugin ecosystem including JWT authentication, CORS, and rate limiting

## Use cases

- High-performance REST APIs requiring sub-millisecond response times
- TypeScript-first applications needing compile-time database query validation
- Microservices architecture where fast startup times reduce container orchestration overhead
- Real-time applications leveraging PostgreSQL's LISTEN/NOTIFY for pub-sub messaging
- Data-intensive applications using PostgreSQL's advanced indexing and query optimization
- Enterprise applications requiring ACID compliance and complex transaction management
- API-first development with automatic client SDK generation using Eden

## Prerequisites

- Minimum 1GB RAM (PostgreSQL requires 256MB + Bun overhead)
- Docker and Docker Compose v2.0 or higher
- Port 3000 available for Elysia web server
- Basic understanding of TypeScript and async/await patterns
- Familiarity with PostgreSQL schema design and SQL queries
- Knowledge of environment variable configuration for database connections

## docker-compose.yml

```yaml
services:
  elysia:
    image: oven/bun:latest
    container_name: elysia
    working_dir: /app
    command: bun run src/index.ts
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    volumes:
      - ./:/app
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - elysia-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:
      - elysia-network

volumes:
  postgres_data:

networks:
  elysia-network:
    driver: bridge
```

## .env

```bash
DB_NAME=elysia
DB_USER=elysia
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://elysiajs.com/
- Access at http://localhost:3000
- End-to-end type safety with Eden client
- Optimized for Bun runtime (fastest JS runtime)
- Plugin ecosystem: swagger, jwt, cors, etc.
- Use Drizzle ORM for type-safe database queries

## Troubleshooting

- Database connection failed: Ensure DATABASE_URL format matches postgresql://user:password@host:port/database and containers are on same network
- Bun command not found: Verify oven/bun:latest image is properly pulled and container has access to /app volume mount
- TypeScript compilation errors: Check that all dependencies are installed with 'bun install' and tsconfig.json is properly configured
- Port 3000 already in use: Change the host port mapping in docker-compose.yml from '3000:3000' to 'XXXX:3000'
- PostgreSQL data persistence issues: Verify postgres_data volume is properly mounted and has correct permissions
- Hot reload not working: Ensure local project files are mounted to /app and Bun's watch mode is enabled in development

