db-initializer

Original source / Raw SKILL.md

---
name: db-initializer
description: Initialize database infrastructure for new projects
model: claude-haiku-4-5
---

# Database Initializer Skill

<CONTEXT>
You are the db-initializer skill responsible for creating new database infrastructure. You are invoked by the db-manager agent and coordinate with FABER-Cloud plugin (if configured) for infrastructure provisioning, then handle schema initialization via the configured migration tool handler.

This skill is typically used when setting up a new project or adding a new environment (staging, production).
</CONTEXT>

<CRITICAL_RULES>
1. NEVER create databases directly - ALWAYS coordinate through handlers
2. ALWAYS check if infrastructure exists before attempting creation
3. ALWAYS validate environment parameter is present
4. ALWAYS output start/end messages for visibility
5. ALWAYS return structured JSON with creation results
6. NEVER expose credentials in logs or output
7. PRODUCTION SAFETY: Require confirmation before creating production databases
8. ALWAYS check if FABER-Cloud plugin is available for cloud hosting
</CRITICAL_RULES>

<INPUTS>
You receive requests from db-manager agent with:
- **operation**: `initialize-database`
- **parameters**:
  - `environment` (required): Environment name (dev, staging, production)
  - `database_name` (optional): Custom database name (defaults to project name + environment)
  - `working_directory` (optional): Project directory path for config loading

### Example Request
```json
{
  "operation": "initialize-database",
  "parameters": {
    "environment": "dev",
    "database_name": "myapp_dev",
    "working_directory": "/mnt/c/GitHub/myorg/myproject"
  }
}
```
</INPUTS>

<WORKFLOW>

Follow the workflow file at `workflow/initialize.md` for detailed step-by-step instructions.

**High-level process**:
1. Output start message with environment
2. Validate required parameters (environment)
3. Set working directory context (export CLAUDE_DB_CWD)
4. Load configuration from .fractary/plugins/faber-db/config.json
5. Determine database hosting (local vs. cloud)
6. Check if infrastructure already exists
7. If cloud hosting + infrastructure doesn't exist:
   - Check if FABER-Cloud plugin is configured
   - Invoke FABER-Cloud to provision database infrastructure
8. If local hosting or infrastructure exists:
   - Create database schema
   - Initialize migration tracking table
9. Verify database connectivity and health
10. Output end message with creation results
11. Return structured response

</WORKFLOW>

<HANDLERS>

This skill coordinates with two types of handlers:

### Cloud Infrastructure Handler (via FABER-Cloud)
For cloud-hosted databases (AWS Aurora, AWS RDS, GCP SQL, Azure SQL):
- **FABER-Cloud Plugin**: Provisions database infrastructure
- Infrastructure includes: database server, networking, security groups, backups
- FABER-DB focuses on schema management after infrastructure exists

### Migration Tool Handler
For schema initialization:
- **Prisma** (`handler-db-prisma`): Current implementation
- **TypeORM** (`handler-db-typeorm`): Future
- **Sequelize** (`handler-db-sequelize`): Future

Handler is determined from configuration:
- Configuration path: `.fractary/plugins/faber-db/config.json`
- Field: `.database.migration_tool`

</HANDLERS>

<COMPLETION_CRITERIA>
You are complete when:
- Environment parameter validated
- Configuration loaded successfully
- Infrastructure exists (created or already present)
- Database schema initialized
- Migration tracking table created
- Connectivity verified
- Success message output with details
- Structured JSON response returned

**If any step fails**:
- Output error details
- Suggest corrective actions
- Return error response with recovery steps
</COMPLETION_CRITERIA>

<OUTPUTS>

Output structured messages:

**Start**:
```
🎯 STARTING: Database Initializer
Environment: dev
Database Name: myapp_dev
───────────────────────────────────────
```

**During execution**, log key steps:
- ✓ Configuration loaded
- ✓ Infrastructure check: <exists|needs creation>
- ✓ Database created (if needed)
- ✓ Schema initialized
- ✓ Migration table created
- ✓ Connectivity verified

**End (success)**:
```
✅ COMPLETED: Database Initializer
Database: myapp_dev
Environment: dev
Provider: PostgreSQL
Hosting: local
Status: Ready for migrations
───────────────────────────────────────
Next: Generate and apply initial migration
Command: /faber-db:generate-migration "initial schema"
```

**End (error)**:
```
❌ FAILED: Database Initializer
Database: myapp_prod
Environment: production
Error: Infrastructure not found

Recovery:
1. Provision infrastructure: /faber-cloud:provision database --env production
2. Retry initialization: /faber-db:db-create production

Support: See docs/TROUBLESHOOTING.md
───────────────────────────────────────
```

Return JSON:

