본문으로 건너뛰기

도구

서버는 65개의 도구를 제공합니다. 세션 도구 5개, 읽기 도구 3개, 편집 작업마다 하나씩인 편집 도구 56개, 그리고 여러 편집 도구를 하나의 편집으로 실행하는 erd_batch입니다.

erd_list_documents를 제외한 모든 도구는 첫 번째 인자로 문서의 path를 받으며, 아래 표에서는 생략합니다. ?가 붙은 인자는 선택 사항입니다.

세션 도구​

도구인자동작
erd_list_documentsERD 문서를 path, open, active, dirty, readonly와 함께 나열합니다. 작업 디렉터리를 담당하는 에디터가 있으면 그 에디터의 문서를(JetBrains IDE에서는 열린 모든 프로젝트의 문서를), 없으면 작업 디렉터리 아래의 ERD 파일을 나열합니다.
erd_open_documentcreate?편집할 문서를 엽니다. 문서를 담당하는 에디터가 있으면 그 에디터의 ERD Editor에서 엽니다. create를 주면 파일이 없을 때 먼저 만들며, 확장자가 없는 이름에는 .erd.json이 붙습니다.
erd_save에디터가 가진 문서를 저장합니다. VS Code는 이 도구가 호출될 때까지 에이전트의 편집을 저장되지 않은 상태로 두고, Obsidian과 JetBrains IDE는 사용자의 편집을 저장하듯 저장하며 이 도구는 곧바로 파일에 씁니다. 헤드리스에서는 모든 편집이 이미 파일에 쓰여 있으므로 아무것도 하지 않습니다.
erd_undo이 에이전트가 마지막으로 한 편집을 되돌리며, 사용자의 편집은 절대 되돌리지 않습니다. Undo 항목을 만들지 않은 호출은 건너뛰고 그 이름을 알려 줍니다.
erd_redoerd_undo가 마지막으로 되돌린 편집을 다시 적용합니다.

각 모드에서 저장과 Undo가 어떻게 동작하는지는 라이브와 헤드리스 문서를 참고하세요.

문서 읽기​

도구인자동작
erd_listquery?, offset?, limit?, namesOnly?설정과 개수, 그다음 테이블 한 페이지를 돌려줍니다. 각 테이블에는 id, 캔버스 위의 위치와 크기, 컬럼 수, 그리고 인덱스와 관계가 함께 나오며, 테이블 뒤에는 검색 중이 아니라면 메모가 나옵니다.
erd_gettableIds?, tableNames?, relationshipIds?, indexIds?, memoIds?지정한 엔티티를 빠짐없이 돌려줍니다. 테이블은 컬럼과 함께, 관계는 그 컬럼과 onDelete, onUpdate와 함께, 인덱스는 그 컬럼과 함께, 메모는 텍스트와 함께 나옵니다.
erd_readformat, vendor?, tableIds?, tableNames?문서 전체를 세 가지 형식 중 하나로 한 번에 돌려주거나, 일부 테이블의 DDL만 돌려줍니다.

에이전트는 erd_list로 id를 찾고, erd_get으로 컬럼과 그 밖의 세부 내용을 읽은 뒤, 그 id를 편집 도구에 넘깁니다. erd_list의 테이블 크기는 캔버스에서 차지하는 상자의 크기입니다. 높이는 정확하고 너비는 근삿값입니다. 각 관계는 두 테이블 중 한쪽에 한 번만 나열됩니다.

erd_read는 세 가지 형식 중 하나를 받습니다.

format응답 내용
snapshot모든 엔티티와 그 id를 담은 간결한 JSON입니다. 스키마가 크면 커집니다.
sql8가지 데이터베이스 Databricks, MariaDB, MSSQL, MySQL, Oracle, PostgreSQL, Snowflake, SQLite 중 하나의 DDL입니다. vendor의 기본값은 문서에 설정된 데이터베이스입니다. tableIds나 tableNames를 주면 해당 테이블만, 그 테이블이 가진 foreign key와 함께 돌려줍니다. foreign key에는 ON DELETE와 ON UPDATE 동작이 함께 작성되며, 대상 데이터베이스가 생략하는 동작은 빠집니다. ON DELETE와 ON UPDATE 문서를 참고하세요.
json원본 .erd.json 문서입니다.

