Creating Your First Entity

​

Prerequisites

• You must have completed the Quick Start guide and have the development server running.
• The API server must be running at http://localhost:1028.

​

Step 1: Access Sonamu UI

• Create and edit entities
• Add/modify/delete props
• Define relations
• Manage Enum types
• Define Subsets
• Create and run migrations
• Scaffolding (auto-generate Model files)

​

Step 2: Create a New Entity

1

Click Entity Tab

Click the Entity tab in the Sonamu UI top menu to see existing entities.

2

Click New Entity Button

Click the New Entity button at the bottom of the left sidebar.

3

Enter Basic Information and Create

Enter the basic information for the new entity and click the Create button:

• Entity ID: Post (starts with uppercase, singular)
• Table Name: posts (lowercase, plural)
• Title: Post

Entity ID is used as the TypeScript class name, and Table Name is the actual database table name.

​

Step 3: Define Props

1

Add Basic Props

Click the Add a prop button to add the following props:

Prop Name	Type	Description	Options
id	integer	ID	Primary Key
created_at	date	Created At	DB Default: CURRENT_TIMESTAMP
title	string	Title	Length: 255
content	string	Content	-
author	string	Author	Length: 100
view_count	integer	View Count	DB Default: 0

How to Configure Each Prop

id prop

• Name: id
• Type: integer
• Description: ID

created_at prop

• Name: created_at
• Type: date
• Description: Created At
• DB Default: CURRENT_TIMESTAMP

title prop

• Name: title
• Type: string
• Description: Title
• Length: 255

content prop

• Name: content
• Type: string
• Description: Content
• Length: empty (creates TEXT type)

author prop

• Name: author
• Type: string
• Description: Author
• Length: 100

view_count prop

• Name: view_count
• Type: integer
• Description: View Count
• DB Default: 0

2

Define Subsets

In the Subsets section, define data query forms:

• Subset A (Admin): id, created_at, title, content, author, view_count - Full information
• Subset P (Public): id, title, author, created_at - Public information
• Subset SS (Secure Short): id, title, author - Summary information

Subsets pre-define which props to include when querying data through APIs. For details, see the Subset Guide.

3

Define Enums

In the Enums section, define sorting and search options:PostOrderBy

• id-desc: ID newest first
• created_at-desc: Created at newest first
• view_count-desc: Highest view count first

PostSearchField

• id: ID
• title: Title
• author: Author

​

Step 4: Database Migration

1

Go to Migration Tab

Click the Migration tab in Sonamu UI.

2

Generate Migration

Click the Generate button to auto-generate a new migration Code File.Click the <> button in the generated file list to open the migration file page in Cursor. The file content looks like this:

3

Run Migration

You can see pending migrations in the Migration tab.Click the all button, then click Apply to Latest to see migration targets in the modal.Select Shadow DB Testing and click the commit button to create the database table.

4

Verify

Connect to the database using a PostgreSQL client or pgAdmin to verify the posts table was created.

​

Step 5: Scaffolding (Auto-Generate Model Files)

1

Go to Scaffolding Tab

Click the Scaffolding tab in Sonamu UI.

2

Select Post Entity

Select Post as the entity to scaffold.

3

Select Templates

Select templates to generate:

• ✅ Model - post.model.ts (business logic and API endpoints)
• ✅ Model Test - post.model.test.ts (test file)

Scaffolding auto-generates template files, so you don’t need to write code from scratch. Generated files can be modified to fit your project.

4

Preview (Optional)

Click the Preview button to preview the code that will be generated.

5

Generate

Click the Generate button to create the files.

The following files are generated:

• api/src/application/post/post.model.ts
• api/src/application/post/post.model.test.ts

You can also run this from the terminal:

Copy

cd api
pnpm sonamu scaffold model Post
pnpm sonamu scaffold model_test Post

​

Step 6: Review Generated Model File

​

Step 7: Auto-Generate Frontend Service

export class PostService {
  static async findById(subset: PostSubsetKey, id: number) {
    const res = await axios.get(`/api/posts/${id}`, {
      params: { subset },
    });
    return res.data;
  }

  static async findMany(subset: PostSubsetKey, params?: PostListParams) {
    const res = await axios.get("/api/posts", {
      params: { subset, ...params },
    });
    return res.data;
  }

  static async save(params: PostSaveParams) {
    const res = await axios.post("/api/posts", params);
    return res.data;
  }

  static async del(id: number) {
    await axios.delete(`/api/posts/${id}`);
  }
}

​

Step 8: Test the API

​

Test with REST Client

curl -X POST http://localhost:1028/api/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "First Post",
    "content": "This is my first post created with Sonamu.",
    "author": "John Doe"
  }'

​

Test in Browser

​

Complete! 🎉

• ✅ Defined entity with Sonamu UI
• ✅ Created database table
• ✅ Auto-generated types and schemas
• ✅ Auto-generated Model and Test files with scaffolding
• ✅ Auto-generated REST API
• ✅ Auto-generated frontend Service
• ✅ Tested the API

​

Next Steps