bknd-modify-schema_skill

Overview

This skill helps you modify an existing Bknd schema safely and predictably. It covers renaming entities and fields, changing field types and constraints, handling destructive vs non-destructive changes, and the recommended sync and migration workflow. Follow the guidance to avoid accidental data loss and maintain reproducible deployments.

How this skill works

The skill inspects differences between your code-mode schema and the live database and classifies changes as safe (additive or loosening constraints) or destructive (renames, drops, type-tightening). It guides you through safe patterns: add-new-then-migrate for renames or type changes, run preview dry-runs with npx bknd sync, and apply force or drop flags only after backups and validation. It includes migration script templates and verification steps to confirm success.

When to use it

• Renaming an entity or field while preserving data
• Changing a field type that risks incompatible data conversion
• Tightening constraints (making fields required or unique) in production
• Preparing a schema change for team review and version control
• Debugging sync failures due to constraint or type issues

Best practices

• Always back up the database before any destructive operation
• Prefer code mode for production changes and version control
• Preview changes with npx bknd sync before applying --force
• Migrate data by adding new fields/entities, copying data, then removing old ones
• Resolve nulls or duplicates before adding required or unique constraints

Example use cases

• Rename posts to articles: add articles entity, migrate records, remove posts, then sync with --force
• Change price from text to integer cents: add price_cents, convert values with a script, drop old price
• Make email required: update all null emails to defaults, then add .required() and sync
• Add a unique username constraint: find and resolve duplicates, then add .unique()
• Interactive prototype: use UI mode for quick schema edits when data loss is acceptable