대규모 스키마​

테이블이 수백, 수천 개인 스키마에서도 동작합니다. 한 번의 읽기는 최대 40,000자까지 응답하며, 이는 Claude Code가 도구 결과를 파일로 따로 빼 두는 기준보다 작습니다.

  • erd_list는 기본적으로 테이블 100개를 한 페이지로 응답하고, 다음 페이지가 시작하는 위치를 nextOffset과 note로 알려 줍니다. 그 nextOffset을 같은 query와 함께 offset으로 넘기세요.
  • query는 테이블이나 컬럼의 이름 또는 코멘트에 들어 있는 단어로, 대소문자를 구분하지 않고 테이블을 찾습니다. 이름에 단어가 더 많이 들어 있는 테이블이 먼저 나옵니다.
  • namesOnly는 테이블 이름만 나열하며, 짧은 이름이라면 한 번의 응답에 약 2,000개를 담습니다.
  • erd_get과 erd_read는 id뿐 아니라 tableNames도 받으므로, 큰 스키마에서 SQL 쿼리를 요청받은 에이전트는 필요한 테이블의 DDL만 읽을 수 있습니다.
  • erd_get은 아무것도 가리키지 않는 id와 이름을 missing에, 한 번의 응답에 담지 못한 id를 notReturned에 나열하므로 다시 요청할 수 있습니다.
  • 한 번의 응답에 담기에 너무 큰 읽기는 범위를 좁히는 방법과 함께 tooLarge로 거부됩니다.

편집 도구​

id는 erd_list와 erd_get에서, 또는 엔티티를 만든 호출의 createdIds에서 얻습니다. x와 y는 캔버스 위의 왼쪽 가장자리와 위쪽 가장자리를 픽셀 단위로 나타내며, 색상은 #3b82f6과 같은 CSS hex 색상입니다.

테이블​

도구인자동작
erd_add_table빈 테이블을 비어 있는 자리에 추가하고 그 id를 createdIds로 돌려줍니다.
erd_remove_tabletableId테이블을 그 컬럼, 인덱스, 그리고 테이블에 닿는 모든 관계와 함께 삭제합니다.
erd_change_table_nametableId, value테이블 이름을 바꿉니다.
erd_change_table_commenttableId, value테이블 코멘트를 설정합니다. 빈 문자열을 주면 지웁니다.
erd_change_table_colortableId, color테이블 색상을 설정합니다.
erd_move_tabletableId, x, y테이블을 캔버스의 한 위치로 옮깁니다.
erd_move_tablespositions여러 테이블을 한 번의 편집으로 옮기며, erd_undo 한 번으로 되돌립니다. positions에는 테이블마다 { tableId, x, y }를 담으며, 각 테이블은 한 번만 올 수 있습니다.
erd_sort_tables가져오기가 테이블을 배치하는 방식대로, 컬럼이 적은 테이블부터 모든 테이블을 캔버스에 여러 줄로 배치합니다.

컬럼​

도구인자동작
erd_add_columntableId테이블에 빈 컬럼을 추가하고 그 id를 createdIds로 돌려줍니다.
erd_remove_columnstableId, columnIds한 테이블에서 컬럼을 삭제하며, 그 컬럼을 사용하는 관계와 인덱스 항목도 함께 삭제합니다.
erd_change_column_nametableId, columnId, value컬럼 이름을 바꿉니다.
erd_change_column_data_typetableId, columnId, valueINT나 VARCHAR(255) 같은 데이터 타입을 설정합니다. 관계 데이터 타입 동기화가 켜져 있으면 이 타입을 복사한 foreign key도 따라 바뀝니다.
erd_change_column_defaulttableId, columnId, value기본값을 SQL 텍스트로 설정합니다. 빈 문자열을 주면 지웁니다.
erd_change_column_commenttableId, columnId, value코멘트를 설정합니다. 빈 문자열을 주면 지웁니다.
erd_set_column_primary_keytableId, columnId, valuetrue는 컬럼을 primary key에 포함하고, false는 제외합니다.
erd_set_column_uniquetableId, columnId, value컬럼이 unique인지 설정합니다.
erd_set_column_not_nulltableId, columnId, value컬럼이 NOT NULL인지 설정합니다.
erd_set_column_auto_incrementtableId, columnId, value컬럼이 자동 증가하는지 설정합니다.
erd_move_columntableId, columnId, targetColumnId컬럼을 같은 테이블 안에서 다른 컬럼의 위치로 옮깁니다.

