Режими Live і Headless

Під час кожного виклику сервер шукає редактор, який тримає документ, за файлами блокування, які редактори зберігають у ~/.erd-editor/ide/. Кожне вікно VS Code і кожне вікно сховища (vault) Obsidian з ERD Editor зберігає по одному такому файлу, а IDE від JetBrains зберігає один файл на всю IDE, у якому перелічено всі відкриті в ній проєкти. Редактор видаляє свій файл блокування, коли закривається. Від того, що знайде сервер, залежить, куди піде зміна.

Що знайдено	Що робить зміна
Редактор, робоча область, сховище або відкритий проєкт якого містить документ або в якому цей документ відкрито	Live. За потреби відкриває документ в ERD Editor, приєднується до сеансу редагування й застосовує зміну там. Зміни з’являються одразу й зберігаються так само, як редактор зберігає ваші, — див. збереження.
Редактора немає	Headless. Завантажує файл, застосовує зміну й замінює файл ще до відповіді, тож результат містить saved: true, а інструмент erd_save не має чого робити.
Редактор із вимкненим хабом	Відхилено. Читання все одно працює — з диска. Зміну, записану у файл в обхід відкритого редактора, могло б перезаписати наступне збереження цього редактора, тому сервер нічого не записує.
Редактор, хаб якого ввімкнено, але який використовує інший протокол, ніж сервер: із сервером версії 1.0.0 або новішої — розширення для VS Code версії 3.x, плагін для Obsidian версії 0.x або плагін для JetBrains версії 0.9.0 чи 0.10.0; із сервером до версії 1.0.0 — розширення версії 4.0.0 або новішої чи плагін версії 1.0.0 або новішої	Відхилено, зокрема й читання, з кодом protocolMismatch. Повідомлення називає сторону, яку треба оновити: розширення чи плагін або сервер — див. оновлення.
У Windows редактор, який тримає документ за іншим шляхом до того самого файлу: агент указав його через спільний мережевий ресурс або підключений диск цього комп’ютера, як-от \\localhost\C$\…, а редактор тримає його за шляхом із літерою диска, або навпаки	Відхилено, зокрема й читання, з кодом invalidPath. Повідомлення називає шлях, за яким редактор тримає документ; повторіть виклик із цим шляхом.
У Windows редактор, до якого Windows не допускає агента: запущений від імені адміністратора, тоді як агента — ні, або будь-який редактор, коли агент працює в пісочниці	Відхилено, зокрема й читання, з кодом hubUnreachable і повідомленням, яке пояснює причину. Запустіть редактор і агента з однаковими правами, наприклад запустивши редактор знову без прав адміністратора.

Результат зміни називає режим, у якому її виконано, — live або headless, а відхилена зміна повідомляє причину. Пошук виконується заново під час кожного виклику, тож відкриття або закриття редактора переспрямовує вже наступний виклик.

Коли документ тримає більше ніж один редактор, редактор, у якому його відкрито, має перевагу над тим, що лише обслуговує папку з ним, а серед тих, що обслуговують папку, перемагає той, чия папка лежить найглибше. За рівності, як-от коли документ відкрито в обох редакторах, перевага дістається тому, чий файл блокування змінився останнім. Тож документ у сховищі Obsidian, розташованому всередині папки робочої області VS Code, дістається Obsidian, хіба що його відкрито у VS Code, а в Obsidian — ні.

Виклики для одного документа виконуються по одному, у тому порядку, в якому вони надійшли на сервер. Виклики для різних документів виконуються паралельно.

Live

Агент приєднується до редактора як ще один співавтор. Його зміни одразу доходять до всіх редакторів, у яких відкрито документ, а його фокус відображається на таблиці й клітинці, які він редагує, так само, як фокус співавтора, — див. focusTracker.

Читання ніколи не відкриває редактор. Зміна відкриває документ в ERD Editor, якщо його ще не відкрито, не забираючи фокус клавіатури.

Редактор із розширенням для VS Code до версії 4.2.0 або плагіном для Obsidian чи JetBrains до версії 1.2.0 усе одно приймає зміни агента в режимі Live, але не показує й не зберігає логічних назв, прив’язок до доменів і рядків словників, які записує агент, — див. оновлення.

