feat: ✨ add automatic database migrations and error handling

[truehazker]

• Introduced DB_AUTO_MIGRATE configuration to enable automatic migrations on server startup.
• Implemented migration error handling to prevent server startup on failure.
• Updated dependencies: drizzle-orm to 0.45.0, elysia to 1.4.18, and drizzle-kit to 0.31.8.
• Modified docker-compose to rename postgres service and volume for clarity.

Summary by CodeRabbit

• New Features

  • Configurable automatic database migrations on startup (toggleable).
  • App startup now runs initialization tasks before listening.

• Bug Fixes

  • Improved database migration error handling.

• Chores

  • Dependency updates to newer versions.
  • Docker Compose: service/volume renamed and healthcheck enhanced.
  • Logging improvements and clearer log namespaces for better diagnostics.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@truehazker has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 16 minutes and 23 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 05e0fa4 and 1182e43.

📒 Files selected for processing (2)

• docker-compose.yml (3 hunks)
• src/db/index.ts (2 hunks)

Walkthrough

Adds a DB_AUTO_MIGRATE flag and bootstrap flow to optionally run database migrations on startup; renames Docker Postgres service and volume; bumps several dependencies; and introduces namespaced child loggers in a few modules.

Changes

Cohort / File(s)	Summary
Configuration & Env \.env.example, src/common/config.ts	Add DB_AUTO_MIGRATE env var (default false) and parse it as a boolean in config.
Database Migration & Startup src/db/index.ts, src/main.ts	Add migrateDb() to run drizzle migrations; introduce bootstrap() in main.ts to conditionally run migrations before app.listen, with startup error handling and graceful shutdown registration.
Docker Compose docker-compose.yml	Rename postgres → elysia-boilerplate-postgres, rename volume to elysia-boilerplate-postgres-data, update references and add healthcheck timeout: 5s and retries: 5.
Dependencies package.json	Bump versions: drizzle-orm, elysia, and drizzle-kit.
Logging src/modules/users/index.ts, src/util/graceful-shutdown.ts, src/common/logger.ts	Use logger import alias and create namespaced child loggers; change pino-pretty transport activation to include both development and test NODE_ENV values.
Changelog / Docs CHANGELOG.md	Add entries for migration error handling, automatic migrations, and dependency updates.

Sequence Diagram

sequenceDiagram
    participant Server as Server (main.ts)
    participant Config as Config (src/common/config.ts)
    participant Migrator as Migrator (src/db/index.ts)
    participant Logger as Logger

    Server->>Config: read DB_AUTO_MIGRATE
    alt DB_AUTO_MIGRATE == true
        Server->>Logger: log "Running migrations..."
        Server->>Migrator: call migrateDb()
        Migrator->>Logger: log before/after migration
        Migrator-->>Server: migration result
    else DB_AUTO_MIGRATE == false
        Server->>Logger: log "Skipping migrations"
    end
    Server->>Server: app.listen(...)
    Server->>Logger: log server URL
    Server->>Server: register SIGINT/SIGTERM handlers

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review bootstrap/startup ordering and signal handler placement in src/main.ts.
• Verify migrateDb() uses drizzle migrator API and correct migrationsFolder path.
• Confirm DB_AUTO_MIGRATE parsing and default in src/common/config.ts.
• Check Docker service/volume rename doesn’t break external integrations.
• Validate logger transport change (includes test) and child logger usage.

Poem

🐇 I nibbled at the schema bright,

hopped through migrations in the night,
DB_AUTO_MIGRATE gave me a clue,
Postgres renamed — a tidy view,
Now servers wake with logs that light.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objectives: adding automatic database migrations and error handling, which are the primary changes throughout the codebase.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docker-compose.yml (1)

13-37: Fix DATABASE_URL hostname after Postgres service rename

You renamed the Postgres service to elysia-boilerplate-postgres, but DATABASE_URL still points to @postgres:5432. In a default Compose network, the hostname must match the service name, so the app will fail to connect to the DB in this setup.

Recommend updating the hostname:

-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/elysia-boilerplate
+      DATABASE_URL: postgresql://postgres:postgres@elysia-boilerplate-postgres:5432/elysia-boilerplate

The rest of the changes (healthcheck tweaks, volume rename, depends_on) look good and improve clarity/reliability.

🧹 Nitpick comments (2)

.env.example (1)

15-16: Mirror the safety warning from config.ts for DB_AUTO_MIGRATE

The DB_AUTO_MIGRATE flag is exposed here (good), but the comment is quite minimal compared to the detailed caution in src/common/config.ts. To reduce the risk of someone blindly enabling this in production, consider expanding the comment:

-# Enable migrations on server startup
-DB_AUTO_MIGRATE=false
+# Enable automatic database migrations on server startup
+# ⚠️ CAUTION:
+# - Keep this disabled in production; run migrations via CI/CD instead.
+# - Useful to enable in development/staging for convenience.
+# - If migrations fail on startup, the server will NOT start.
+DB_AUTO_MIGRATE=false