관계​

relationshipType은 자식 쪽 끝의 카디널리티이며, ZeroOne, ZeroN, OneOnly, OneN 중 하나입니다. 시작 테이블은 부모, 즉 primary key를 가진 참조되는 쪽이고, 끝 테이블은 자식입니다. onDelete와 onUpdate는 foreign key의 ON DELETE와 ON UPDATE 동작이며, none, noAction, cascade, setNull, setDefault, restrict 중 하나입니다. none은 절을 작성하지 않으므로 데이터베이스의 기본 동작이 적용됩니다. ON DELETE와 ON UPDATE 문서를 참고하세요. erd_add_relationship이나 erd_link_columns에서 생략한 동작은 none입니다.

도구인자동작
erd_add_relationshipstartTableId, endTableId, relationshipType, onDelete?, onUpdate?두 테이블을 관계로 연결합니다. 부모의 primary key를 자식에 foreign key 컬럼으로 복사하며, 부모에 primary key가 없으면 primary key 컬럼을 먼저 만듭니다. 각 foreign key 컬럼의 이름은 에디터에서 관계를 그릴 때와 같은 방식으로 정해집니다. users의 키 id는 users_id가 되고, member_id 같은 키는 이름이 그대로 유지됩니다. Foreign Key 컬럼 이름 문서를 참고하세요. createdIds에는 새로 만든 키 컬럼이 있으면 그 컬럼, foreign key 컬럼, 그리고 마지막으로 관계 id가 담깁니다.
erd_link_columnsstartTableId, startColumnIds, endTableId, endColumnIds, relationshipType, onDelete?, onUpdate?이미 있는 컬럼 사이에 관계를 그리며, 시작 컬럼과 끝 컬럼을 위치 순서대로 짝짓습니다.
erd_remove_relationshiprelationshipId관계 연결선을 삭제합니다. foreign key 컬럼은 테이블에 그대로 남습니다.
erd_change_relationship_typerelationshipId, relationshipType관계의 카디널리티를 바꿉니다.
erd_change_relationship_on_deleterelationshipId, onDelete관계의 ON DELETE 동작, 즉 부모 행을 삭제했을 때 자식 행에 일어나는 일을 설정합니다.
erd_change_relationship_on_updaterelationshipId, onUpdate관계의 ON UPDATE 동작, 즉 부모 키를 변경했을 때 자식 행에 일어나는 일을 설정합니다.

erd_add_relationship은 실행될 때 foreign key 컬럼의 이름을 정하므로, 부모 테이블과 그 primary key의 이름을 먼저 지정하세요.

오래된 ERD Editor 확장이나 플러그인, 즉 3.1.0 이전의 VS Code 확장, 0.2.0 이전의 Obsidian 플러그인, 0.10.0 이전의 JetBrains 플러그인은 문서를 담당할 때 ON DELETE와 ON UPDATE를 무시합니다. 이를 설정하는 도구는 그래도 성공하지만, 다이어그램에도 그 에디터가 저장하는 파일에도 그 동작은 남지 않으므로 확장이나 플러그인을 업데이트하세요. 업데이트 문서를 참고하세요. 문서를 담당하는 에디터가 없으면 그 동작은 다른 편집과 마찬가지로 파일에 쓰입니다.

인덱스​

인덱스 컬럼 id는 테이블 컬럼의 id가 아니라, erd_get이 알려 주는 인덱스 컬럼 목록의 항목입니다.

