# Hono + PostgreSQL

> Ultrafast web framework for edge and serverless with PostgreSQL.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: hono, postgres
- Tags: hono, edge, postgres, serverless
- Source: https://docker.recipes/full-stacks/hono-postgres

## Overview

Hono is an ultrafast web framework designed specifically for edge computing and serverless environments, built with Web Standard APIs (Request, Response) for maximum portability across JavaScript runtimes including Bun, Deno, Node.js, Cloudflare Workers, and Vercel. Originally created to address the performance limitations of traditional web frameworks in edge environments, Hono features a RegExp-based router that delivers exceptional routing speed while maintaining a small bundle size, making it ideal for latency-sensitive applications deployed at the edge. When combined with PostgreSQL, this stack creates a powerful full-stack solution that leverages PostgreSQL's enterprise-grade ACID compliance, advanced transaction support, and robust JSON/JSONB capabilities alongside Hono's edge-optimized performance characteristics. The PostgreSQL integration provides reliable data persistence with full-text search, geospatial capabilities through PostGIS, and sophisticated query optimization, while Hono handles high-throughput request processing with minimal cold start times. This combination is particularly valuable for developers building modern web applications that require both edge performance and enterprise-grade database capabilities, such as real-time APIs, serverless backends, and globally distributed applications that need consistent data integrity across multiple regions.

## Features

- RegExp-based ultrafast routing with sub-millisecond request processing optimized for edge deployment
- Web Standard API compatibility enabling deployment across Bun, Deno, Node.js, Cloudflare Workers, and Vercel without code changes
- PostgreSQL ACID compliance with advanced transaction isolation levels for enterprise-grade data integrity
- JSON/JSONB native support in PostgreSQL for hybrid relational-document data models with indexing
- Edge-optimized cold start performance with minimal bundle size for serverless environments
- Full-text search capabilities with ranking and highlighting through PostgreSQL's built-in search functions
- Logical and streaming replication support for multi-region PostgreSQL deployments
- Extensible PostgreSQL type system supporting custom functions and PostGIS geospatial operations

## Use cases

- Edge-deployed API backends for mobile applications requiring sub-100ms response times globally
- Serverless e-commerce platforms needing ACID transactions for payment processing with edge caching
- Real-time analytics dashboards processing high-frequency data with PostgreSQL window functions
- Multi-tenant SaaS applications leveraging PostgreSQL row-level security and Hono's lightweight routing
- Geospatial applications combining PostGIS capabilities with edge-optimized API responses
- JAMstack applications requiring fast API routes with complex relational data queries
- IoT data collection systems processing sensor data at edge locations with PostgreSQL time-series optimization

## Prerequisites

- Docker Desktop or Docker Engine with Docker Compose v2.0+ installed and running
- Minimum 1GB RAM available (256MB for PostgreSQL, additional memory for Hono application)
- Port 3000 available for Hono web server access
- Basic understanding of JavaScript/TypeScript and SQL query syntax
- Familiarity with ORM tools like Drizzle or Prisma for database schema management
- Environment variables configured for DB_NAME, DB_USER, and DB_PASSWORD

## docker-compose.yml

```yaml
services:
  hono:
    build: .
    container_name: hono
    environment:
      DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
    ports:
      - "3000:3000"
    depends_on:
      - postgres
    networks:
      - hono-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:
      - hono-network

volumes:
  postgres_data:

networks:
  hono-network:
    driver: bridge
```

## .env

```bash
DB_NAME=hono
DB_USER=hono
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://hono.dev/
- Access at http://localhost:3000
- Runs on Bun, Deno, Node.js, Cloudflare Workers, Vercel
- Web Standard APIs (Request, Response)
- Ultrafast routing with RegExp-based router
- Use Drizzle or Prisma for database access

## Troubleshooting

- Connection refused on port 3000: Ensure Hono container built successfully and DATABASE_URL environment variable is properly formatted
- PostgreSQL connection timeout: Verify postgres container is fully initialized before Hono starts, consider adding healthcheck or wait script
- FATAL: database does not exist: Check DB_NAME environment variable matches POSTGRES_DB value in postgres service
- Hono runtime errors about missing dependencies: Verify your Dockerfile includes proper package.json and node_modules installation for chosen runtime
- ORM connection pooling issues: Configure connection pool size appropriately for PostgreSQL max_connections setting in high-load scenarios
- Edge deployment failures: Ensure Hono application uses only Web Standard APIs and avoid Node.js-specific modules for serverless compatibility

