Sonamu UI 사용하기

Sonamu UI는 Entity를 시각적으로 정의하고 관리할 수 있는 웹 기반 인터페이스입니다. 자동 완성, 유효성 검사, 실시간 미리보기 등 강력한 기능을 제공합니다.

Sonamu UI 접속하기

서버 실행

cd api
pnpm dev

UI 접속

API 서버가 실행되면 자동으로 Sonamu UI도 함께 제공됩니다:

http://localhost:1028/sonamu-ui

Sonamu UI는 별도의 포트 없이 API 서버의 /sonamu-ui 경로에서 제공됩니다.

주요 탭 구성

Sonamu UI는 4개의 주요 탭으로 구성됩니다:

Entities
Migrations
Scaffolding
Fixture

Entity 정의와 관리

Entity 생성, 수정, 삭제
Props, Indexes, Subsets, Enums 설정

Entity 생성하기

1. Entity 목록 페이지

Entities 탭을 클릭하면 프로젝트의 모든 Entity 목록이 표시됩니다.

표시 정보:

Entity ID와 Title
테이블명
Props 개수
Relation 개수

2. 새 Entity 생성

Create Entity 버튼 클릭

우측 상단의 “Create Entity” 버튼을 클릭합니다.

기본 정보 입력

Entity 생성 폼에서 다음 정보를 입력합니다:

Entity ID: PascalCase (예: User, BlogPost)
Table Name: snake_case (예: users, blog_posts)
Title: 한글 또는 표시명 (예: “사용자”, “블로그 글”)
Parent ID: 선택 사항 - 다른 Entity를 상속할 때 사용

Entity ID는 생성 후 변경할 수 없으므로 신중하게 입력하세요.

저장

“Create” 버튼을 클릭하면:

{entity}.entity.json 파일 생성
Entity 상세 페이지로 자동 이동

Entity 편집하기

Entity를 클릭하면 상세 편집 페이지가 열립니다. 4개의 시트로 구성됩니다:

Props 시트

Entity의 속성(컬럼)을 관리하는 메인 시트입니다.

Props 추가하기

Add Property 버튼 클릭

우측 상단의 “Add Property” 버튼 클릭 또는 단축키 Ctrl+Cmd+Shift+N 사용

속성 정보 입력

기본 필드:

name: 속성명 (snake_case)
type: 데이터 타입 (드롭다운에서 선택)
desc: 설명 (선택 사항)
nullable: NULL 허용 여부 (체크박스)
dbDefault: 데이터베이스 기본값

타입별 추가 옵션:

string / string[]

length: 문자열 길이 (기본값: TEXT)
예: length: 255 → VARCHAR(255)

number / number[]

precision: 전체 자릿수
scale: 소수점 자릿수
numberType: real | double precision | numeric (기본값: numeric)
예: precision: 10, scale: 2 → NUMERIC(10, 2)

numeric / numeric[]

precision: 전체 자릿수
scale: 소수점 자릿수
주의: TypeScript에서 string 타입으로 처리됨 (정밀도 유지)

enum / enum[]

id: Enum 타입 ID (예: UserRole)
Enum은 별도의 Enums 섹션에서 정의

json

id: JSON 스키마 타입 ID
TypeScript 타입을 {entity}.types.ts에서 정의

vector / vector[]

dimensions: 벡터 차원 (예: 1536)
pgvector 확장 필요

virtual

id: Virtual 타입 ID
virtualType: code | query
- code: TypeScript 코드로 계산 (기본값)
- query: SQL 쿼리로 계산
데이터베이스에 저장되지 않는 계산된 필드

relation

Relation 타입 선택 및 설정
자세한 내용은 Relations 참조

저장

입력 완료 후 “Save” 버튼 클릭

Props 수정 및 삭제

수정
삭제
순서 변경

Props 목록에서 수정할 행을 더블클릭 또는 Enter 키
또는 행 선택 후 우측의 “Edit” 버튼 클릭
폼에서 값 수정 후 저장

Props 목록에서 삭제할 행 선택
Cmd+Backspace 단축키 사용
또는 우측의 “Delete” 버튼 클릭
확인 다이얼로그에서 삭제 확인