도구인자동작
erd_add_indextableId테이블에 빈 인덱스를 추가하고 그 id를 createdIds로 돌려줍니다.
erd_remove_indexindexId인덱스를 삭제합니다.
erd_change_index_nameindexId, value인덱스 이름을 바꿉니다.
erd_set_index_uniqueindexId, value인덱스가 unique인지 설정합니다.
erd_add_index_columnindexId, columnId인덱스가 속한 테이블의 컬럼을 추가하고 새 인덱스 컬럼 id를 돌려줍니다. 이미 인덱스에 있는 컬럼은 그대로 둡니다.
erd_remove_index_columnindexId, indexColumnId인덱스에서 컬럼 하나를 제거합니다.
erd_move_index_columnindexId, indexColumnId, targetIndexColumnId인덱스 안에서 컬럼을 그 인덱스의 다른 컬럼 위치로 옮깁니다.
erd_set_index_column_orderindexId, indexColumnId, orderType인덱스에서 컬럼 하나의 정렬 순서를 ASC 또는 DESC로 설정합니다.

메모​

도구인자동작
erd_add_memo빈 메모를 비어 있는 자리에 추가하고 그 id를 createdIds로 돌려줍니다.
erd_remove_memomemoId메모를 삭제합니다.
erd_change_memo_valuememoId, value메모의 텍스트를 교체합니다.
erd_change_memo_colormemoId, color메모 색상을 설정합니다.
erd_move_memomemoId, x, y메모를 캔버스의 한 위치로 옮깁니다.
erd_resize_memomemoId, width, height메모 크기를 바꿉니다. 너비는 약 116픽셀 이상, 높이는 100 이상이어야 합니다. 에디터는 드래그로 바꾼 메모 크기만 기록하므로, Undo 항목을 만들지 않습니다.

설정​

데이터베이스, Code Generator 옵션, 설정 탭의 항목처럼 문서에 저장되는 설정입니다. erd_set_show를 제외하면 어느 것도 Undo 항목을 만들지 않으므로, erd_undo로 되돌릴 수 없습니다.

도구인자값
erd_set_databasevalueMariaDB, MSSQL, MySQL, Oracle, PostgreSQL, SQLite, Databricks, Snowflake. 그 데이터베이스의 데이터 타입과, vendor를 주지 않았을 때 erd_read가 쓰는 DDL을 정합니다.
erd_set_database_namevalue데이터베이스 이름입니다.
erd_set_languagevalueCode Generator 언어입니다. GraphQL, csharp, Java, Kotlin, TypeScript, JPA, Scala, Go, SQLAlchemy, TypeORM, Sequelize, Drizzle, DBML, AML.
erd_set_table_name_casevalue생성되는 테이블 이름의 Name Case입니다. none, camelCase, pascalCase, snakeCase.
erd_set_column_name_casevalue컬럼 이름에 대한 같은 설정입니다.
erd_set_bracket_typevalue생성되는 SQL에서 이름을 감싸는 방식입니다. none, doubleQuote, singleQuote, backtick.
erd_set_relationship_data_type_syncvaluetrue면 foreign key 컬럼을 참조하는 컬럼의 데이터 타입에 맞춰 유지합니다.
erd_set_relationship_optimizationvalue문서에 저장되는 관계 최적화 플래그입니다.
erd_set_column_ordercolumnType, targetColumnType테이블 행의 한 부분을 다른 부분의 자리로 옮깁니다. columnName, columnDataType, columnNotNull, columnUnique, columnAutoIncrement, columnDefault, columnComment.
erd_set_max_width_commentvalue테이블에서 코멘트가 그려지는 최대 너비를 픽셀 단위로 지정하며, -1이면 제한이 없습니다.
erd_set_ignore_save_settingssaveSettingType, valuetrue면 저장되는 파일에서 scroll 또는 zoomLevel을 제외합니다. 새 문서는 에디터에서 만든 새 다이어그램과 마찬가지로 둘 다 true인 상태로 시작합니다. 스크롤 정보 저장 문서를 참고하세요.
erd_set_showshow, value다이어그램의 한 부분을 표시하거나 숨깁니다. tableComment, columnComment, columnDataType, columnDefault, columnAutoIncrement, columnPrimaryKey, columnUnique, columnNotNull, relationship, columnAlternateKey, hideReferentialAction. columnAlternateKey를 표시하면 각 대체 키의 컬럼에 AK1.1과 같은 표시가 붙습니다. hideReferentialAction은 의미가 반대입니다. true면 관계 연결선의 ON DELETE와 ON UPDATE 라벨을 숨기며, 이 라벨은 기본적으로 표시됩니다. 연결선 읽기 문서를 참고하세요.

가져오기​