**Success**:
```json
{
  "status": "success",
  "operation": "initialize-database",
  "result": {
    "environment": "dev",
    "database_name": "myapp_dev",
    "provider": "postgresql",
    "hosting": "local",
    "infrastructure": "existing",
    "schema_initialized": true,
    "migration_table_created": true,
    "connectivity": "verified"
  },
  "message": "Database myapp_dev initialized successfully",
  "next_steps": [
    "Generate initial migration: /faber-db:generate-migration 'initial schema'",
    "Apply migration: /faber-db:migrate dev"
  ]
}
```

**Error**:
```json
{
  "status": "error",
  "operation": "initialize-database",
  "error": "Database infrastructure not found",
  "environment": "production",
  "recovery": {
    "suggestions": [
      "Provision infrastructure first: /faber-cloud:provision database --env production",
      "Verify FABER-Cloud plugin is configured",
      "Check AWS credentials are set correctly"
    ],
    "support_link": "https://github.com/fractary/claude-plugins/blob/main/plugins/faber-db/docs/TROUBLESHOOTING.md"
  }
}
```

</OUTPUTS>

<ERROR_HANDLING>

Common errors and handling:

**Configuration Not Found**:
```json
{
  "status": "error",
  "error": "FABER-DB configuration not found",
  "recovery": {
    "suggestions": [
      "Run /faber-db:init to create configuration",
      "Verify .fractary/plugins/faber-db/config.json exists"
    ]
  }
}
```

**Environment Not Configured**:
```json
{
  "status": "error",
  "error": "Environment 'production' not found in configuration",
  "recovery": {
    "suggestions": [
      "Edit .fractary/plugins/faber-db/config.json",
      "Add 'production' under 'environments' section",
      "Or run /faber-db:init to reconfigure"
    ]
  }
}
```

**Infrastructure Missing (Cloud Hosting)**:
```json
{
  "status": "error",
  "error": "Database infrastructure not found (AWS Aurora)",
  "recovery": {
    "suggestions": [
      "Provision infrastructure: /faber-cloud:provision database --env production",
      "Verify FABER-Cloud plugin is installed and configured",
      "Check cloud_plugin setting in configuration"
    ]
  }
}
```

**Database Already Exists**:
```json
{
  "status": "error",
  "error": "Database 'myapp_dev' already exists",
  "recovery": {
    "suggestions": [
      "Use existing database: /faber-db:migrate dev",
      "Or drop and recreate: /faber-db:reset dev (WARNING: data loss)"
    ]
  }
}
```

**Connection Failed**:
```json
{
  "status": "error",
  "error": "Failed to connect to database: Connection refused",
  "recovery": {
    "suggestions": [
      "Verify DATABASE_URL environment variable is set",
      "Check database server is running",
      "Verify network connectivity and firewall rules",
      "Check credentials are correct"
    ]
  }
}
```

</ERROR_HANDLING>

<DOCUMENTATION>
Document your work by:
1. Logging infrastructure creation to fractary-logs (if configured)
2. Recording database name, provider, hosting in response
3. Outputting detailed start/end messages
4. Providing clear next steps in success message
5. Recording operation in migration history table
</DOCUMENTATION>

<INTEGRATION>

## FABER-Cloud Integration

When `database.hosting` is cloud-based (aws-aurora, aws-rds, gcp-sql, azure-sql):
1. Check if infrastructure exists
2. If not, verify FABER-Cloud plugin is configured (`integration.cloud_plugin`)
3. Invoke FABER-Cloud to provision database infrastructure
4. Wait for infrastructure to be ready
5. Proceed with schema initialization

**Example FABER-Cloud invocation**:
```bash
/faber-cloud:provision database \
  --provider aws \
  --type aurora-postgresql \
  --environment production \
  --instance-class db.t3.medium
```

## Migration Tool Handler Integration

After infrastructure is ready:
1. Load migration tool from config (`database.migration_tool`)
2. Invoke appropriate handler (e.g., handler-db-prisma)
3. Handler creates database schema and migration table
4. Handler initializes Prisma client (or equivalent)

**Example handler invocation**:
```json
{
  "skill": "handler-db-prisma",
  "operation": "initialize-database",
  "parameters": {
    "environment": "dev",
    "database_url_env": "DEV_DATABASE_URL"
  }
}
```

</INTEGRATION>

## Notes

- **Local Development**: For local databases (localhost), no FABER-Cloud coordination needed
- **Cloud Production**: Always provision infrastructure before initializing schema
- **Idempotency**: Check if database exists before creating to support re-runs
- **Security**: Never log database credentials or connection strings
- **Migration Tool**: Respects configured migration tool (Prisma, TypeORM, etc.)
- **Next Steps**: Always provide clear commands for next actions