# AdonisJS + PostgreSQL

> Node.js MVC framework with PostgreSQL and Lucid ORM.

- Category: Full Web Stacks
- Difficulty: intermediate
- Components: adonis, postgres
- Tags: adonis, nodejs, postgres, mvc
- Source: https://docker.recipes/full-stacks/adonis-postgres

## Overview

AdonisJS is a TypeScript-first Node.js MVC framework inspired by Laravel and Rails, designed to provide a complete web application development experience with built-in features like authentication, validation, ORM, and mail handling. Created by Harminder Virk, AdonisJS emphasizes developer productivity through convention over configuration, strong typing, and a rich ecosystem of first-party packages that eliminate the need to piece together disparate npm modules.

This stack combines AdonisJS with PostgreSQL to create a robust web application platform where Lucid ORM (AdonisJS's built-in ORM) leverages PostgreSQL's advanced features like JSONB columns, full-text search, and complex relationship handling. PostgreSQL's ACID compliance and advanced indexing capabilities complement AdonisJS's sophisticated query builder and migration system, enabling developers to build data-intensive applications with confidence in data integrity and performance.

This combination is ideal for development teams seeking a Laravel-like experience in the Node.js ecosystem, particularly those building content management systems, e-commerce platforms, or enterprise applications requiring complex business logic and reliable data persistence. The TypeScript-first approach of AdonisJS paired with PostgreSQL's mature feature set makes this stack particularly valuable for teams prioritizing code maintainability and long-term scalability.

## Features

- Lucid ORM with full PostgreSQL feature support including JSONB columns, arrays, and advanced data types
- Built-in database migrations and schema management with PostgreSQL-specific column types and constraints
- Edge templating engine with server-side rendering and PostgreSQL query result formatting
- Integrated authentication system with PostgreSQL session storage and user management
- Route model binding with automatic PostgreSQL record fetching and type safety
- Built-in validator with PostgreSQL unique constraint checking and database rule validation
- AdonisJS ace commands for database seeding, migration rollbacks, and PostgreSQL maintenance tasks
- Full-text search integration using PostgreSQL's native search capabilities through Lucid ORM

## Use cases

- Enterprise web applications requiring complex business logic with reliable ACID-compliant data storage
- Content management systems with mixed relational and JSON document storage needs
- E-commerce platforms needing inventory management, order processing, and financial transaction integrity
- Multi-tenant SaaS applications leveraging PostgreSQL's row-level security and schema isolation
- API backends for mobile applications requiring authentication, file uploads, and real-time features
- Internal business tools and dashboards with complex reporting and data analytics requirements
- Educational platforms with user management, course content delivery, and progress tracking

## Prerequisites

- Docker and Docker Compose installed with at least 1GB RAM available for PostgreSQL
- Node.js and npm knowledge for AdonisJS application development and package management
- Basic understanding of MVC architecture patterns and ORM concepts
- SQL knowledge for database design, migrations, and complex query optimization
- Port 3333 available for AdonisJS application access
- Environment file (.env) configuration experience for database credentials and application settings

## docker-compose.yml

```yaml
services:
  adonis:
    build: .
    container_name: adonis
    environment:
      DB_CONNECTION: pg
      PG_HOST: postgres
      PG_PORT: 5432
      PG_USER: ${DB_USER}
      PG_PASSWORD: ${DB_PASSWORD}
      PG_DB_NAME: ${DB_NAME}
    ports:
      - "3333:3333"
    depends_on:
      - postgres
    networks:
      - adonis-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:
      - adonis-network

volumes:
  postgres_data:

networks:
  adonis-network:
    driver: bridge
```

## .env

```bash
DB_NAME=adonis
DB_USER=adonis
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.adonisjs.com/
- Access at http://localhost:3333
- TypeScript-first MVC framework for Node.js
- Lucid ORM with migrations: node ace migration:run
- Built-in auth, validation, i18n, and mail
- Similar developer experience to Laravel/Rails

## Troubleshooting

- Connection refused to PostgreSQL: Ensure postgres service is fully started before adonis container attempts connection, add healthcheck or increase depends_on wait time
- Migration failed with relation does not exist: Run 'node ace migration:run' inside the adonis container after PostgreSQL is ready and database is created
- TypeScript compilation errors on startup: Verify AdonisJS version compatibility and ensure all @adonisjs packages are at matching versions in package.json
- Session/authentication not persisting: Check that PostgreSQL connection is stable and session table migration has been executed successfully
- Lucid ORM query timeouts: Increase PostgreSQL max_connections setting and optimize queries using AdonisJS query builder explain methods
- Port 3333 already in use: Stop any existing Node.js applications or change the host port mapping in docker-compose.yml