З розширенням для VS Code версії 4.3.0 або новішої чи плагіном для Obsidian або JetBrains версії 1.3.0 або новішої імпорт у режимі replace та erd_undo чи erd_redo такого імпорту завершують малювання зв’язку в редакторі, незалежно від випуску сервера — див. створення зв’язків. До цих випусків малювання лишалося активним, а клацання таблиці могло додати зв’язок від таблиці, якої вже немає в діаграмі. Імпорт у режимі append залишає малювання активним. Відкритий вами редактор нотатки, назви групи таблиць чи клітинки лишається відкритим, доки діаграма все ще містить і показує те, що він редагує.

Зміни в один і той самий момент

Із сервером 1.2.0 або новішим і, в редакторі, з розширенням для VS Code версії 4.3.0 або новішої чи плагіном для Obsidian або JetBrains версії 1.3.0 або новішої зміни, які ви й агент в один і той самий момент вносите в те саме, завершуються однаково в редакторі, у файлі, який він зберігає, і в тому, що erd_list, erd_get та erd_read дають агентові. Це охоплює назву чи інше поле таблиці, стовпця, зв’язку, індексу, нотатки, групи таблиць або рядка словника, назву бази даних і скрипти перед таблицями й після них, а також положення чи розмір таблиці, нотатки або групи таблиць, але не колір, не порядок стовпців у таблиці чи індексі й не базу даних. Дві зміни однієї назви чи поля, два переміщення або дві зміни розміру закінчуються на одній із двох, ніколи на суміші: перемагає зміна, зроблена після того, як інша дійшла до свого боку, а з двох зроблених у той самий момент перемагає одна, на кожному боці та сама, хоч яка надійде першою.

Дві зміни кольору однієї таблиці, нотатки чи групи таблиць, зроблені в один і той самий момент, як-от ваша й erd_change_table_color агента, можуть закінчитися по-різному або навіть помінятися місцями, бо кожен бік зберігає колір, який почув останнім. Зміна порядку стовпців, ваша чи erd_move_column або erd_move_index_column агента, застосовується на кожному боці в порядку надходження, тож дві зміни, зроблені в один і той самий момент в одній таблиці чи індексі, можуть залишити її стовпці в різному порядку. Зміна бази даних, ваша чи erd_set_database агента, теж застосовується в порядку надходження, тож дві зміни, зроблені в один і той самий момент, можуть залишити редактор і агента з різними базами даних.

Ваше перетягування й erd_move_table, erd_move_tables, erd_move_memo, erd_move_table_group та erd_sort_tables агента передаються як точки, в яких вони закінчуються, тож два переміщення однієї таблиці, нотатки чи групи таблиць закінчуються там, куди її поставило одне з них, а не в сумі обох. erd_move_table_group надсилає точку групи й кожної з її таблиць одним пакетом, як і перетягування смуги заголовка групи. Зміна розміру записує положення й розмір разом, тож переміщення й зміна розміру однієї нотатки чи групи таблиць у той самий момент, як-от erd_resize_memo, поки ви перетягуєте цю нотатку, закінчуються на одному прямокутнику з обох боків: прямокутнику зміни розміру або, коли перемагає переміщення, точці переміщення з розміром зміни розміру. Переміщення менш ніж на 20 пікселів, яке не створює запису відміни, теж надсилається як точка, в якій воно закінчується, тож воно може перемогти переміщення з іншого боку, хай то короткий erd_move_table_group чи ваше коротке перетягування, як-от клацання, що зсуває таблицю на кілька пікселів.

Старіші випуски все одно підключаються, бо сервер 1.2.0 розуміє протокол хаба 2, як і версії від 1.0.0 до 1.1.1. Із сервером до версії 1.2.0, розширенням до версії 4.3.0 чи плагіном до версії 1.3.0 переміщення або зміна розміру однієї таблиці, нотатки чи групи таблиць у той самий момент може залишити редактор і агента з різними положеннями. Старіший редактор надсилає ваше перетягування як пройдену відстань, і сервер до версії 1.2.0 так само надсилає erd_move_table_group. Інший бік додає цю відстань до точки, яку тримає. Старіший бік також застосовує точки іншого боку в порядку надходження. Тоді агент читає й редагує від власного положення для цієї таблиці, нотатки чи групи таблиць, а не від того, яке показує і зберігає редактор. Так триває, доки пізніше переміщення не буде передано як точку, як-от ваше перетягування в новішому редакторі чи erd_move_table агента, або доки агент знову не приєднається до документа, як-от після того, як редактор його відкинув, або після 30 хвилин без виклику на документі. Окрім кольору, порядку стовпців і бази даних, назва чи інше поле, змінені в той самий момент, усе одно завершуються однаково, коли старіший лише один бік, майже завжди на зміні новішого боку. Коли обидва боки старіші, обидві зміни все ще можуть закінчитися по-різному.