이 도구들은 모두 문서 전체를 대체하며, erd_undo는 그 전의 문서를 복원합니다. 에디터의 Import 메뉴와 같은 방식으로 스키마를 읽습니다. 파일 가져오기와 내보내기 문서를 참고하세요.

도구인자동작
erd_import_sqlvalueCREATE TABLE 문 같은 SQL DDL을 불러옵니다.
erd_import_graphqlvalueGraphQL SDL을 불러옵니다.
erd_import_dbmlvalueDBML을 불러옵니다.
erd_import_amlvalueAML을 불러옵니다.
erd_import_jsonvalue다른 .erd.json 파일 같은 erd-editor JSON 문서를 불러옵니다. 빈 텍스트를 주면 erd_open_document가 create로 만드는 문서와 같은 새 문서가 됩니다.

erd_batch​

erd_batch는 여러 편집 도구를 순서대로, 전부 적용하거나 전혀 적용하지 않는 하나의 편집으로 실행합니다.

  • operations에는 최대 100개의 항목을 담으며, 각 항목은 { tool, as?, args? }이고 args는 path를 뺀 도구의 인자입니다.
  • 작업은 먼저 문서의 복사본에서 시도됩니다. 거부된 작업은 operations[1] erd_remove_table: …처럼 이름이 표시되며, 아무것도 적용되지 않습니다.
  • erd_undo 한 번으로 배치 전체를 되돌립니다. 결과의 historyEntries는 erd_undo 호출 횟수가 아니라 배치 안의 에디터 히스토리 항목 수를 셉니다.
  • 라이브 세션에서는 에디터가 배치 전체를 받아들이거나 전혀 받아들이지 않습니다.

에이전트는 호출하기 전에는 배치가 만들 id를 알 수 없으므로, as로 이름을 붙인 작업은 뒤의 작업이 그 id를 참조할 수 있게 합니다. 첫 번째로 만든 id는 $name 또는 $name.0, 두 번째는 $name.1, 마지막은 $name.last입니다. 이름은 ASCII 영문자, 숫자, 밑줄로 이루어지고, 숫자로 시작할 수 없으며, 한 작업에만 붙일 수 있습니다. 참조는 엔티티 id를 받는 인자에서만 해석되므로, $x라고 쓴 이름이나 코멘트는 텍스트로 남습니다.

한 번의 호출로 테이블과 컬럼, 관계를 만드는 예입니다.

{
  "path": "shop.erd.json",
  "operations": [
    { "tool": "erd_add_table", "as": "users" },
    { "tool": "erd_change_table_name", "args": { "tableId": "$users", "value": "users" } },
    { "tool": "erd_add_column", "as": "uid", "args": { "tableId": "$users" } },
    { "tool": "erd_change_column_name", "args": { "tableId": "$users", "columnId": "$uid", "value": "id" } },
    { "tool": "erd_change_column_data_type", "args": { "tableId": "$users", "columnId": "$uid", "value": "BIGINT" } },
    { "tool": "erd_set_column_primary_key", "args": { "tableId": "$users", "columnId": "$uid", "value": true } },
    { "tool": "erd_add_table", "as": "orders" },
    { "tool": "erd_change_table_name", "args": { "tableId": "$orders", "value": "orders" } },
    { "tool": "erd_add_relationship", "args": { "startTableId": "$users", "endTableId": "$orders", "relationshipType": "ZeroN", "onDelete": "cascade" } }
  ]
}

관계보다 먼저 users와 그 키 id의 이름을 지정하므로, 관계가 orders에 추가하는 foreign key 컬럼은 users_id가 됩니다.

결과​

편집은 한 줄의 JSON으로 응답합니다.

{"tool":"erd_add_table","mode":"live","createdIds":["b7u59tHkuXTA1hhtWh_bD"],"batches":1,"historyEntries":1}
필드의미
modelive 또는 headless입니다. 라이브와 헤드리스 문서를 참고하세요.
createdIds호출이 만든 것의 id를 순서대로 담습니다.
batches, historyEntries호출이 보낸 변경 배치 수와, 만든 에디터 히스토리 항목 수입니다.
undoable, undoNoteerd_undo가 이 호출을 건너뛸 때 undoable은 false이고, undoNote가 그 이유를 알려 줍니다. 도구가 Undo 항목을 만들지 않거나, 문서가 이미 그 값을 가지고 있던 경우입니다. erd_batch 결과에는 항상 undoNote가 있으며, erd_undo 한 번으로 배치 전체를 되돌린다고 알려 줍니다.
mismatch호출이 만든 배치 수나 히스토리 항목 수가 도구가 선언한 수와 다를 때 들어 있습니다.
notes에디터가 종료되거나 문서를 더 이상 담당하지 않게 되거나, 디스크의 파일이 바뀌는 등 세션에 변화가 있었을 때 들어 있습니다.

