NocoDB 가이드

NocoDB는 팀의 공용 데이터베이스다. 에이전트가 데이터를 기록하고, 사람이 웹 UI로 조회한다.

접속 정보

API 빠른 참조

에이전트가 NocoDB API를 호출할 때 참고할 정보.

인증 토큰 획득

# 방법 1: Secret Manager (추천)
from tools._lib.secrets import get_secret
token = get_secret("nocodb/api_token")

# 방법 2: 직접 HTTP
import json, urllib.request
req = urllib.request.Request("http://10.200.2.183:8900/secrets/nocodb")
resp = urllib.request.urlopen(req)
secrets = json.loads(resp.read())
token = secrets["api_token"]

주요 API 엔드포인트

API 주의사항

• 인증 헤더는 xc-token 이다. xc-auth는 401 에러 발생.
• Base 목록 조회는 v1 API (/api/v1/workspaces/{ws_id}/bases). v2 /api/v2/meta/bases/는 403.
• Base 생성은 v2 API (/api/v2/meta/workspaces/{ws_id}/bases). v1은 404.
• 레코드 CRUD는 v2 API (/api/v2/tables/{table_id}/records).
• SingleSelect 컬럼에 새 선택지를 추가하려면 /api/v2/meta/columns/{col_id}를 PATCH하여 colOptions.options에 추가한 뒤 레코드를 삽입해야 한다.

고정 ID 레지스트리

에이전트가 매번 탐색하지 않도록, 변하지 않는 ID들을 여기에 기록한다. 새 base/table이 추가되면 이 섹션도 업데이트한다.

Workspace

Bases

Tables

에이전트 탐색 흐름

이미 테이블 ID를 아는 경우

위의 고정 ID 레지스트리를 참조하여 바로 접근한다. 대부분의 경우 이 방법으로 충분하다.

table_id = "m00itzw58f79kzs"  # recording_log — 위 표에서 확인
req = urllib.request.Request(
    f"https://ttslab-nocodb.exe.xyz/api/v2/tables/{table_id}/records",
    headers={"xc-token": token}
)

테이블 ID를 모르는 경우

새로운 테이블이거나 ID를 모르면 _meta를 통해 탐색한다.

1. _meta/tables_directory 조회 (table_id: m1qjx4oal56k3oh)
   → Table Name과 Table ID를 확인

2. 필요한 테이블의 ID로 직접 접근

새 테이블을 발견하면

이 문서의 고정 ID 레지스트리에 없는 테이블을 발견하면, 이 문서를 업데이트하여 다른 에이전트가 반복 탐색하지 않도록 한다.

Base 구조

_meta (메타데이터)

에이전트가 NocoDB를 탐색하기 위한 진입점. wiki/INDEX.md와 같은 역할.

주의: _meta는 read-only. harness-admin만 수정한다.

harness-ops (하네스 운영)

팀과 에이전트의 활동을 추적한다.

tts-data (TTS 데이터)

TTS 프로젝트의 핵심 데이터를 관리한다.

계층 설계 정책

NocoDB의 데이터 구조는 Workspace → Base → Table 계층이다.

Workspace: TTS Lab (wv7y2917)
├── _meta          (메타 — 에이전트 탐색 전용)
├── harness-ops    (운영 — 팀 공용)
├── tts-data       (도메인 — TTS 데이터)
├── proj-*         (프로젝트 한정 — 필요 시 생성)
└── ...

언제 새 Base를 만드는가

Base는 독립적인 업무 도메인 단위로 생성한다. 하나의 base 안에 있는 테이블들은 서로 관련된 데이터여야 한다.

Base 이름 접두사

테이블 설계 규칙

• 테이블 간 참조가 필요하면 같은 base 안에 둔다 — NocoDB의 Link/Lookup은 같은 base 내에서만 동작
• 다른 base의 데이터를 참조해야 하면 텍스트 컬럼에 ID를 기록하고 애플리케이션에서 조인
• 테이블이 1만 행 또는 20개 컬럼을 넘으면 분할을 검토
• 시계열 데이터는 연도별 테이블(예: recording_log_2026)보다 하나의 테이블 + 날짜 컬럼을 우선

_meta의 특수한 역할

_meta는 일반 데이터를 넣는 곳이 아니다. 에이전트가 NocoDB 구조를 파악하기 위한 카탈로그다.

• 새 base 생성 → _meta/bases_directory에 등록 필수
• 새 테이블 생성 → _meta/tables_directory에 등록 필수
• 규칙 변경 → _meta/rules에 반영

운영 규칙

네이밍

• Base 이름: kebab-case (예: harness-ops, tts-data)
• Table 이름: snake_case (예: recording_log, training_log)
• SingleSelect 선택지: 영문 kebab-case (예: qa-pass, read-write)

스키마

• 새 base 생성 시 → _meta/bases_directory에 등록 필수
• 새 테이블 생성 시 → _meta/tables_directory에 등록 필수
• 날짜/시간: ISO 8601 형식

접근

• _meta base는 read-only (harness-admin만 수정)
• 에이전트가 데이터를 기록할 때 actor_type을 agent로 명시

데이터 품질

• 빈 행을 만들지 않는다
• 필수 컬럼은 반드시 채운다
• 중복 데이터를 입력하기 전에 기존 데이터를 확인한다

새 base/테이블 추가 절차

1. 목적과 스키마를 정의한다
2. base 또는 테이블을 생성한다
3. _meta/bases_directory 또는 _meta/tables_directory에 등록한다
4. 이 문서의 고정 ID 레지스트리를 업데이트한다

API 사용 예시

테이블 레코드 조회

from tools._lib.secrets import get_secret
import json, urllib.request

token = get_secret("nocodb/api_token")
table_id = "m00itzw58f79kzs"  # recording_log

req = urllib.request.Request(
    f"https://ttslab-nocodb.exe.xyz/api/v2/tables/{table_id}/records",
    headers={"xc-token": token}
)
resp = urllib.request.urlopen(req)
data = json.loads(resp.read())
print(data["list"])

레코드 생성

row = {
    "date": "2026-04-16",
    "speaker_code": "KR_F02",
    "utterance_count": 150,
    "status": "recorded",
    "recorded_by": "이녹음엔지니어"
}
data = json.dumps(row).encode()
req = urllib.request.Request(
    f"https://ttslab-nocodb.exe.xyz/api/v2/tables/{table_id}/records",
    data=data,
    headers={"xc-token": token, "Content-Type": "application/json"},
    method="POST"
)

Workspace/Base 탐색 (새 base가 추가되었을 때)

# Workspace 목록 (v2)
req = urllib.request.Request(
    "https://ttslab-nocodb.exe.xyz/api/v2/meta/workspaces",
    headers={"xc-token": token}
)

# Workspace 내 Base 목록 (v1 — v2는 403)
req = urllib.request.Request(
    f"https://ttslab-nocodb.exe.xyz/api/v1/workspaces/wv7y2917/bases",
    headers={"xc-token": token}
)

# Base 내 Table 목록 (v2)
req = urllib.request.Request(
    f"https://ttslab-nocodb.exe.xyz/api/v2/meta/bases/{base_id}/tables",
    headers={"xc-token": token}
)

harness CLI 사용

python -m tools.integrations.nocodb.client --table m00itzw58f79kzs --action list --json