Zadeklarowane kolumny rozszerzeń
Zainstalowany pakiet modułu może dodać kilka własnych kolumn do tabeli rdzenia — na przykład
kod ERP organizacji — bez edytowania rdzenia, bez ręcznie pisanego alter table i bez ryzyka, że
zginą przy następnej aktualizacji platformy. Pakiet je deklaruje, a resztą zajmuje się platforma.
To stopień D2 drabiny danych opisanej na stronie Drabina dostosowań. Najpierw spróbuj niższych stopni: operator może dodać pole niestandardowe w czasie działania bez żadnego kodu (D0), a tabela poboczna, której właścicielem jest twój moduł (D1), niczego od gospodarza nie wymaga. Po zadeklarowane kolumny sięgaj wtedy, gdy wartość należy do wiersza gospodarza — jest z nim odczytywana, indeksowana i unikalna w jego obrębie.
Co możesz rozszerzyć
Rozszerzalne tabele to dokładnie te tabele, które mają pola niestandardowe — są wyprowadzane z powiązań gospodarzy pól niestandardowych, nigdy nie wypisuje się ich po raz drugi. W tym wydaniu otwarta jest jedna:
| Tabela | Moduł-właściciel |
|---|---|
organizations | organizations |
Pozostałych ośmiu gospodarzy pól niestandardowych (customer_accounts, orders,
quote_requests, products, categories, crm_opportunities, projects, tasks) zostanie
otwartych w późniejszym wydaniu. Deklaracja w tabeli, która nie jest otwarta, jest odrzucana, gdy
platforma wykrywa pakiet, a komunikat wymienia tabele otwarte.
Reguły
- Deklaruje tylko zainstalowany pakiet. Pakiet modułu z własnego repozytorium platformy jest właścicielem swoich tabel albo używa tabeli pobocznej, a moduł nakładkowy wdrożenia nie zawiera schematu; generator odrzuca oba przypadki.
- Musisz zależeć od gospodarza. Moduł-właściciel gospodarza musi należeć do domknięcia
dependenciestwojego manifestu, inaczej deklaracja jest odrzucana (host-not-a-dependency). - Kolumny są twoje i tylko twoje. Ich fizyczne nazwy to
x_<moduleId>_<snake_case(klucz)>; zapisuje je wyłącznie kod twojego modułu, przez opisany niżej akcesor, wewnątrz polecenia (Command) albo haka polecenia. Gospodarz zachowuje tabelę, jej ograniczenia i każdą kolumnę, której nie zadeklarowałeś. - Tylko addytywnie. Kolumna ma typ
text,varchar(zlength),boolean,smallint,integer,bigint,numeric(zprecisioniscale),date,timestamptz,uuidalbojsonb(ze schematem Zod wschema). Dopuszczanullalbo jest NOT NULL ze stałą wartościądefault;timestamptzijsonbzawsze dopuszczająnull.index: truetworzy indeks btree,index: 'unique'— unikalny indeks częściowy po wartościach różnych odnull(tylko dla kolumn dopuszczającychnull). Najwyżej 32 kolumny w deklaracji; nazwa fizyczna dłuższa niż 63 bajty jest odrzucana. - Dwa klucze są zarezerwowane:
idiorganizationIdto własne kolumny gospodarza, które platforma mapuje za ciebie; deklaracja z którymkolwiek z nich jest odrzucana (key). - Nazwy fizyczne są unikalne między modułami.
x_<moduleId>_<snake_case(klucz)>może wyjść taka sama dla dwóch modułów (acme+erpCodeiacme_erp+codeto w obu przypadkachx_acme_erp_code); wykrywanie odrzuca drugą deklarację zphysical-name-collision, podając oba moduły. Uzupełnianie danych może ustawiać wyłącznie dokładnie te kolumny, które twój moduł deklaruje. - Zmiana kolumny nie jest oferowana. Zmiana typu, dopuszczalności
nullalbo wartości domyślnej klucza jest odrzucana (non-additive-change) — zadeklaruj nowy klucz. Usunięcie klucza oznacza jego kolumnę jako osieroconą; kolumna nie jest usuwana. - Jeszcze nie oferowane: filtry i sortowanie list po kolumnach rozszerzeń, dane rozszerzeń w
treści zapisów HTTP rdzenia, wyszukiwarka, eksporty, pliki PDF, odpowiedzi sklepu i zdarzenia.
Deklaracja z
filterablealbosortablejest odrzucana jakonot-offered-yet.
Przykład
Pakiet acme_erp dodaje trzy kolumny do organizations. Jego źródła to dane testowe samej
platformy, sprawdzane kompilatorem przy każdym uruchomieniu, więc ta strona nie może się
rozjechać z tym, co się kompiluje.
Deklaracja:
export const acmeOrganizationColumns = defineColumnExtension({
host: 'organizations',
module: 'acme_erp',
adminReads: true,
columns: {
erpCode: { type: 'varchar', length: 64, nullable: true, index: 'unique' },
creditTier: { type: 'smallint', default: 0 },
onboardedVia: { type: 'text', nullable: true },
},
});
Eksport ./backend pakietu wymienia ją obok encji:
export const schemaExtensions = [acmeOrganizationColumns];
export const entities = [];
Manifest pakietu zależy od gospodarza: dependencies: ['organizations'].
Po pnpm install i migrate tabela organizations ma kolumny x_acme_erp_erp_code,
x_acme_erp_credit_tier i x_acme_erp_onboarded_via, unikalny indeks częściowy na pierwszej z
nich, a rejestr platformy schema_extensions zapisuje każdy element. Encja rdzenia
Organization, jej odpowiedzi i jej wpisy audytu pozostają bez zmian.
Zapis z polecenia
extensionColumns(declaration, em) zwraca get(id), load(ids) i set(id, patch). set wykonuje
jedno UPDATE wyłącznie zmienionych kolumn, nigdy nie wstawia wiersza, odmawia działania poza
transakcją i zwraca zmienione klucze — nigdy ich wartości — do wpisu audytu:
export function syncErpCode(organizationId: string, erpCode: string): Command<void> {
return {
action: 'acme_erp.organization.sync',
objectType: 'organization',
objectId: organizationId,
async run({ em }) {
const { changedFields } = await extensionColumns(acmeOrganizationColumns, em).set(
organizationId,
columnExtensionPatchSchema(acmeOrganizationColumns).parse({ erpCode }),
);
// audit-state D-288: names, never values.
return { result: undefined, after: { extensions: { acme_erp: { changedFields } } } };
},
};
}
ColumnExtensionValues<typeof acmeOrganizationColumns> to wywnioskowany typ wiersza
({ erpCode: string | null; creditTier: number; onboardedVia: string | null }), a
columnExtensionSchema / columnExtensionPatchSchema to odpowiadające mu schematy Zod.
Każda metoda akcesora jest uzależniona od obecności twojego modułu: gdy jest wyłączony, każde
wywołanie rzuca ModuleDisabledError, a kolumny zachowują wartości.
Akcesor nie sprawdza uprawnień. W organizations, która jest tabelą globalną, load, get
i set sięgają każdej organizacji po identyfikatorze: nie ma filtra dzierżawy, który by je
zawężał, ani sprawdzenia zasięgu wywołującego. Sprawdź uprawnienia we własnej trasie albo
poleceniu, zanim go wywołasz — tak jak robią to odczyty gospodarza w panelu administracyjnym,
które dołączają wartości rozszerzeń wyłącznie do rekordów, do których już sprawdziły dostęp.
Uzupełnianie z własnej migracji
Generowany krok wykonuje się na początku bloku migracji twojego modułu, więc twoje własne migracje wykonują się po nim i mogą uzupełnić twoje kolumny — i tylko twoje kolumny:
export class Migration20261201T090000AcmeErpBackfillCreditTier extends Migration {
override async up(): Promise<void> {
this.addSql(`update "organizations" set "x_acme_erp_credit_tier" = 1 where "vat_status" = 'valid'`);
}
}
Odczyt na ekranach panelu administracyjnego
Przy adminReads: true (domyślnie false) odczyty szczegółów i listy organizacji w panelu
administracyjnym przyjmują ?extensions=acme_erp i dołączają wartości do każdego rekordu:
GET /api/v1/admin/organizations/<id>?extensions=acme_erp
→ { "data": { …, "extensions": { "acme_erp": { "erpCode": "ERP-42", "creditTier": 0, "onboardedVia": null } } } }
Lista pięćdziesięciu organizacji kosztuje jedno dodatkowe zapytanie na każdy wskazany moduł, a nie
jedno na wiersz. Moduł wyłączony, niezainstalowany albo nieudostępniający gospodarza po prostu nie
występuje w extensions i nie powoduje błędu; bez parametru odpowiedź się nie zmienia. Miejscem
na ich pokazanie jest strefa twojego pakietu na ekranie szczegółów organizacji — nie ma nowego
miejsca w interfejsie.
Migracja, aktualizacja i weryfikacja
Platforma zamienia twoje deklaracje w jeden generowany krok migracji,
Migration10000101T000000AcmeErpSchemaExtensions<hash12>, który oczekuje na wykonanie dokładnie
wtedy, gdy deklaracje się zmieniają. Krok uzgadnia je z rejestrem — dodaje brakujące elementy,
przejmuje pasującą kolumnę, która już istnieje, ponownie dołącza osieroconą o niezmienionej
specyfikacji i odrzuca wszystko, co nieaddytywne. migrate up i install cyklu życia sprawdzają
każdą zadeklarowaną kolumnę i indeks wewnątrz transakcji migracji, więc przebieg, który którąś
utraci, jest wycofywany, a backend odmawia startu przy rozjeździe, podając moduł, kolumnę, tabelę i
ostatnią wykonaną migrację właściciela tabeli.
Rdzeń dotrzymuje swojej strony umowy w CI: każda migracja rdzenia jest wykonywana po kolei na świeżej bazie danych z przykładowymi kolumnami rozszerzeń w każdej otwartej rozszerzalnej tabeli, a migracja, która którąś utraci, przerywa build.
Uwaga dla operatora. Dodanie kolumny dopuszczającej null albo ze stałą wartością domyślną
zmienia w PostgreSQL wyłącznie katalog. Budowa indeksu blokuje tabelę na czas budowy, w trakcie
migrate; przy dużych tabelach zaplanuj to odpowiednio.
Odinstalowanie i usunięcie
W katalogu głównym instancji:
pnpm run module:uninstall acme_erp --hard # kolumny zostają, rejestr: orphaned
Wypisywanie i usuwanie elementów to module:schema-extensions, w tym samym katalogu głównym
instancji:
pnpm run module:schema-extensions list # każdy element i jego status
pnpm run module:schema-extensions drop acme_erp # wypisuje plan
pnpm run module:schema-extensions drop acme_erp --confirm # usuwa, jeden wpis audytu
pnpm run module:schema-extensions drop acme_erp --key erpCode --confirm # tylko elementy jednego klucza
list --json i list --module <id> zawężają listę. W klonie repozytorium Endora Commerce to samo
polecenie ma postać pnpm --filter backend run module:schema-extensions ….
Odinstalowanie twojego modułu zachowuje jego kolumny wraz z wartościami; usuwa je wyłącznie jawne,
audytowane drop … --confirm, i to tylko dla elementów osieroconych i już niedeklarowanych.
Pakiet usunięty bez module:uninstall --hard — skasowany z zależności instancji — jest
obsługiwany przy następnym migrate: jego wiersze w rejestrze są oznaczane jako osierocone (a jego
generowany krok znika z historii migracji), więc drop … --confirm może po nim posprzątać. Ten
migrate niczego nie usuwa, a jeśli ten sam pakiet wróci, jego kolumny zostaną ponownie dołączone.
Start backendu nigdy nie zmienia rejestru; jedynie ostrzega o osieroconych kolumnach.
Odinstalowanie gospodarza, gdy twój moduł jest zainstalowany, jest odrzucane z
dependents-block.
Czego migracja pakietu robić nie może
Deklaracja to jedyna droga do tabeli rdzenia. Każda migracja dostarczana przez zainstalowany
pakiet wykonuje się wewnątrz strażnika obcego schematu platformy, który odrzuca — i wycofuje
przebieg migrate — każdą instrukcję zapisującą tabelę, której właścicielem nie jest twój moduł:
alter table "organizations", indeks na niej, insert do orders, politykę na niej. Strażnik
czyta każdą drogę zapisu, jaką ma migracja: to, co przekazuje do addSql i execute, bloki
do $$ … $$, ciała tworzonych przez nią funkcji, ciągi wykonywane przez execute w PL/pgSQL oraz
getEntityManager() — jego flush, skróty insert*, upsert*, native* i execute, buildery
zapytań, połączenie i rozwidlenia. execute w PL/pgSQL na obliczanym ciągu (format(…), zmienna)
i surowe getKnex() menedżera encji nie dają się przypisać tabeli i są odrzucane.
create table if not exists na tabeli mapowanej przez encję innego modułu nie tworzy niczego, co
wolno ci potem zmieniać, a żadna twoja migracja nie może usunąć, wyczyścić (truncate) ani
alter … drop tabeli mapowanej przez encję innego modułu — ani w up(), ani w down(),
niezależnie od tego, co sama utworzyła — więc twardo odinstalowany pakiet nigdy nie zabierze ze
sobą tabeli innego modułu. Jedynym wyjątkiem jest down(), którego cel nie może przetrwać twojego
modułu: jego właściciel zależy od twojego modułu (więc jest usuwany wcześniej) albo oba moduły są
niewyłączalne.
Tabela jest twoja, gdy mapuje ją jedna z twoich encji albo tworzy ją jedna z twoich migracji i nie
mapuje jej encja żadnego innego modułu. Strażnik działa w trybie odmowy domyślnej: tabela,
której nie da się przypisać twojemu modułowi, jest odrzucana, a nie dopuszczana — mapuj więc swoje
tabele encjami i twórz każdą używaną tabelę we własnych migracjach. Dozwolone są własne tabele, tabele platformy i uzupełnianie własnych kolumn
x_<moduleId>_* w zadeklarowanym gospodarzu; reguły są na stronie Migracje, w
sekcji Strażnik obcego schematu.
Aby przed aktualizacją sprawdzić, czego wydanie by odmówiło, w katalogu głównym instancji:
pnpm run module:schema-extensions audit-packages
Polecenie czyta migracje wszystkich zainstalowanych pakietów, nie wykonując żadnej z nich, wypisuje każdą instrukcję, której strażnik by odmówił, i kończy się kodem 65, gdy taka istnieje.
Pakowanie
Pakietów lokalnych dla instancji jeszcze nie ma: zbuduj moduł, wykonaj pnpm pack i zainstaluj
archiwum w instancji, tak jak każdy inny pakiet modułu.