Entity 관리

Sonamu UI의 Entity 관리 기능을 사용하면 시각적 인터페이스로 Entity를 쉽게 생성하고 편집할 수 있습니다. CLI로 파일을 직접 수정하는 것보다 훨씬 빠르고 직관적입니다.

Entity 탭 구조

Entity 탭은 두 가지 주요 영역으로 구성됩니다:

왼쪽 Sidebar: Entity 목록과 새 Entity 추가 버튼
오른쪽 Content: 선택한 Entity의 상세 정보 (Properties, Indexes, Relations, Subsets, Enums)

Entity 생성하기

1. New Entity 버튼 클릭

사이드바 하단의 [+ New Entity] 버튼을 클릭합니다.

2. Entity 정보 입력

모달이 열리면 다음 정보를 입력합니다:

필드	설명	예시
Entity ID	Entity 식별자 (PascalCase)	`Product`, `OrderItem`
Title	한글 제목	`상품`, `주문 항목`
Parent Entity	부모 Entity (선택)	`Order`

Parent Entity를 지정하면 부모 Entity의 하위 Entity가 됩니다. 예: Order → OrderItem

3. 기본 Properties 추가

생성된 Entity는 기본적으로 다음 필드를 포함합니다:

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

Properties 편집

Property 추가

[+ Add Property] 버튼 클릭
Property 정보 입력:

필드	필수	설명	예시
Name	✅	필드명 (snake_case)	`email`, `phone_number`
Type	✅	데이터 타입	`string`, `integer`, `numeric`
Length	조건부	문자열 길이	`255`
Nullable		NULL 허용 여부	`true`
DB Default		DB 기본값	`0`, `CURRENT_TIMESTAMP`
Description		설명	`사용자 이메일`

지원하는 데이터 타입:

문자열: string(길이 미지정 시 text), uuid, searchText
숫자: integer, bigInteger, number, numeric(precision/scale)
날짜: date
기타: boolean, enum, json, virtual, vector, tsvector, relation

대부분의 스칼라 타입은 integer[], string[]처럼 []를 붙인 배열 타입도 지원합니다. 전체 목록은 필드 타입 문서를 참고하세요.

Property 수정

Property 행을 클릭하여 편집 모드로 전환
값을 수정
다른 곳을 클릭하거나 Enter를 눌러 저장

Property 삭제

Property 행의 [×] 버튼을 클릭합니다.

데이터 손실 주의: Property를 삭제하면 해당 컬럼의 모든 데이터가 삭제됩니다. 마이그레이션을 실행하기 전에 반드시 데이터를 백업하세요.

Indexes 관리

Index 추가

Indexes 섹션으로 스크롤
[+ Add Index] 버튼 클릭
Index 정보 입력:

필드	설명	예시
Target Columns	인덱스 대상 필드 (복수 선택 가능)	`email`, `created_at`
Type	인덱스 타입	`index`, `unique`, `hnsw`, `ivfflat`

Index 타입:

index: 일반 인덱스 (검색 성능 향상)
unique: 유니크 인덱스 (중복 방지)
hnsw / ivfflat: pgvector 벡터 인덱스

전문 검색은 별도의 인덱스 타입이 아니라 searchText/tsvector prop과 using: "gin" 옵션으로 구성합니다. 벡터 검색 문서를 참고하세요.

복합 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" }] }
  ]
}

Relations 관리

belongsTo (N:1 관계)

의미: “이 Entity는 다른 Entity에 속한다” 예시: Post는 User에 속함

belongsTo 섹션의 [+ Add] 버튼 클릭
정보 입력:

필드	설명	예시
Entity	참조할 Entity	`User`
As	관계 별칭	`author`
Foreign Key	외래키 필드명 (선택)	`author_id`

생성되는 코드:

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

hasMany (1:N 관계)

의미: “이 Entity는 여러 개의 다른 Entity를 가진다” 예시: User는 여러 Post를 가짐

hasMany 섹션의 [+ Add] 버튼 클릭
정보 입력:

필드	설명	예시
Entity	대상 Entity	`Post`
As	관계 별칭	`posts`

생성되는 코드:

{
  "type": "relation",
  "name": "posts",
  "relationType": "HasMany",
  "with": "Post",
  "joinColumn": "user_id",
  "desc": "게시글목록"
}

Enums 관리

특정 필드가 제한된 값만 가질 수 있을 때 Enum을 사용합니다.

Enum 추가

Enums 섹션의 [+ Add Enum] 버튼 클릭
Enum 정보 입력:

필드	설명	예시
Name	Enum 이름	`UserRole`
Values	값과 레이블의 쌍	`admin: 관리자`, `user: 일반`

생성되는 코드:

{
  "enums": {
    "UserRole": { "admin": "관리자", "user": "일반", "guest": "게스트" }
  }
}

Property에서 사용:

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

AI 지원 Entity 생성

사이드바 하단의 [💬 AI] 버튼을 클릭하면 AI 채팅 인터페이스가 열립니다.

AI로 Entity 생성

예시 프롬프트:

블로그 게시글을 위한 Post Entity를 만들어줘.
제목, 내용, 작성자, 작성일, 조회수가 필요해.

AI가 Entity 정의를 생성하고 자동으로 추가해줍니다.

AI로 Entity 수정

예시 프롬프트:

User Entity에 프로필 이미지 필드를 추가해줘.

AI가 기존 Entity를 분석하고 수정 사항을 적용합니다.

구체적으로 요청하세요: 필드 타입, 제약 조건, 관계 등을 명확히 설명할수록 더 정확한 결과를 얻을 수 있습니다.

실전 예제

전자상거래 Product Entity

src/application/product/product.entity.json

{
  "id": "Product",
  "title": "상품",
  "table": "products",
  "props": [
    { "name": "id", "type": "integer", "desc": "ID" },
    {
      "name": "created_at",
      "type": "date",
      "desc": "등록일시",
      "dbDefault": "CURRENT_TIMESTAMP"
    },
    { "name": "title", "type": "string", "length": 255, "desc": "상품명" },
    { "name": "description", "type": "string", "nullable": true, "desc": "설명" },
    { "name": "price", "type": "numeric", "precision": 10, "scale": 2, "desc": "가격" },
    { "name": "stock", "type": "integer", "desc": "재고", "dbDefault": 0 },
    { "name": "status", "type": "enum", "id": "ProductStatus", "desc": "상태" },
    {
      "type": "relation",
      "name": "category",
      "relationType": "BelongsToOne",
      "with": "Category",
      "onUpdate": "CASCADE",
      "onDelete": "CASCADE",
      "desc": "카테고리"
    },
    {
      "type": "relation",
      "name": "reviews",
      "relationType": "HasMany",
      "with": "Review",
      "joinColumn": "product_id",
      "desc": "리뷰목록"
    }
  ],
  "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": "판매중", "inactive": "판매중지", "soldout": "품절" },
    "ProductOrderBy": { "id-desc": "ID최신순" },
    "ProductSearchField": { "id": "ID", "title": "상품명" }
  }
}

변경사항 적용

Entity를 수정한 후에는 마이그레이션을 생성하고 실행해야 데이터베이스에 반영됩니다.

워크플로우

Entity 편집: UI에서 Entity 수정
Migration 생성: Migration 탭에서 마이그레이션 생성
Migration 실행: 마이그레이션 실행하여 DB 반영
Scaffolding: Model과 테스트 코드 생성

Entity 파일(.entity.json)은 UI에서 수정 시 자동으로 저장됩니다.

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

Entity 탭 구조

Entity 생성하기

1. New Entity 버튼 클릭

2. Entity 정보 입력

3. 기본 Properties 추가

Properties 편집

Property 추가

Property 수정

Property 삭제

Indexes 관리

Index 추가

복합 Index

Relations 관리

belongsTo (N:1 관계)

hasMany (1:N 관계)

Enums 관리

Enum 추가

AI 지원 Entity 생성

AI로 Entity 생성

AI로 Entity 수정

실전 예제

전자상거래 Product Entity

변경사항 적용

워크플로우

다음 단계

Migration 탭

Scaffolding 탭

​Entity 탭 구조

​Entity 생성하기

​1. New Entity 버튼 클릭

​2. Entity 정보 입력

​3. 기본 Properties 추가

​Properties 편집

​Property 추가

​Property 수정

​Property 삭제

​Indexes 관리

​Index 추가

​복합 Index

​Relations 관리

​belongsTo (N:1 관계)

​hasMany (1:N 관계)

​Enums 관리

​Enum 추가

​AI 지원 Entity 생성

​AI로 Entity 생성

​AI로 Entity 수정

​실전 예제

​전자상거래 Product Entity

​변경사항 적용

​워크플로우

​다음 단계

Migration 탭

Scaffolding 탭

Entity 탭 구조

Entity 생성하기

1. New Entity 버튼 클릭

2. Entity 정보 입력

3. 기본 Properties 추가

Properties 편집

Property 추가

Property 수정

Property 삭제

Indexes 관리

Index 추가

복합 Index

Relations 관리

belongsTo (N:1 관계)

hasMany (1:N 관계)

Enums 관리

Enum 추가

AI 지원 Entity 생성

AI로 Entity 생성

AI로 Entity 수정

실전 예제

전자상거래 Product Entity

변경사항 적용

워크플로우

다음 단계