DB Initializer

Database Initializer Skill

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

Example Request

{
  "operation": "initialize-database",
  "parameters": {
    "environment": "dev",
    "database_name": "myapp_dev",
    "working_directory": "/mnt/c/GitHub/myorg/myproject"
  }
}

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

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

If any step fails:

• Output error details
• Suggest corrective actions
• Return error response with recovery steps

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:

{
  "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:

{
  "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"
  }
}

Common errors and handling:

Configuration Not Found:

{
  "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:

{
  "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):

{
  "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:

{
  "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:

{
  "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"
    ]
  }
}

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:

/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:

{
  "skill": "handler-db-prisma",
  "operation": "initialize-database",
  "parameters": {
    "environment": "dev",
    "database_url_env": "DEV_DATABASE_URL"
  }
}

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