Props를 삭제하면 해당 컬럼이 모든 Subset에서도 자동으로 제거됩니다. 복구할 수 없으므로 주의하세요.

Indexes 시트

데이터베이스 인덱스를 관리합니다.

Index 추가하기

Add Index 버튼 클릭

“Add Index” 버튼 클릭 또는 Indexes 시트에서 Ctrl+Cmd+Shift+N

Index 설정

Index 옵션:

type: 인덱스 타입
- index: 일반 인덱스
- unique: 유니크 인덱스 (중복 방지)
- hnsw: Vector HNSW 인덱스
- ivfflat: Vector IVFFlat 인덱스
name: 인덱스명 (자동 생성 가능)
columns: 인덱스에 포함할 컬럼 선택
- 다중 컬럼 선택 가능
- 컬럼 순서 중요 (복합 인덱스)
using: 인덱스 방법 (선택 사항)
- btree (기본값)
- hash
- gin
- gist

Vector 인덱스 추가 옵션:

vectorOps: 거리 연산자
- vector_cosine_ops: 코사인 거리 (권장)
- vector_ip_ops: 내적 거리
- vector_l2_ops: 유클리드 거리
m: HNSW 그래프 연결 수 (기본값: 16)
efConstruction: HNSW 구성 품질 (기본값: 64)
lists: IVFFlat 클러스터 수 (기본값: 100)

인덱스 네이밍 규칙:

일반 인덱스: {table}_{columns}_idx
유니크 인덱스: {table}_{columns}_unique
예: users_email_unique, posts_created_at_idx

Subsets 시트

API 응답을 위한 필드 조합을 정의합니다.

Subset 키 추가

Add Subset 버튼 클릭

“Add Subset” 버튼을 클릭하여 새 subset 키 추가

Subset 키 입력

대문자로 시작하는 짧은 키 권장 (예: A, P, SS)
일반적으로 사용되는 키:
- A: All - 모든 필드
- P: Public - 공개 API용
- SS: Simple Short - 간단한 정보만

필드 선택

일반 필드
Relation 필드
Internal 필드

체크박스를 클릭하여 필드 포함/제외
여러 subset에서 동일 필드 선택 가능

Relation 필드는 트리 구조로 표시됨
화살표 아이콘을 클릭하여 펼치기/접기
하위 Entity의 필드도 선택 가능
예: employee.department.name

Relation 필드를 선택하면 Sonamu가 자동으로 JOIN 쿼리를 생성합니다.

부모 Relation을 선택하면 하위 필드를 개별 선택할 수 없습니다. 전체 또는 특정 필드만 선택하세요.

Enums 섹션

Enum 타입의 키와 레이블을 정의합니다.

Enum 추가

Add Enum 버튼 클릭

“Add Enum” 버튼을 클릭

Enum ID 입력

PascalCase로 입력 (예: UserRole, PostStatus)
Entity ID와 연결하려면 {EntityId} 패턴 사용
- 예: $ModelRole → UserRole (자동 변환)

Enum 값 추가

각 Enum은 별도의 탭으로 표시되며, 키-레이블 쌍으로 구성됩니다.

{
  "UserRole": {
    "normal": "일반 사용자",
    "admin": "관리자",
    "superadmin": "최고 관리자"
  }
}

Enum 값 추가 방법:

“Add Row” 버튼 클릭
또는 Enum 탭에서 Ctrl+Cmd+Shift+N
Key와 Label 입력
- Key: 영문 소문자, 숫자, 언더스코어만 허용
- Label: 한글 또는 표시용 텍스트

자주 사용되는 Enum 패턴:

{Entity}OrderBy: 정렬 옵션 (예: id-desc, created_at-desc)
{Entity}SearchField: 검색 필드 (예: email, username)
{Entity}Status: 상태 (예: active, inactive, deleted)

키보드 단축키

Sonamu UI는 효율적인 작업을 위한 다양한 단축키를 제공합니다.

전역 단축키