Нічого з цього не стосується редагування в режимі Headless, яке записує лише файл.

Збереження

Кожен редактор зберігає зміни агента так само, як зберігає ваші.

У VS Code зміни агента, як і ваші, позначають вкладку як незбережену й потрапляють на диск лише після збереження документа. Інструмент erd_save зберігає його через VS Code так само, як і власна команда збереження VS Code. Натомість ви можете зберегти його самі, натиснувши Ctrl + S (Windows/Linux) або ⌘ + S (Mac). Якщо закрити редактор із незбереженими змінами агента, з’явиться запит, чи зберегти їх, як і для будь-якої іншої незбереженої зміни.

Obsidian зберігає зміни агента приблизно через дві секунди після завершення редагування, а закриття вкладки зберігає їх без запиту. IDE від JetBrains записує їх через частку секунди після завершення редагування, а закриття вкладки записує те, що ще не записано; вкладка ніколи не позначається як змінена. В обох випадках інструмент erd_save записує їх одразу.

Інструмент erd_save спершу чекає до двох секунд, поки в редакторі опиняться всі зміни, які зробив агент. Виклик відхиляється з кодом notSaved, коли редактор не зміг цього підтвердити або не записав файл: VS Code залишає вкладку незбереженою, якщо файл змінився на диску, а IDE від JetBrains не змогла його записати, наприклад поки було відкрито діалогове вікно або коли файл неможливо записати.

У VS Code та IDE від JetBrains виклик erd_save для документа, у якому нічого не залишилося зберегти, завершується успішно й залишає файл без змін. Так буває, щойно всі зміни збережено, що IDE від JetBrains робить самостійно, і так залишається, поки кожна наступна зміна — це зміна, яку блокування не допускає до файлу, як-от прокручування чи масштабування, коли заблоковано Viewport, перемикання вкладок, коли заблоковано Canvas Type, або перемикання відображення назв, коли заблоковано Name View. Усі блокування ввімкнено за замовчуванням. Для файлу, який IDE від JetBrains не може записати, виклик відхиляється навіть тоді.

Коли редактор закриває документ після останньої зміни агента, наступний виклик агента містить примітку про те, що ці зміни є у файлі, лише якщо їх було збережено до закриття редактора.

Відміна

Інструмент erd_undo відміняє останню зміну, зроблену агентом, і ніколи — вашу, а erd_redo знову її застосовує. Власна відміна редактора працює навпаки: вона відміняє ваші зміни й ніколи — зміни агента, бо зміни, що надходять з іншого редактора, не записуються у вашу історію змін.

Кілька змін не створюють у редакторі кроку відміни: erd_set_database і erd_set_database_name серед інструментів налаштувань, а також erd_resize_memo. Так само його не створює виклик erd_move_table_group, який переміщує групу загалом менш ніж на 20 пікселів, якщо скласти зсув по горизонталі й по вертикалі, хоча група залишається там, куди її переміщено. Не створює його й виклик, який нічого не змінює: erd_set_column_primary_key, erd_set_column_unique, erd_set_column_not_null, erd_set_column_auto_increment, erd_set_index_unique або erd_set_index_column_order, що задають значення, яке документ уже містить; erd_add_index_column зі стовпцем, який уже є в індексі; erd_set_table_group з таблицями, які вже входять до цієї групи (або вже не входять до жодної, коли groupId має значення null); erd_move_table_group у точку, де група вже стоїть; erd_resize_table_group до прямокутника, який група вже має; erd_sort_tables для документа без таблиць; erd_set_table_logical_name або erd_set_column_logical_name з логічною назвою, яку таблиця чи стовпець уже має, коли формування з неї нічого б не змінило; erd_set_column_domain з доменом, до якого стовпець уже прив’язано, коли стовпець уже має тип цього домену, а синхронізація типів даних у зв’язках не змінила б типу жодного стовпця вздовж його зв’язків; erd_update_word, erd_update_term або erd_update_domain лише зі значеннями, які рядок уже містить, хіба що терміну без фізичної назви передано його name і його слова складають фізичну назву; erd_derive_physical_names, коли кожна охоплена ним назва, для якої є логічна назва, уже містить те, що їй дають словники, і позначена як сформована; або імпорт з аргументом mode зі значенням append, який не додає жодної таблиці (для erd_import_json — жодної таблиці й жодної нотатки). Інструмент erd_undo пропускає такі виклики й називає їх у своєму результаті. Інші зміни, як-от erd_change_relationship_type, erd_change_relationship_on_delete, erd_change_relationship_on_update, erd_change_table_group_name, erd_change_table_group_color і erd_set_ddl_script, створюють крок відміни навіть тоді, коли задають значення, яке документ уже містить.

