본문으로 건너뛰기
가이드

필수 설치 콘텐츠

일반 Laravel 시더를 버전별로 등록하고 개발·설치·업데이트에서 실행합니다.

필수 설치 콘텐츠

일반 Laravel Seeder::run()과 $this->call()을 그대로 사용하고, 초기화기에 버전별 시더 목록만 연결합니다. id와 public_id는 모델의 자동 생성을 사용합니다. 고정 UUID를 직접 넣을 필요가 없습니다. 이 계약을 포함한 SDK와 대응 플랫폼·런타임·CLI가 필요합니다. 아직 해당 계약이 없는 SDK에서는 사용할 수 없습니다.

1. 시더 작성

아래는 이미 Category 모델과 테이블이 있는 앱의 src/Seeders/CategorySeeder.php입니다. 자신의 namespace와 필수 속성에 맞추세요. 시더는 배포에 포함되는 autoload 경로에 둡니다.

코드 예시
PHP
<?php
namespace Nexia\Apps\Acme\Workshop\Seeders;

use Illuminate\Database\Seeder;
use Nexia\Apps\Acme\Workshop\Models\Category;

final class CategorySeeder extends Seeder
{
    public function run(): void
    {
        Category::create(['name' => 'General']);
    }
}

2. 초기화기에 버전 연결

src/Contribution/WorkshopDefaults.php를 만듭니다. 처음에는 1 => [CategorySeeder::class]만 등록합니다. SettingsSeeder를 추가하면 같은 초기화기의 목록에 2 => [SettingsSeeder::class]를 추가합니다. 버전 1을 2로 바꾸거나 기존 목록을 덮어쓰지 않습니다. 같은 버전에 여러 시더를 순서대로 등록할 수 있습니다.

코드 예시
PHP
<?php
namespace Nexia\Apps\Acme\Workshop\Contribution;

use Nexia\AppRuntime\Contracts\VersionedTenantAppSeederContribution;
use Nexia\Apps\Acme\Workshop\Seeders\CategorySeeder;
use Nexia\Apps\Acme\Workshop\Seeders\SettingsSeeder;

final class WorkshopDefaults implements VersionedTenantAppSeederContribution
{
    public function appKey(): string { return 'workshop'; }

    public function versions(): array
    {
        return [
            1 => [CategorySeeder::class],
            2 => [SettingsSeeder::class],
        ];
    }
}

SettingsSeeder도 위와 같은 일반 Laravel 시더로 작성합니다. 이미 게시한 시더를 수정하여 다른 버전에 재사용하지 말고, 수정용 시더를 새 클래스로 만드세요.

Manifest가 src/Manifest.php에 있다면 contribution 경로는 아래와 같습니다. 생성된 Manifest에 이 경로가 이미 있으면 그대로 사용하고, 기존 다른 경로도 유지합니다. Composer의 앱 namespace는 src/에 연결되어 있어야 합니다. 한 앱에 이 초기화기는 하나만 둡니다.

코드 예시
PHP
public function contributionLocations(): array
{
    return [[
        'namespace' => 'Nexia\\Apps\\Acme\\Workshop\\Contribution',
        'directory' => __DIR__.'/Contribution',
    ]];
}

3. 개발 중 실행

앱 폴더에서 실행하면 그 앱만 대상으로 합니다. 프로젝트 루트에서는 --app workshop으로 대상을 명시하세요.

코드 예시
Shell
nexia db migrate
nexia db seed
nexia db status
상황결과와 다음 행동
1번만 등록한 첫 실행1번 실행·완료 기록
같은 명령 재실행완료한 1번 생략
2번 추가 후 실행1번 생략, 2번 실행
2번 실행 중 오류2번의 DB 변경과 완료 기록만 취소. 1번 데이터 유지
오류 수정 후 재실행개발자가 파일·예외를 확인하고 수정한 뒤 같은 nexia db seed 실행. 미완료 2번 재시도
이미 성공한 1번 코드를 수정개발은 차단하지 않으며, 변경된 1번을 다시 실행하지 않았다는 경고 표시
깨끗한 개발 DB에서 다시 시험nexia db fresh --seed로 선택한 앱의 개발 데이터와 이력을 지우고 현재 버전 전부 실행
nexia db refresh --seed모든 migration의 down·up 후 초기화 이력을 비우고 전체 시더 실행. migration이 되돌리기를 지원해야 함
nexia db rollbackmigration 되돌리기. 시더의 반대 작업을 자동 생성하거나 성공 이력을 취소하지 않음
nexia db seed demo이름이 demo인 선택형 fixture를 호출할 때마다 실행. 버전 시더 전체 재실행 명령이 아님
nexia db seed --class='…'선택한 일반 시더를 직접 실행. 버전 완료 이력을 사용하거나 갱신하지 않음

fresh는 해당 앱 개발 DB의 데이터를 삭제합니다. 보존할 데이터가 있으면 새 수정 버전을 추가하세요. 게시 이력 유무와 관계없이 개발 DB의 수정·재시도·fresh에는 관리자 승인이 필요하지 않습니다. 결과가 불명확한 전송 중단은 먼저 출력된 요청 ID로 결과를 조회하고, 같은 작업을 무작정 중복 실행하지 않습니다.

4. 게시와 운영 업데이트

신규 설치는 등록된 버전을 작은 번호부터 모두 실행합니다. 기존 설치 업데이트는 완료한 버전을 생략하고 추가 버전만 실행합니다. 앱 릴리스 번호만 올려서는 완료한 시더가 재실행되지 않습니다. 단순 게시와 실제 배포·설치는 별개이며, 운영 업데이트는 이전 코드와 데이터 보존 검증을 거칩니다.

게시된 버전의 등록·시더 파일을 수정하거나 삭제하면 게시 검증에서 차단합니다. Console과 CLI에서 해당 초기화 버전, 이전 앱 릴리스, 파일, 게시 당시 해시를 확인하고 그 릴리스의 Git 소스를 복원하세요. 수정 사항은 새 버전·새 시더에 넣습니다. 이전 해시가 없는 항목은 해시를 추측해서 표시하지 않습니다. 관리자는 게시·배포 절차에만 관여하며 개발 코드를 대신 고치거나 개발 DB 이력을 수동 변경할 필요가 없습니다.

검사는 등록 클래스와 정적으로 참조한 하위 Seeder, 앱 내부 부모·trait 파일을 비교합니다. 동적으로 계산한 클래스명, 임의의 모델·공용 helper 변경까지 추적하는 것은 아닙니다. 게시된 초기값의 동작을 바꿀 때는 새 시더 클래스로 명시적으로 등록하고 호환성을 시험하세요. 외부 API·이메일은 DB 롤백으로 취소되지 않으므로 시더에서 실행하지 않습니다. 고객이 바꾼 기존 데이터는 수정용 시더에서도 의도 없이 덮어쓰지 마세요.

기존 TenantAppInitializerContribution과 VersionedTenantAppInitializerContribution은 유지됩니다. 새 버전 목록 계약과 동시에 등록할 수 없습니다. 이미 이전 초기화기로 데이터가 들어간 DB를 자동 변환하지 않습니다. 기존 운영 앱은 이전 계약을 유지하고, 새 계약의 개발 시험에는 fresh를 사용하세요. 관리자 수동 DB 변경으로 전환하지 않습니다.

개발용 테스트 데이터 · 설치 콘텐츠 계약

원본 위치: docs/developers/content/ko/platform-extensions/required-installation-content.md