단축키	기능
`Cmd+S`	현재 Entity 저장
`Cmd+K`	검색 모드 진입
`Tab`	다음 시트로 이동
`Shift+Tab`	이전 시트로 이동
`Esc`	다이얼로그 닫기 / 선택 해제

Props/Indexes 시트

단축키	기능
`Ctrl+Cmd+Shift+N`	새 항목 추가
`Enter`	선택한 항목 수정
`Cmd+Backspace`	선택한 항목 삭제
`↑` `↓`	항목 선택 이동
`Cmd+↑` `Cmd+↓`	항목 순서 변경

검색 모드

단축키	기능
`Cmd+K`	검색 시작
타이핑	일치하는 항목으로 자동 이동
`Enter`	검색 완료
`Esc`	검색 취소

검색 모드에서는 타이핑하는 즉시 일치하는 항목으로 커서가 이동합니다. 빠른 네비게이션에 활용하세요!

Entity 삭제하기

Entity 삭제는 되돌릴 수 없습니다. 반드시 백업 후 진행하세요.

Entity 선택

삭제할 Entity의 상세 페이지로 이동

Delete Entity 버튼 클릭

우측 상단의 “Delete Entity” 버튼 클릭

확인

확인 다이얼로그에서 Entity ID를 정확히 입력하여 삭제 확인

삭제 시 영향:

{entity}.entity.json 파일 삭제
관련된 Model, Types 파일은 수동으로 삭제 필요
데이터베이스 테이블은 마이그레이션을 통해 별도로 삭제

파일 구조

Entity를 저장하면 다음 파일들이 생성됩니다:

하이라이트된 파일들은 Sonamu가 자동으로 생성하는 파일입니다.

실시간 유효성 검사

Sonamu UI는 입력 즉시 유효성을 검사합니다:

Props
Indexes
Subsets
Enums

예약어 체크 (JavaScript/TypeScript 키워드)
타입별 필수 옵션 체크
중복 이름 체크

오류가 있으면 빨간색 테두리와 함께 오류 메시지가 표시됩니다.

자동 완성 기능

Sonamu UI는 컨텍스트에 맞는 자동 완성을 제공합니다:

Entity ID 입력 시

기존 Entity 목록 제안
타이핑에 따라 필터링

Relation 설정 시

with 필드에서 사용 가능한 Entity 목록 자동 완성

Type ID 입력 시

JSON, Virtual 타입의 id 필드에서 타입 제안

Enum ID 입력 시

정의된 Enum 목록 제안
새 Enum 생성 옵션 제공

다음 단계

Sonamu UI의 기본 사용법을 익혔다면, 다음 주제를 학습하세요:

Field Types

모든 필드 타입의 상세 옵션과 사용법

Relations

Entity 간 관계 정의하는 방법

Migrations

생성된 마이그레이션 실행하기

Scaffolding

Model과 Types 파일 자동 생성

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​Sonamu UI 접속하기

​서버 실행

​UI 접속

​주요 탭 구성

​Entity 생성하기

​1. Entity 목록 페이지

​2. 새 Entity 생성

​Entity 편집하기

​Props 시트

​Props 추가하기

​Props 수정 및 삭제

​Indexes 시트

​Index 추가하기

​Subsets 시트

​Subset 키 추가

​필드 선택

​Enums 섹션

​Enum 추가

​Enum 값 추가

​키보드 단축키

​전역 단축키

​Props/Indexes 시트

​검색 모드

​Entity 삭제하기

​파일 구조

​실시간 유효성 검사

​자동 완성 기능

​다음 단계

Field Types

Relations

Migrations

Scaffolding

Sonamu UI 접속하기

서버 실행

UI 접속

주요 탭 구성

Entity 생성하기

1. Entity 목록 페이지

2. 새 Entity 생성

Entity 편집하기

Props 시트

Props 추가하기

Props 수정 및 삭제

Indexes 시트

Index 추가하기

Subsets 시트

Subset 키 추가

필드 선택

Enums 섹션

Enum 추가

Enum 값 추가

키보드 단축키

전역 단축키

Props/Indexes 시트

검색 모드

Entity 삭제하기

파일 구조

실시간 유효성 검사

자동 완성 기능

다음 단계