Історія змін агента обривається, і результат містить про це примітку, коли:

• Агент знову приєднується до документа, наприклад після того, як редактор від’єднав від нього агента.
• Редактор завершує роботу або закриває документ і перестає його обслуговувати, а агент продовжує редагувати файл на диску.
• Редактор перебирає на себе документ, який агент редагував на диску.

Сервер також закриває документ, до якого агент не звертався 30 хвилин, і разом із ним зникає історія змін — без примітки.

Коли редактор зникає

Поки документ тримає редактор, сервер ніколи сам не переходить до роботи з файлом. Якщо з’єднання обривається, він підключається знову. Лише коли редактор завершив роботу або закрив документ і більше не перелічує ні його, ні папку з ним, сервер редагує файл і повідомляє про це в результаті. Так стається, коли ви закриваєте діаграму, що лежить поза всіма папками, які обслуговує редактор (у VS Code — діаграму, відкриту поза робочою областю), коли ви вимикаєте плагін ERD Editor в Obsidian і коли ви закриваєте проєкт, що містить документ, в IDE від JetBrains або вимикаєте там плагін. Закрита діаграма в папці, яку обслуговує редактор, залишається за редактором, а наступна зміна агента знову її відкриває.

Редактор, який ще працює, але файл блокування якого зник, а з’єднання закрилося, хоча сам він документ не закривав, відхиляє наступну зміну з кодом hubGone. Повідомлення пояснює, що звільнить документ: у VS Code перезавантажте це вікно або закрийте його, щоб агент редагував файл напряму; в Obsidian знову ввімкніть плагін ERD Editor або закрийте це вікно; в IDE від JetBrains знову ввімкніть плагін або вийдіть з IDE.

У двох випадках читання натомість звертається до файлу на диску й додає примітку, що змін, ще не збережених у редакторі, у ньому немає: коли в редакторі, що тримає документ, вимкнено хаб, і в описаному вище випадку hubGone. Читання, яке не може підключитися до хаба редактора, відхиляється з кодом hubUnreachable, так само як і зміна.

Headless

Коли документ не обслуговує жоден редактор, кожна операція редагування завантажує файл, застосовує зміну й записує файл назад ще до відповіді, тож її результат містить saved: true — див. результати. Запис іде в тимчасовий файл поруч із документом з назвою .<name>.<id>.tmp, який потім замінює документ, тож документ ніколи не залишається записаним наполовину, крім описаного нижче випадку запису на місці у Windows.

Перед цим останнім кроком сервер перевіряє, чи не змінився файл на диску під час виклику. Якщо змінився, нічого не записується, файл завантажується знову, а виклик відхиляється з кодом conflict. Агент повторює виклик. Файл, що змінився між двома викликами, просто завантажується знову, а попередня історія змін агента відкидається.

Файл лише для читання залишається без змін, а зміна відхиляється з кодом readonly: це файл без дозволу на запис для власника або, у Windows, з атрибутом «лише для читання», як-от файл Perforce чи TFVC, не взятий на редагування (check out). Зробіть його доступним для запису й повторіть виклик. Читання все одно працює.

Якщо редактор починає обслуговувати документ, поки агент редагує його на диску, саме ця зміна відхиляється з кодом hubAppeared і нічого не записується. Наступний виклик редагує через редактор.

У Windows діють ще два правила:

• Документ із власними дозволами, відмінними від дозволів його папки, записується на місці замість заміни, щоб зберегти їх, а тимчасовий файл потім видаляється. Програма, що читає документ під час такого запису, може натрапити на текст, який не вдається розібрати.
• Файл, який тримає відкритим інша програма, неможливо замінити, тому сервер повторює спроби протягом щонайбільше двох секунд. Кожна спроба спершу знову шукає редактор, і редактор, який тим часом почав обслуговувати документ, відхиляє запис з кодом hubAppeared або, якщо його хаб вимкнено, з кодом blocked. Якщо через дві секунди файл усе ще зайнятий, нічого не записується, файл завантажується знову, а виклик завершується невдачею з повідомленням, яке наводить текст системної помилки.