This keeps the docs consistent and makes the behavior explicit right where people tend to copy env vars from.

src/modules/users/index.ts (1)

2-7: Module-scoped child logger for users looks good

Using a users-scoped child logger is a solid improvement for log filtering and aligns with pino's recommended patterns for stable contextual fields. Existing log handlers remain behaviorally unchanged.

Consider adopting structured logging with object-first pattern: log.info({ total: users.total }, 'Got users') rather than string interpolation. This keeps logs queryable, improves performance (especially when log level is disabled), and leverages pino's strength in structured field aggregation and filtering.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8ca8669 and aa63dc2.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• .env.example (1 hunks)
• CHANGELOG.md (1 hunks)
• docker-compose.yml (3 hunks)
• package.json (2 hunks)
• src/common/config.ts (2 hunks)
• src/db/index.ts (2 hunks)
• src/main.ts (2 hunks)
• src/modules/users/index.ts (1 hunks)
• src/util/graceful-shutdown.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

src/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.{ts,tsx,js,jsx}: Strictly follow Biome linter rules and run bun run lint:fix to auto-fix issues
Use explicit imports instead of wildcard imports

Files:

• src/common/config.ts
• src/util/graceful-shutdown.ts
• src/modules/users/index.ts
• src/db/index.ts
• src/main.ts

src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.{ts,tsx}: TypeScript strict mode is enabled. Do not use any types unless absolutely necessary
Use src/common/config.ts for environment variables with Envalid. Do not use process.env directly
All new features must include unit/integration tests

Files:

• src/common/config.ts
• src/util/graceful-shutdown.ts
• src/modules/users/index.ts
• src/db/index.ts
• src/main.ts

🧠 Learnings (2)

📚 Learning: 2025-11-27T13:14:34.782Z

Learnt from: CR
Repo: truehazker/elysia-boilerplate PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-27T13:14:34.782Z
Learning: Applies to src/**/*.{ts,tsx} : Use `src/common/config.ts` for environment variables with Envalid. Do not use `process.env` directly

Applied to files:

• src/common/config.ts

📚 Learning: 2025-11-27T13:14:34.782Z

Learnt from: CR
Repo: truehazker/elysia-boilerplate PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-27T13:14:34.782Z
Learning: Applies to src/db/schema/**/*.{ts,tsx} : Generate migrations after modifying schema in `src/db/schema` by running `bun run db:generate`

Applied to files:

• src/db/index.ts

🧬 Code graph analysis (4)

src/util/graceful-shutdown.ts (1)

src/common/logger.ts (1)

• log (4-19)

src/modules/users/index.ts (1)

src/common/logger.ts (1)

• log (4-19)

src/db/index.ts (1)

src/common/logger.ts (1)

• log (4-19)

src/main.ts (3)

src/db/index.ts (1)

• migrateDb (20-24)

src/common/logger.ts (1)

• log (4-19)

src/util/graceful-shutdown.ts (1)

• gracefulShutdown (9-37)

🔇 Additional comments (6)

CHANGELOG.md (1)

8-18: Changelog updates align well with the new behavior

The Unreleased entries for automatic migrations, migration error handling, and dependency updates accurately reflect the scope of this PR and match the existing changelog structure.

src/common/config.ts (1)

1-24: DB_AUTO_MIGRATE config is well-integrated and safely defaulted

Using bool({ default: false }) with a clear cautionary comment is exactly the right pattern here, and it respects the guideline of centralizing env access through config instead of process.env. The envalid bool() validator accepts "1", "0", "true", "false", "t", and "f" as string tokens, so deployment manifests can safely use any of these standard boolean representations.

src/util/graceful-shutdown.ts (1)

1-6: This review comment is obsolete. The code in src/util/graceful-shutdown.ts already implements the suggested refactor with const log = logger.child({ name: 'graceful-shutdown' }), consistent with other modules in the codebase (db, users). Pino best practices support this approach for stable module-level context. No action required.

Likely an incorrect or invalid review comment.

package.json (1)

29-41: Dependency bumps look consistent; confirm compatibility via install and lint

The drizzle-orm, elysia, and drizzle-kit minor bumps are reasonable and consistent with the stack. Please run bun install and bun run lint to confirm no regressions (especially around migrations and app bootstrap). Note: this project has no test script configured.

#!/bin/bash
bun install
bun run lint

src/main.ts (2)

6-6: LGTM!

The import is explicit and correctly references the migration function used in the bootstrap process.

---

83-86: LGTM!

The error handling correctly prevents the server from starting if migrations or initialization fail. Using log.fatal with the error object and exiting with code 1 provides clear diagnostics for debugging startup issues.