Elysia + PostgreSQL

intermediate

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

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.

Key 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

Common Use Cases

1High-performance REST APIs requiring sub-millisecond response times
2TypeScript-first applications needing compile-time database query validation
3Microservices architecture where fast startup times reduce container orchestration overhead
4Real-time applications leveraging PostgreSQL's LISTEN/NOTIFY for pub-sub messaging
5Data-intensive applications using PostgreSQL's advanced indexing and query optimization
6Enterprise applications requiring ACID compliance and complex transaction management
7API-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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  elysia: 
3    image: oven/bun:latest
4    container_name: elysia
5    working_dir: /app
6    command: bun run src/index.ts
7    environment: 
8      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
9    volumes: 
10      - ./:/app
11    ports: 
12      - "3000:3000"
13    depends_on: 
14      - postgres
15    networks: 
16      - elysia-network
17
18  postgres: 
19    image: postgres:16-alpine
20    environment: 
21      POSTGRES_DB: ${DB_NAME}
22      POSTGRES_USER: ${DB_USER}
23      POSTGRES_PASSWORD: ${DB_PASSWORD}
24    volumes: 
25      - postgres_data:/var/lib/postgresql/data
26    networks: 
27      - elysia-network
28
29volumes: 
30  postgres_data: 
31
32networks: 
33  elysia-network: 
34    driver: bridge

.env Template

.env

1DB_NAME=elysia
2DB_USER=elysia
3DB_PASSWORD=changeme

Usage Notes

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

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

elysia

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  elysia:
5    image: oven/bun:latest
6    container_name: elysia
7    working_dir: /app
8    command: bun run src/index.ts
9    environment:
10      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
11    volumes:
12      - ./:/app
13    ports:
14      - "3000:3000"
15    depends_on:
16      - postgres
17    networks:
18      - elysia-network
19
20  postgres:
21    image: postgres:16-alpine
22    environment:
23      POSTGRES_DB: ${DB_NAME}
24      POSTGRES_USER: ${DB_USER}
25      POSTGRES_PASSWORD: ${DB_PASSWORD}
26    volumes:
27      - postgres_data:/var/lib/postgresql/data
28    networks:
29      - elysia-network
30
31volumes:
32  postgres_data:
33
34networks:
35  elysia-network:
36    driver: bridge
37EOF
38
39# 2. Create the .env file
40cat > .env << 'EOF'
41DB_NAME=elysia
42DB_USER=elysia
43DB_PASSWORD=changeme
44EOF
45
46# 3. Start the services
47docker compose up -d
48
49# 4. View logs
50docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/elysia-postgres/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

elysiapostgres

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download