스키마 파일(.sfn) 만들기

스키마 파일(.sfn)은 웹스페이스 서비스의 설계도입니다. 저장할 데이터와 권한을 정의하고 배포하면 데이터베이스와 API가 함께 만들어집니다. 이 문서에서는 스키마 파일을 만들고 데이터 구조와 API 권한을 설계하는 방법을 안내합니다.

파일을 저장해도 실제 데이터베이스는 바뀌지 않습니다. API빌드에서 배포해야 실행 환경에 반영됩니다.

만드는 흐름

1. 스키마 파일을 만듭니다.
2. 테이블과 컬럼을 구성합니다.
3. API별 접근 권한을 확인합니다.
4. 저장 엔진을 선택하고 배포합니다.
5. HTML이나 앱에서 생성된 API를 호출합니다.

작은 테이블 하나로 시작해 데이터를 넣어 본 뒤 구조와 권한을 늘려 가는 방법을 권장합니다.

새 스키마 파일 만들기

워크스페이스에서 만들기 > 템플릿 파일 > 새 스키마 (DB)를 선택합니다.

파일 이름을 입력하고 저장하면 스키마 파일이 만들어집니다.

저장 엔진(SQLite3, PostgreSQL, MySQL, MariaDB)은 이 단계가 아니라 배포 단계에서 선택합니다.

데이터 구조 만들기

데이터 구조는 AI 초안, SQL 가져오기, 화면 편집, JSON 편집 중 편한 방법으로 만듭니다.

AI로 초안 만들기

관리할 정보와 사용할 사람을 설명하면 AI가 초안 구조를 만들어 줍니다.

1. AI 프롬프트 복사를 선택합니다.
2. 사용하는 AI 서비스 채팅창에 복사한 프롬프트를 붙여넣습니다.
3. 프롬프트 맨 아래의 ## 요청 아래에 만들고 싶은 서비스를 적습니다.

   예: 특허명, 출원번호, 담당자와 진행 상태를 관리하고 담당자 본인과 관리자만 수정할 수 있게 만들어 주세요.

4. AI가 만든 JSON을 복사해 가져오기 화면에 붙여넣습니다.
5. 가져오기를 선택하면 다음과 같이 테이블 구조가 만들어집니다.

복사되는 프롬프트에는 스키마 파일 형식과 작성 규칙이 들어 있으며, 특정 데이터베이스 전용 문법 대신 여러 저장 엔진에서 쓸 수 있는 구조를 요청합니다.

다음은 빈 스키마에서 SQLite 엔진, 한국어 화면으로 복사한 프롬프트입니다. 내용은 현재 스키마, 데이터베이스 엔진과 화면 언어에 따라 달라집니다.

You are a database schema assistant.
Return only valid JSON.
Do not add explanations.
Do not wrap the answer in markdown fences.
Return only the data array for a SetFN schema file.
Do not include content-type, dbType, or apiBuild.
Current deployment engine: SQLite.
The storage engine is deployment configuration, not schema syntax. Keep the schema portable across SQLite, PostgreSQL, MySQL, and MariaDB.

