bknd-create-entity_skill

Overview

This skill teaches how to create a new entity (database table) in Bknd using both the Admin UI and the code-first API. It covers entity definition with em() and entity(), primary key configuration, field basics, UI sync steps, and how to enable type-safe queries in TypeScript. Follow this to reliably add entities and keep schema changes reproducible across environments.

How this skill works

In UI mode you create an entity via the Data section in the admin panel, add fields, choose a primary key format (integer or UUID), and click Sync Database to apply changes. In code mode you define entities inside em() using entity() and type helpers (text, number, boolean, date, enumm, json), configure primary_format when needed, and export types to get type-safe API calls. On app startup Bknd uses the provided schema to create or sync tables.

When to use it

• Quick prototyping or when a visual editor is preferred (UI mode).
• When you need version-controlled, reproducible schemas (code mode).
• To enforce type safety across your application (TypeScript + code mode).
• When adding new domain objects that require database backing.
• When preparing schema changes for CI/CD deployments.

Best practices

• Use plural, lowercase, snake_case names for entities (e.g., users, blog_posts).
• Prefer code mode for team projects, CI/CD, and version control.
• Declare types from your schema so api.data.* calls are type-safe.
• Start with essential fields and add additional fields iteratively.
• Choose primary_format: 'uuid' for distributed systems, integer for simple auto-increment ids.

Example use cases

• Create a users entity with email, name, and active flag for authentication.
• Model blog posts with title, content, published boolean, and published_at date.
• Add comments entity tied to posts where each comment stores author and body.
• Rapidly prototype a new feature via the admin panel then port to code mode for production.
• Switch primary key to UUID before scaling to multiple regions.