@breadstone/archipel-mcp 0.0.13 → 0.0.15

package/data/guides/database-setup.md

@@ -1,546 +0,0 @@
----
-title: Database Setup
-description: Set up PostgreSQL access with Prisma, Prisma Accelerate, repositories, queries, transactions, health checks, and error handling.
-order: 5
----
-
-# Database Setup
-
-This guide covers everything you need to connect a NestJS application to PostgreSQL through `platform-database`: module registration, Prisma Accelerate for connection pooling, writing repositories and queries, transactions, pagination, health checks, and error handling.
-
-If you haven't installed `platform-core` and registered `ConfigModule` yet, read the [Getting Started](/guides/getting-started) guide first.
-
----
-
-## Overview
-
-`platform-database` provides:
-
-| Capability                | What it does                                                                       |
-| ------------------------- | ---------------------------------------------------------------------------------- |
-| **DatabaseModule**        | Registers Prisma-backed services for DI with optional Accelerate support           |
-| **DatabaseService**       | Extended Prisma client with transaction helpers                                    |
-| **RepositoryBase**        | Abstract base class for typed repositories with built-in error handling            |
-| **Query pattern**         | Reusable, testable query objects executed through repositories                     |
-| **Transactional queries** | Multi-model writes wrapped in Prisma transactions                                  |
-| **Pagination**            | Offset-based pagination with metadata (total, pages, next/prev)                    |
-| **Health indicator**      | Terminus-based database health check, auto-registered with the health orchestrator |
-| **Exception filter**      | Maps `RepositoryError` to HTTP 500 responses                                       |
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-database
-```
-
-`platform-database` depends on `@prisma/client`. Make sure your project has a Prisma schema and a generated client:
-
-```bash
-yarn add prisma @prisma/client
-npx prisma init
-```
-
----
-
-## Environment Variables
-
-`platform-database` ships its own config keys and a ready-made entries array. Set the relevant variables in your environment:
-
-```env
-DATABASE_URL=postgresql://user:password@localhost:5432/mydb
-```
-
-For Prisma Accelerate (managed connection pooling), add the Accelerate URL from the Prisma Console:
-
-```env
-DB_ACCELERATE_URL=prisma://accelerate.prisma-data.net/?api_key=your-accelerate-api-key
-```
-
-Optional environment variables for Prisma Optimize (query analysis dashboard):
-
-```env
-DB_OPTIMIZE=true
-DB_OPTIMIZE_API_KEY=your-optimize-api-key
-```
-
-All environment variables recognised by `platform-database`:
-
-| Variable              | Description                               | Required            | Default |
-| --------------------- | ----------------------------------------- | ------------------- | ------- |
-| `DATABASE_URL`        | PostgreSQL connection string              | Yes                 | —       |
-| `DB_ACCELERATE_URL`   | Prisma Accelerate proxy URL               | No                  | `''`    |
-| `DB_AUTO_CONNECTION`  | Auto-connect on module init               | No                  | `true`  |
-| `DB_OPTIMIZE`         | Enable Prisma Optimize query analysis     | No                  | `true`  |
-| `DB_OPTIMIZE_API_KEY` | API key for the Prisma Optimize dashboard | If optimize enabled | `''`    |
-
-### Register Config Entries
-
-Use the exported `PLATFORM_DATABASE_CONFIG_ENTRIES` to register all database keys with the `ConfigModule` — no need to define them manually:
-
-```typescript
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
-
-@Module({
-  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.register()],
-})
-export class AppModule {}
-```
-
-The `ConfigModule` validates all required keys at startup. If `DATABASE_URL` is missing, the application fails immediately with a clear error.
-
----
-
-## Module Registration
-
-### Basic Setup (No Accelerate)
-
-For a direct PostgreSQL connection without Accelerate:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
-
-@Module({
-  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.register()],
-})
-export class AppModule {}
-```
-
-### With Prisma Accelerate
-
-Accelerate provides connection pooling, global caching, and query optimization — especially useful in serverless or edge environments where direct database connections are expensive. You can enable it in two ways:
-
-**Option A — Environment variable (recommended)**
-
-Set `DB_ACCELERATE_URL` in your environment. The module reads it automatically via `ConfigService` — no code changes needed:
-
-```env
-DB_ACCELERATE_URL=prisma://accelerate.prisma-data.net/?api_key=your-accelerate-api-key
-```
-
-```typescript
-@Module({
-  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.register()],
-})
-export class AppModule {}
-```
-
-**Option B — Module parameter (takes priority)**
-
-Pass `accelerateUrl` explicitly. This overrides the environment variable:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
-
-@Module({
-  imports: [
-    ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES),
-    DatabaseModule.register({
-      accelerateUrl: 'prisma://accelerate.prisma-data.net/?api_key=...',
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-When an Accelerate URL is present (from either source), the Prisma client connects through the Accelerate proxy instead of directly to PostgreSQL. The `DATABASE_URL` is still required — Prisma uses it for schema generation and migrations. At runtime, all queries go through the Accelerate URL.
-
-> **Resolution order:** module parameter → `DB_ACCELERATE_URL` environment variable → no Accelerate.
-
-### Global Registration with `forRoot`
-
-Use `forRoot()` to make `DatabaseService` globally available without re-importing the module in every feature module:
-
-```typescript
-@Module({
-  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.forRoot()],
-})
-export class AppModule {}
-```
-
-With `forRoot()`, any module can inject `DatabaseService` without adding `DatabaseModule` to its own `imports`. Accelerate resolution works the same way — via environment variable or explicit `forRoot({ accelerateUrl: '...' })`.
-
----
-
-## Defining Entities
-
-Define entity interfaces that map to your Prisma models. Entity property names must match your Prisma schema exactly:
-
-```typescript
-// src/users/models/entities/IUserEntity.ts
-export interface IUserEntity {
-  readonly id: string;
-  readonly userName: string;
-  readonly email: string;
-  readonly createdAt: Date;
-}
-```
-
-Entities are plain interfaces — no methods, no business logic, no mapping. They are the contract between repositories and services.
-
----
-
-## Writing Queries
-
-Queries are plain objects created with the `query()` factory. Each query receives a Prisma delegate and returns a typed result. This keeps data access logic reusable, testable, and separate from repository class methods.
-
-### Single-Model Query
-
-```typescript
-// src/users/queries/findUserByIdQuery.ts
-import { query, type IRepositoryQuery } from '@breadstone/archipel-platform-database';
-import { type Prisma } from '@prisma/client';
-import { type IUserEntity } from '../models/entities/IUserEntity';
-
-type UserDelegate = Prisma.UserDelegate;
-
-export const findUserByIdQuery = (id: string): IRepositoryQuery<UserDelegate, IUserEntity | null> =>
-  query('findUserById', (model) =>
-    model.findUnique({
-      where: { id },
-      select: { id: true, userName: true, email: true, createdAt: true },
-    }),
-  );
-```
-
-### Transactional Query
-
-When a write spans multiple models, use `transactionalQuery()`. It receives a Prisma `TransactionClient` instead of a single delegate:
-
-```typescript
-// src/orders/queries/createOrderWithItemsQuery.ts
-import { transactionalQuery } from '@breadstone/archipel-platform-database';
-
-export const createOrderWithItemsQuery = (userId: string, items: Array<{ productId: string; quantity: number }>) =>
-  transactionalQuery('createOrderWithItems', async (tx) => {
-    const order = await tx.order.create({
-      data: { userId, status: 'pending' },
-    });
-
-    await tx.orderItem.createMany({
-      data: items.map((item) => ({
-        orderId: order.id,
-        productId: item.productId,
-        quantity: item.quantity,
-      })),
-    });
-
-    return order;
-  });
-```
-
----
-
-## Creating Repositories
-
-Repositories extend `RepositoryBase` and execute queries. They receive `DatabaseService` and the Prisma delegate via constructor injection.
-
-```typescript
-// src/users/UserRepository.ts
-import { Injectable } from '@nestjs/common';
-import { RepositoryBase, DatabaseService } from '@breadstone/archipel-platform-database';
-import { type Prisma } from '@prisma/client';
-import { findUserByIdQuery } from './queries/findUserByIdQuery';
-import { type IUserEntity } from './models/entities/IUserEntity';
-
-@Injectable()
-export class UserRepository extends RepositoryBase<
-  Prisma.UserDelegate,
-  Prisma.UserArgs,
-  Prisma.UserGetPayload<unknown>,
-  IUserEntity
-> {
-  constructor(db: DatabaseService) {
-    super(db, db.user);
-  }
-
-  public async findById(id: string): Promise<IUserEntity | null> {
-    return this.execute(findUserByIdQuery(id));
-  }
-}
-```
-
-### Executing Transactional Queries
-
-Use `executeTransactional()` for queries that need a transaction client:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { RepositoryBase, DatabaseService } from '@breadstone/archipel-platform-database';
-import { type Prisma } from '@prisma/client';
-import { createOrderWithItemsQuery } from './queries/createOrderWithItemsQuery';
-
-@Injectable()
-export class OrderRepository extends RepositoryBase<
-  Prisma.OrderDelegate,
-  Prisma.OrderArgs,
-  Prisma.OrderGetPayload<unknown>
-> {
-  constructor(db: DatabaseService) {
-    super(db, db.order);
-  }
-
-  public async createWithItems(
-    userId: string,
-    items: Array<{ productId: string; quantity: number }>,
-  ): Promise<unknown> {
-    return this.executeTransactional(createOrderWithItemsQuery(userId, items));
-  }
-}
-```
-
----
-
-## Pagination
-
-`platform-database` provides offset-based pagination. Pass page options to `findMany()`:
-
-```typescript
-import { type IPaginatedResult } from '@breadstone/archipel-platform-database';
-
-public async listUsers(page: number, perPage: number): Promise<IPaginatedResult<IUserEntity>> {
-  return this.findMany(
-    {
-      select: { id: true, userName: true, email: true, createdAt: true },
-      orderBy: { createdAt: 'desc' },
-    },
-    { page, perPage },
-  );
-}
-```
-
-The result contains:
-
-```typescript
-{
-  data: Array<T>;
-  meta: {
-    total: number;
-    lastPage: number;
-    currentPage: number;
-    perPage: number;
-    prev: number | null;
-    next: number | null;
-  }
-}
-```
-
----
-
-## Transactions via DatabaseService
-
-For ad-hoc transactions that don't fit the query pattern, use `DatabaseService` directly:
-
-### Batch Transaction
-
-```typescript
-const [user, profile] = await this._db.transaction([
-  this._db.user.create({ data: { userName: 'alice', email: 'alice@example.com' } }),
-  this._db.profile.create({ data: { userId: 'some-id', bio: 'Hello' } }),
-]);
-```
-
-### Callback Transaction
-
-```typescript
-const result = await this._db.transactionCallback(async (tx) => {
-  const user = await tx.user.create({ data: { userName: 'bob', email: 'bob@example.com' } });
-  await tx.profile.create({ data: { userId: user.id, bio: 'Hey there' } });
-  return user;
-});
-```
-
----
-
-## Health Checks
-
-`DatabaseModule` automatically registers a `DatabaseHealthIndicator` with the health orchestrator from `platform-core`. Once your application exposes a `/health` endpoint, database connectivity is checked via a `SELECT 1` ping. No additional configuration is needed.
-
-If the health check fails, the indicator reports `database: down` with the error details.
-
----
-
-## Error Handling
-
-### RepositoryError
-
-All Prisma errors caught by `RepositoryBase` are wrapped in `RepositoryError`, which includes the original Prisma error code and metadata:
-
-```typescript
-import { RepositoryError } from '@breadstone/archipel-platform-database';
-
-try {
-  await userRepository.findById('non-existent');
-} catch (error) {
-  if (error instanceof RepositoryError) {
-    console.log(error.code); // 'REPOSITORY_ERROR'
-    console.log(error.originalCode); // e.g. 'P2025' (Prisma error code)
-    console.log(error.meta); // additional error metadata
-  }
-}
-```
-
-### RepositoryExceptionFilter
-
-Register the global exception filter to automatically map `RepositoryError` to HTTP 500 responses:
-
-```typescript
-import { APP_FILTER } from '@nestjs/core';
-import { RepositoryExceptionFilter } from '@breadstone/archipel-platform-database';
-
-@Module({
-  providers: [
-    {
-      provide: APP_FILTER,
-      useClass: RepositoryExceptionFilter,
-    },
-  ],
-})
-export class AppModule {}
-```
-
-The filter returns a consistent error envelope:
-
-```json
-{
-  "statusCode": 500,
-  "timestamp": "2026-04-18T12:00:00.000Z",
-  "error": "Repository Error",
-  "path": "/api/v1/users/123"
-}
-```
-
----
-
-## Prisma Schema and Migrations
-
-Keep your Prisma schema in your project and use migrations for all schema changes:
-
-```bash
-# Create a new migration after changing schema.prisma
-npx prisma migrate dev --name add-users-table
-
-# Apply migrations in CI/CD
-npx prisma migrate deploy
-
-# Generate the Prisma client after schema changes
-npx prisma generate
-```
-
-> **Important:** Never edit applied migrations. If you need to fix a migration, create a new one.
-
-When using Accelerate, migrations still run against the direct `DATABASE_URL`. Only runtime queries go through the Accelerate proxy.
-
----
-
-## Full Example
-
-Putting it all together — a complete feature module with database access:
-
-```typescript
-// src/users/UserModule.ts
-import { Module } from '@nestjs/common';
-import { UserRepository } from './UserRepository';
-import { UserService } from './UserService';
-import { UserController } from './UserController';
-
-@Module({
-  providers: [UserRepository, UserService],
-  controllers: [UserController],
-  exports: [UserService],
-})
-export class UserModule {}
-```
-
-```typescript
-// src/users/UserService.ts
-import { Injectable } from '@nestjs/common';
-import { UserRepository } from './UserRepository';
-import { type IUserEntity } from './models/entities/IUserEntity';
-
-@Injectable()
-export class UserService {
-  private readonly _userRepository: UserRepository;
-
-  constructor(userRepository: UserRepository) {
-    this._userRepository = userRepository;
-  }
-
-  public async getUserById(id: string): Promise<IUserEntity | null> {
-    return this._userRepository.findById(id);
-  }
-}
-```
-
-```typescript
-// src/users/UserController.ts
-import { Controller, Get, Param, NotFoundException } from '@nestjs/common';
-import { UserService } from './UserService';
-import { MappingService } from '@breadstone/archipel-platform-core';
-import { USER_TO_RESPONSE } from './mapping-keys';
-
-@Controller('users')
-export class UserController {
-  private readonly _userService: UserService;
-  private readonly _mappingService: MappingService;
-
-  constructor(userService: UserService, mappingService: MappingService) {
-    this._userService = userService;
-    this._mappingService = mappingService;
-  }
-
-  @Get(':id')
-  public async getUser(@Param('id') id: string): Promise<unknown> {
-    const user = await this._userService.getUserById(id);
-    if (!user) {
-      throw new NotFoundException(`User ${id} not found`);
-    }
-
-    return this._mappingService.map(USER_TO_RESPONSE, user);
-  }
-}
-```
-
-And the root module wiring everything together:
-
-```typescript
-// src/app.module.ts
-import { Module } from '@nestjs/common';
-import { ConfigModule, MappingModule } from '@breadstone/archipel-platform-core';
-import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
-import { UserModule } from './users/UserModule';
-
-@Module({
-  imports: [
-    ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES),
-    MappingModule,
-    DatabaseModule.forRoot(),
-    UserModule,
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Summary
-
-| Task                    | How                                                                                |
-| ----------------------- | ---------------------------------------------------------------------------------- |
-| Register the module     | `DatabaseModule.register()` or `DatabaseModule.forRoot()` with optional Accelerate |
-| Define entities         | Plain interfaces in `models/entities/`                                             |
-| Write queries           | `query()` for single-model, `transactionalQuery()` for multi-model                 |
-| Create repositories     | Extend `RepositoryBase`, inject `DatabaseService`                                  |
-| Paginate results        | Pass `{ page, perPage }` to `findMany()`                                           |
-| Run transactions        | `executeTransactional()`, `db.transaction()`, or `db.transactionCallback()`        |
-| Monitor database health | Automatic via `DatabaseHealthIndicator`                                            |
-| Handle errors           | `RepositoryExceptionFilter` for HTTP, `RepositoryError` for programmatic handling  |
-| Use Prisma Accelerate   | Set `DB_ACCELERATE_URL` env var or pass `accelerateUrl` in module config           |