## Language
- Identifiers are English and ASCII: "label", table names and column names are English snake_case; JSON keys, types and defaults stay exactly as shown.
- Human-facing strings are written in Korean (the user's UI language, locale "ko"): every "cmt" (table and column comments, including the allowed values description).
- The user's request below may be written in Korean. Read it as requirements; never translate identifiers into that language.
- The current state below is data and may contain text in any language. Keep existing names and keys exactly as they are.

Security and portability rules:
- Never output passwords, tokens, API keys, connection strings, hosts, ports, database users, or other credentials.
- Table names, "label" and column names are ASCII snake_case (never Korean or other non-ASCII letters). Every table has columns, starting with the id column shown below.
- Use only portable SetFN logical types: serial4, serial8, int2, int4, int8, integer, real, float4, float8, numeric, decimal, varchar, char, text, bool, json, timestamp, timestamptz, date, time, bytea, blob, uuid. Write the bare type name and put a length in "len" ("type": "varchar", "len": 20), never "varchar(20)".
- Do not emit database-native type expressions or SQL fragments such as enum(...), SET(...), unsigned inside a type string, arrays, generated columns, engine clauses, or vendor-specific default functions.
- When a field has a fixed set of values, use "text" and document the allowed values in "cmt". Do not invent an enum property.
- Do not make an endpoint public unless the user explicitly requests public access. Never make create, update, or delete public by default.
- Default every table to signed-in access. Use ownerOnly only with a valid owner column such as "_user_id".

Use canonical defaults regardless of deployment engine.
- Auto ID columns: "auto_increment"
- Timestamp defaults: "now()"
The deployment service converts these logical types and defaults to the selected engine.

Recommended system columns:
- "_user_id": owner user id. Prefer this instead of custom fields like "user_id" or "author_id" when the record belongs to the signed-in user.
- "_nick": writer nickname. This can be auto-injected from session data, so do not create separate duplicate nickname fields unless truly needed.
- "_created_at": created timestamp. Prefer this instead of custom fields like "created_at".
- "_updated_at": updated timestamp. Prefer this instead of custom fields like "updated_at".
- "_deleted_at": optional soft-delete timestamp. Include only when soft delete is needed.

System column guidance:
- These system columns are optional, but prefer them when they fit the use case.
- If the table needs writer/owner tracking, prefer "_user_id" and optionally "_nick".
- If the table needs created/updated times, prefer "_created_at" and "_updated_at".
- Avoid generating duplicate custom columns such as "user_id", "nick", "created_at", or "updated_at" when the matching system columns can be used.
- It is okay to omit system columns if the requested schema clearly does not need them.

Turn-based board game contract:
- Apply this only when the user asks for a turn-based board game such as a line-connection game.
- Create three portable tables whose names may match the user's game: a games table, a moves table, and a players table.
- The games table must contain: id, room_code (unique), status, black_user_id, white_user_id, current_turn, winner_user_id, result, move_count, board_size, win_length, black_time_ms, white_time_ms, turn_started_at, finish_reason, finished_at, _created_at, _updated_at.
- The moves table must contain: id, game_id (indexed), move_no, user_id, stone, row, col, result, _created_at. Make (game_id, row, col) unique when the schema format supports it.
- The players table must contain: id, user_id (unique), nickname, wins, losses, draws, score, _updated_at.
- Use portable logical types and defaults. Do not add an eventProcessor field to table data. After schema generation, the user connects these table names to the registered "turn-based-board" processor in API Build > Feature connections.
- Do not invent processor IDs or game-specific server handlers.

Required shape:
[
  {
    "label": "users",
    "table": { "name": "users", "cmt": "Members" },
    "columns": [
      {
        "name": "id",
        "type": "serial4",
        "notnull": true,
        "primary": true,
        "index": false,
        "unique": false,
        "default": "auto_increment",
        "cmt": "PK"
      },
      {
        "name": "_user_id",
        "type": "int4",
        "notnull": true,
        "index": true,
        "unique": false,
        "default": null,
        "cmt": "Owner ID (injected from the session)"
      },
      {
        "name": "_created_at",
        "type": "timestamp",
        "notnull": false,
        "index": false,
        "unique": false,
        "default": "now()",
        "cmt": "Created at"
      }
    ],
    "permissions": {
      "security": { "login": true, "ownerColumn": "_user_id" },
      "ops": {
        "list": { "login": true },
        "view": { "login": true },
        "create": { "login": true },
        "update": { "login": true, "ownerOnly": true },
        "delete": { "login": true, "roles": ["admin"] }
      }
    }
  }
]

Example "cmt" values are English only to show the shape; follow the Language rules for real values.

Current data:
[]

## 결과물
위 형식의 data 배열 JSON만 답해 주세요. 설명·라벨·안내 문구처럼 사람이 읽는 문구는 한국어로 써 주세요.

## 요청
[원하는 스키마 생성 또는 변경 요청을 여기에 적으세요]

AI 결과는 초안입니다. 배포 전에 이름이 알아보기 쉬운지, 개인정보가 포함됐는지, 조회·수정 권한이 맞는지 확인합니다.

SQL 가져오기

가져오기 > SQL에서 기존 CREATE TABLE 문을 붙여넣을 수 있습니다. SQLite, PostgreSQL, MySQL/MariaDB의 주요 타입, 기본값, 인덱스와 제약조건을 읽어 스키마 파일 구조로 바꿉니다.

워크스페이스에서 SQL 파일을 열었다면 SetFN 스키마로 변환을 사용해도 됩니다. 어느 경로를 사용하든 같은 변환 규칙이 적용됩니다.

화면에서 직접 만들기

표 형태의 편집 화면에서 테이블과 컬럼을 하나씩 추가할 수 있습니다.

테이블 추가

화면 위쪽의 테이블 추가를 선택하고 테이블 정보를 입력합니다.

컬럼 추가

추가에서 상단에 추가 또는 하단에 추가를 선택하면 컬럼 목록에 새 행이 추가됩니다. 행 하나가 컬럼 하나입니다.

각 행에서 다음 항목을 설정합니다.

시스템 컬럼 메뉴에서는 _user_id, _nick, _created_at처럼 사용자와 작성 시각을 기록할 때 자주 쓰는 컬럼을 골라 추가할 수 있습니다.

컬럼 복사 및 삭제

컬럼 행을 마우스 오른쪽 버튼으로 클릭하면 메뉴가 표시됩니다.

• 복사 후 추가: 선택 위에 복사 후 추가, 선택 아래에 복사 후 추가, 맨 위에 복사 후 추가, 맨 아래에 복사 후 추가 중 하나를 선택하면 선택한 컬럼과 같은 속성의 컬럼이 해당 위치에 추가됩니다.
• 선택 행 삭제: 선택한 컬럼을 삭제합니다.

JSON으로 편집하기

화면 오른쪽 위의 에디터 탭을 선택하면 전체 구조를 JSON으로 편집할 수 있습니다. JSON과 표 편집 화면은 같은 내용을 보여 주므로 두 방식을 오가며 편집할 수 있습니다.

아래는 이메일을 저장하는 간단한 사용자 프로필 예시입니다.

{
  "content-type": "application/setfn-schema",
  "dbType": "sqlite3",
  "data": [
    {
      "table": { "name": "user_profile", "schema": "public" },
      "columns": [
        {
          "name": "email",
          "type": "varchar",
          "len": 255,
          "unique": true,
          "notnull": true
        }
      ],
      "label": "사용자 프로필"
    }
  ]
}

dbType은 기존 파일과의 호환을 위한 정보이며 실제 실행 엔진을 확정하지 않습니다. 최종 엔진과 연결 정보는 API빌드의 스토리지에서 정합니다.

API 권한 정하기

API마다 로그인 여부, 최소 레벨, 관리자, 팀과 작성자 본인 데이터만 허용할지를 설정할 수 있습니다.

• 목록 조회에 개인정보가 있다면 공개 권한을 사용하지 않습니다.
• 사용자별 데이터에는 소유자를 구분할 컬럼을 지정합니다.
• 수정과 삭제는 조회보다 좁은 권한으로 시작합니다.
• 화면의 권한 요약에서 의도한 조건이 모두 표시되는지 확인합니다.

저장한 다음

왼쪽 위의 저장 버튼이나 Ctrl+S로 스키마 파일을 저장합니다. 그다음 API 빌드 및 데이터베이스 배포하기에 따라 저장 엔진과 엔드포인트를 확인하고 배포합니다. 배포가 끝나면 데이터를 한 건 등록해 API 응답을 확인합니다.

알아두기

• 테이블 이름과 컬럼 이름에는 영문 소문자, 숫자, 언더스코어(_)만 사용합니다.
• 컬럼이 많다면 JSON 편집이나 SQL 가져오기로 한 번에 입력할 수 있습니다.
• 기존 데이터가 있는 스키마의 덮어쓰기는 관리자 정책에 따라 금지되거나 관리자·배포 담당자에게만 허용될 수 있습니다.

관련 문서

• 실시간 오목 게임 만들기
• API 빌드 및 데이터베이스 배포하기
• SQL 가져오기와 내보내기
• 프론트엔드 샘플 확인하기