Entity Management

Sonamu UI’s Entity management feature allows you to easily create and edit Entities through a visual interface. It’s much faster and more intuitive than directly modifying files via CLI.

Entity Tab Structure

The Entity tab consists of two main areas:

Left Sidebar: Entity list and new Entity add button
Right Content: Selected Entity details (Properties, Indexes, Relations, Subsets, Enums)

Creating an Entity

1. Click New Entity Button

Click the [+ New Entity] button at the bottom of the sidebar.

2. Enter Entity Information

When the modal opens, enter the following information:

Field	Description	Example
Entity ID	Entity identifier (PascalCase)	`Product`, `OrderItem`
Title	Display title	`Product`, `Order Item`
Parent Entity	Parent Entity (optional)	`Order`

If you specify a Parent Entity, it becomes a child of that Entity. Example: Order → OrderItem

3. Add Basic Properties

Created Entities include these basic fields by default:

{
  "props": [
    { "name": "id", "type": "integer", "desc": "ID" },
    { "name": "created_at", "type": "date", "desc": "등록일시", "dbDefault": "CURRENT_TIMESTAMP" }
  ]
}

Editing Properties

Adding a Property

Click [+ Add Property] button
Enter Property information:

Field	Required	Description	Example
Name	✅	Field name (snake_case)	`email`, `phone_number`
Type	✅	Data type	`string`, `integer`, `numeric`
Length	Conditional	String length	`255`
Nullable		Allow NULL	`true`
DB Default		Database default value	`0`, `CURRENT_TIMESTAMP`
Description		Description	`User email`

Supported data types:

String: string (falls back to text without a length), uuid, searchText
Number: integer, bigInteger, number, numeric (precision/scale)
Date: date
Other: boolean, enum, json, virtual, vector, tsvector, relation

Most scalar types also have an array form such as integer[] or string[]. See Field Types for the full list.

Editing a Property

Click on a Property row to enter edit mode
Modify values
Click elsewhere or press Enter to save

Deleting a Property

Click the [×] button on the Property row.

Data loss warning: Deleting a Property will delete all data in that column. Make sure to backup data before running the migration.

Managing Indexes

Adding an Index

Scroll to the Indexes section
Click [+ Add Index] button
Enter Index information:

Field	Description	Example
Target Columns	Index target fields (multiple selectable)	`email`, `created_at`
Type	Index type	`index`, `unique`, `hnsw`, `ivfflat`
Where	Raw SQL predicate for partial indexes	`deleted_at IS NULL`

Index types:

index: Regular index (improves search performance)
unique: Unique index (prevents duplicates)
hnsw / ivfflat: pgvector vector indexes

Full-text search is not a separate index type. Use a searchText/tsvector prop together with the using: "gin" option — see pgvector setup.

Composite Index

Select multiple fields to create a composite index:

{
  "indexes": [
    {
      "type": "index",
      "name": "posts_user_id_created_at_index",
      "columns": [{ "name": "user_id" }, { "name": "created_at" }]
    },
    { "type": "unique", "name": "users_email_unique", "columns": [{ "name": "email" }] },
    {
      "type": "unique",
      "name": "users_email_active_unique",
      "columns": [{ "name": "email" }],
      "where": "deleted_at IS NULL"
    }
  ]
}

where is emitted as a PostgreSQL partial index predicate. Treat it as raw SQL: do not build it from user input.

Managing Relations

belongsTo (N:1 Relationship)

Meaning: “This Entity belongs to another Entity” Example: Post belongs to User

Click [+ Add] button in the belongsTo section
Enter information:

Field	Description	Example
Entity	Entity to reference	`User`
As	Relation alias	`author`
Foreign Key	Foreign key field name (optional)	`author_id`

Generated code:

{
  "type": "relation",
  "name": "author",
  "relationType": "BelongsToOne",
  "with": "User",
  "onUpdate": "CASCADE",
  "onDelete": "CASCADE",
  "desc": "Author"
}

hasMany (1:N Relationship)

Meaning: “This Entity has multiple of another Entity” Example: User has multiple Posts

Click [+ Add] button in the hasMany section
Enter information:

Field	Description	Example
Entity	Target Entity	`Post`
As	Relation alias	`posts`

Generated code:

{
  "type": "relation",
  "name": "posts",
  "relationType": "HasMany",
  "with": "Post",
  "joinColumn": "user_id",
  "desc": "Posts"
}

Managing Enums

Use Enums when a field can only have limited values.

Adding an Enum

Click [+ Add Enum] button in the Enums section
Enter Enum information:

Field	Description	Example
Name	Enum name	`UserRole`
Values	Value/label pairs	`admin: Admin`, `user: User`

Generated code:

{
  "enums": {
    "UserRole": { "admin": "Admin", "user": "User", "guest": "Guest" }
  }
}

Using in Property:

{
  "name": "role",
  "type": "enum",
  "id": "UserRole",
  "desc": "Role",
  "dbDefault": "user"
}

AI-Assisted Entity Creation

Click the [💬 AI] button at the bottom of the sidebar to open the AI chat interface.

Create Entity with AI

Example prompt:

Create a Post Entity for blog posts.
I need title, content, author, creation date, and view count.

AI generates the Entity definition and adds it automatically.

Modify Entity with AI

Example prompt:

Add a profile image field to the User Entity.

AI analyzes the existing Entity and applies the modifications.

Be specific: The more clearly you describe field types, constraints, and relationships, the more accurate results you’ll get.

Practical Example

E-commerce Product Entity

src/application/product/product.entity.json

{
  "id": "Product",
  "title": "Product",
  "table": "products",
  "props": [
    { "name": "id", "type": "integer", "desc": "ID" },
    { "name": "created_at", "type": "date", "desc": "Created at", "dbDefault": "CURRENT_TIMESTAMP" },
    { "name": "title", "type": "string", "length": 255, "desc": "Title" },
    { "name": "description", "type": "string", "nullable": true, "desc": "Description" },
    { "name": "price", "type": "numeric", "precision": 10, "scale": 2, "desc": "Price" },
    { "name": "stock", "type": "integer", "desc": "Stock", "dbDefault": 0 },
    { "name": "status", "type": "enum", "id": "ProductStatus", "desc": "Status" },
    {
      "type": "relation",
      "name": "category",
      "relationType": "BelongsToOne",
      "with": "Category",
      "onUpdate": "CASCADE",
      "onDelete": "CASCADE",
      "desc": "Category"
    },
    {
      "type": "relation",
      "name": "reviews",
      "relationType": "HasMany",
      "with": "Review",
      "joinColumn": "product_id",
      "desc": "Reviews"
    }
  ],
  "indexes": [
    {
      "type": "index",
      "name": "products_status_created_at_index",
      "columns": [{ "name": "status" }, { "name": "created_at" }]
    }
  ],
  "subsets": { "A": ["id", "created_at", "title", "price", "status", "category.id"] },
  "enums": {
    "ProductStatus": { "active": "Active", "inactive": "Inactive", "soldout": "Sold out" },
    "ProductOrderBy": { "id-desc": "Newest" },
    "ProductSearchField": { "id": "ID", "title": "Title" }
  }
}

Applying Changes

After modifying an Entity, you need to create and run a migration to reflect changes in the database.

Workflow

Edit Entity: Modify Entity in the UI
Create Migration: Generate migration in the Migration tab
Run Migration: Run migration to apply to DB
Scaffolding: Generate Model and test code

Entity files (.entity.json) are automatically saved when modified in the UI.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Entity Tab Structure

Creating an Entity

1. Click New Entity Button

2. Enter Entity Information

3. Add Basic Properties

Editing Properties

Adding a Property

Editing a Property

Deleting a Property

Managing Indexes

Adding an Index

Composite Index

Managing Relations

belongsTo (N:1 Relationship)

hasMany (1:N Relationship)

Managing Enums

Adding an Enum

AI-Assisted Entity Creation

Create Entity with AI

Modify Entity with AI

Practical Example

E-commerce Product Entity

Applying Changes

Workflow

Next Steps

Migration Tab

Scaffolding Tab

​Entity Tab Structure

​Creating an Entity

​1. Click New Entity Button

​2. Enter Entity Information

​3. Add Basic Properties

​Editing Properties

​Adding a Property

​Editing a Property

​Deleting a Property

​Managing Indexes

​Adding an Index

​Composite Index

​Managing Relations

​belongsTo (N:1 Relationship)

​hasMany (1:N Relationship)

​Managing Enums

​Adding an Enum

​AI-Assisted Entity Creation

​Create Entity with AI

​Modify Entity with AI

​Practical Example

​E-commerce Product Entity

​Applying Changes

​Workflow

​Next Steps

Migration Tab

Scaffolding Tab

Entity Tab Structure

Creating an Entity

1. Click New Entity Button

2. Enter Entity Information

3. Add Basic Properties

Editing Properties

Adding a Property

Editing a Property

Deleting a Property

Managing Indexes

Adding an Index

Composite Index

Managing Relations

belongsTo (N:1 Relationship)

hasMany (1:N Relationship)

Managing Enums

Adding an Enum

AI-Assisted Entity Creation

Create Entity with AI

Modify Entity with AI

Practical Example

E-commerce Product Entity

Applying Changes

Workflow

Next Steps