Сервер до версії 1.1.0 читає документ без його логічних назв, прив’язок його стовпців до доменів і його слів, термінів і доменів, тож перша зміна, яку він записує у файл, їх пропускає. Оновіть сервер — див. оновлення.

Відхилено

Вікно VS Code зберігає свій файл блокування, навіть коли його хаб вимкнено: коли вимкнено налаштування dineug.erd-editor.agentHub.enabled, коли робочу область не позначено як довірену або коли його хаб не зміг почати прослуховування. Вікно сховища Obsidian зберігає свій файл блокування за вимкненого хаба, коли вимкнено параметр Coding agents і коли його хаб не зміг почати прослуховування. IDE від JetBrains зберігає свій файл блокування за вимкненого хаба, коли вимкнено параметр Coding agents, коли її хаб не зміг почати прослуховування і поки IDE завершує роботу.

Зміна такого документа відхиляється з кодом blocked, бо відкритий редактор міг би перезаписати записану у файл зміну під час свого наступного збереження. Читання все одно працює — з файлу на диску.

Щоб агент міг редагувати, знову ввімкніть хаб, як пояснює повідомлення для цього редактора: у VS Code позначте робочу область як довірену й увімкніть налаштування або перезавантажте вікно; в Obsidian увімкніть параметр Coding agents або перезавантажте Obsidian; в IDE від JetBrains увімкніть параметр Coding agents або, якщо його вже ввімкнено, перезапустіть IDE.

IDE від JetBrains також відмовляється з кодом hubDisabled змінювати документ, який тримають лише проєкти, яким вона не довіряє. Агенти все одно можуть читати такий документ, а erd_list_documents перелічує його з позначкою readonly. Позначте проєкт як довірений і повторіть виклик.

Редактор, який не зберігає файлу блокування, нічого не захищає, і агент редагує файл на диску, навіть коли діаграму в ньому відкрито. Так буває з Obsidian або IDE від JetBrains, встановленими як Flatpak у Linux, з IDE від JetBrains без JCEF і з IDE від JetBrains, хаб якої не зміг запуститися, — див. налаштування Obsidian і налаштування IDE від JetBrains. Розширення для VS Code до версії 3.0.0 і плагін для JetBrains до версії 0.9.0 теж не зберігають такого файлу, бо не мають хаба.

Документи

Документ задається аргументом path — абсолютним шляхом або шляхом відносно робочого каталогу сервера.

• Нові документи — це файли .erd.json. Інструмент erd_open_document з аргументом create створює файл і додає .erd.json до назви без розширення. Як і в нової діаграми в редакторі, у нового документа ввімкнено всі блокування, тож прокручування, масштабування, перемикання вкладок, перемикання відображення назв або вибір іншої мови генератора коду, стилю назв чи типу лапок у редакторі ніколи не змінює файл. Жоден інструмент не вмикає й не вимикає окреме блокування: це ви робите на вкладці налаштувань редактора. Інструмент erd_import_json у режимі replace замінює їх усі блокуваннями документа, який він завантажує, — див. імпорт.
• Наявні файли .erd, .vuerd і .vuerd.json теж відкриваються. Шлях з будь-яким іншим розширенням відхиляється з кодом invalidPath.
• У Windows шлях, що містить назву, яку Windows не зберігає так, як її написано, відхиляється з кодом invalidPath ще до читання чи запису документа, зокрема й для читання: назва з двокрапкою або іншим символом, який Windows не приймає, як-от orders:v2.erd; назва пристрою, як-от NUL.erd або CON.erd, у будь-якому регістрі; або назва, що закінчується крапкою чи пробілом. Перейменуйте файл, наприклад поставивши - замість :.
• Файл, що не є документом, який може прочитати редактор, як-от файл із залишеними маркерами конфлікту злиття, відхиляється з кодом invalidDocument і залишається без змін. Він ніколи не завантажується як порожня діаграма й не записується назад.

Агент змінює документ лише за допомогою інструментів, і йому вказано ніколи не записувати файл самостійно.

Інструмент erd_list_documents перелічує документи з полями path, open, active, dirty і readonly. Він звертається до редактора, який обслуговує робочий каталог і вибирається так само, як для документа, і перелічує відкриті в ньому діаграми, а потім ERD-файли, які він обслуговує: ті, що лежать у папках робочої області вікна VS Code, у сховищі Obsidian або в усіх відкритих проєктах IDE від JetBrains. Інакше він перелічує ERD-файли в межах робочого каталогу, де файл лише для читання позначається як readonly, а у Windows назва, яку Windows не зберігає так, як її написано, пропускається.