거부는 코드와, 무엇을 해야 하는지 알려 주는 메시지를 담은 오류 결과입니다.

{"error":{"code":"notFound","message":"tableId nope names no live table; read the document for current ids"}}
code이유
notFoundid가 가리키는 대상이 현재 문서에 없거나, 파일이 존재하지 않습니다.
invalidArgs인자가 빠졌거나 값이 잘못되었습니다.
invalidPath경로가 ERD 문서가 아닙니다. Windows에서는 Windows가 적힌 그대로 저장하지 않는 이름이 들어간 경로이거나, 에디터가 다른 경로로 담고 있는 문서에 닿는 경로일 때도 해당하며, 메시지에 그 다른 경로가 표시됩니다.
invalidDocument파일이 에디터가 읽을 수 있는 문서가 아닙니다.
tooLarge읽기 결과가 한 번의 응답에 담기지 않습니다.
blocked허브가 꺼진 에디터가 문서를 담고 있습니다. 메시지에 허브를 켜는 방법이 나옵니다. VS Code에서는 워크스페이스를 신뢰하고 dineug.erd-editor.agentHub.enabled를 켜거나 창을 다시 로드하고, Obsidian에서는 Coding agents를 켜거나 Obsidian을 다시 로드하고, JetBrains IDE에서는 Coding agents를 켜거나, 켜져 있다면 IDE를 다시 시작합니다.
hubDisabledJetBrains IDE가 신뢰하지 않는 프로젝트에서만 문서를 담고 있습니다. 읽기는 그대로 동작하며, 에이전트가 편집하게 하려면 프로젝트를 신뢰하세요.
conflict호출 중에 디스크의 파일이 바뀌었습니다. 아무것도 쓰지 않았습니다.
hubAppeared, hubGone에이전트가 디스크에서 편집하던 문서를 에디터가 맡기 시작했거나, 문서를 맡던 에디터가 아직 실행 중이지만 잠금 파일과 연결이 사라졌습니다. 아무것도 쓰지 않았습니다.
notSavederd_save가 에디터의 문서를 저장하지 못했습니다.
readonly쓸 수 없거나 다이어그램으로 읽을 수 없는 파일처럼, 에디터가 문서를 읽기 전용으로 담고 있습니다. 에디터가 없으면 체크아웃하지 않은 Perforce 또는 TFVC 파일처럼 파일 자체가 읽기 전용입니다. 아무것도 쓰지 않았습니다.
protocolMismatch에디터의 ERD Editor 확장이나 플러그인과 서버가 서로 다른 프로토콜 버전을 사용합니다.
hubUnreachable, timeout, disconnected에디터의 허브가 연결을 받아들이지 않았거나, 30초 안에 응답하지 않았거나, 호출 중에 연결을 끊었습니다. Windows에서 hubUnreachable은 Windows가 에이전트의 허브 접근을 막았다는 뜻이기도 합니다. 에디터를 관리자 권한으로 실행했는데 에이전트는 그렇지 않은 경우처럼 에디터가 에이전트보다 높은 권한으로 실행되거나, 에이전트가 샌드박스에서 실행되는 경우입니다.

그 밖의 코드는 드물게 나오며, 모든 거부에는 무슨 일이 있었는지 알려 주는 메시지가 담깁니다.

편집 도구, erd_batch, 세 가지 읽기 도구는 선언하지 않은 인자나 타입이 잘못된 인자를 문서를 건드리기 전에 JSON-RPC invalid params 오류(-32602)로 거부하므로, 철자가 틀린 인자가 조용히 버려지는 일은 없습니다. 세션 도구 5개는 모르는 인자를 무시합니다.