Laravel 데이터베이스: 마이그레이션

1 개요

Database: Migrations

데이터베이스: 마이그레이션

https://laravel.com/docs/11.x/migrations

2 소개

마이그레이션은 데이터베이스의 버전 관리와 같아서 팀이 애플리케이션의 데이터베이스 스키마 정의를 정의하고 공유할 수 있게 해줍니다. 만약 소스 컨트롤에서 변경사항을 가져온 후 동료에게 로컬 데이터베이스 스키마에 수동으로 컬럼을 추가하라고 한 적이 있다면, 이는 데이터베이스 마이그레이션이 해결하는 문제에 직면한 것입니다.

Laravel Schema 파사드는 Laravel에서 지원하는 모든 데이터베이스 시스템에 대해 데이터베이스 테이블을 생성하고 조작하는 데이터베이스 독립적 지원을 제공합니다. 일반적으로 마이그레이션은 이 파사드를 사용하여 데이터베이스 테이블과 컬럼을 생성하고 수정합니다.

3 마이그레이션 생성

make:migration Artisan 명령어를 사용하여 데이터베이스 마이그레이션을 생성할 수 있습니다. 새 마이그레이션은 database/migrations 디렉토리에 위치하게 됩니다. 각 마이그레이션 파일명에는 타임스탬프가 포함되어 있어 Laravel이 마이그레이션 순서를 결정할 수 있습니다:

php artisan make:migration create_flights_table

Laravel은 마이그레이션의 이름을 사용하여 테이블 이름과 마이그레이션이 새로운 테이블을 생성하는지 여부를 추측하려고 합니다. Laravel이 마이그레이션 이름에서 테이블 이름을 결정할 수 있는 경우, 지정된 테이블로 미리 채워진 마이그레이션 파일을 생성합니다. 그렇지 않은 경우, 마이그레이션 파일에서 테이블을 수동으로 지정할 수 있습니다.

생성된 마이그레이션에 대해 커스텀 경로를 지정하고 싶다면 make:migration 명령어를 실행할 때 --path 옵션을 사용할 수 있습니다. 지정된 경로는 애플리케이션의 기본 경로를 기준으로 상대 경로여야 합니다.

Note

마이그레이션 스텁은 스텁 퍼블리싱을 통해 커스터마이즈할 수 있습니다.

3.1 마이그레이션 스쿼싱

애플리케이션을 개발하면서 시간이 지남에 따라 더 많은 마이그레이션이 축적될 수 있습니다. 이는 database/migrations 디렉토리가 수백 개의 마이그레이션으로 인해 부피가 커지는 문제를 야기할 수 있습니다. 이러한 경우 마이그레이션을 단일 SQL 파일로 "압축(squash)"할 수 있습니다. 이를 시작하려면 다음 명령어를 실행하세요:

php artisan schema:dump

# 현재 데이터베이스 스키마를 덤프하고 기존의 모든 마이그레이션을 제거합니다...
php artisan schema:dump --prune

이 명령어를 실행하면, Laravel은 애플리케이션의 database/schema 디렉토리에 "스키마" 파일을 작성합니다. 스키마 파일의 이름은 데이터베이스 연결에 해당합니다. 이제 데이터베이스를 마이그레이션하려고 할 때 다른 마이그레이션이 실행되지 않은 경우 Laravel은 먼저 사용 중인 데이터베이스 연결의 스키마 파일에 있는 SQL 문을 실행합니다. 그런 다음 스키마 파일의 SQL 문을 실행한 후 남아있는 나머지 마이그레이션을 실행합니다.

애플리케이션의 테스트가 로컬 개발 중에 일반적으로 사용하는 것과 다른 데이터베이스 연결을 사용하는 경우, 테스트가 데이터베이스를 구축할 수 있도록 해당 데이터베이스 연결을 사용하여 스키마 파일을 덤프했는지 확인해야 합니다. 로컬 개발 중에 일반적으로 사용하는 데이터베이스 연결을 덤프한 후에 이 작업을 수행하는 것이 좋습니다:

php artisan schema:dump
php artisan schema:dump --database=testing --prune

다른 새로운 팀원들이 애플리케이션의 초기 데이터베이스 구조를 빠르게 생성할 수 있도록 데이터베이스 스키마 파일을 소스 컨트롤에 커밋해야 합니다.

Warning

마이그레이션 스쿼싱은 MySQL, PostgreSQL, SQLite 데이터베이스에서만 사용할 수 있으며, 데이터베이스의 명령줄 클라이언트를 활용합니다.

4 마이그레이션 구조

마이그레이션 클래스에는 두 가지 메소드 up과 down이 있습니다. up 메소드는 데이터베이스에 새 테이블, 컬럼, 인덱스를 추가하는 데 사용되며, down 메소드는 up 메소드에서 수행한 작업을 되돌리는 역할을 합니다.

이 두 메소드 내에서 Laravel 스키마 빌더를 사용하여 테이블을 표현적으로 생성하고 수정할 수 있습니다. Schema 빌더에서 사용할 수 있는 모든 메소드에 대해 자세히 알아보려면 해당 문서를 참조하세요. 예를 들어, 다음 마이그레이션은 flights 테이블을 생성합니다:

<?php
 
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
 
return new class extends Migration
{
    /**
     * 마이그레이션을 실행합니다.
     */
    public function up(): void
    {
        Schema::create('flights', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('airline');
            $table->timestamps();
        });
    }
 
    /**
     * 마이그레이션을 되돌립니다.
     */
    public function down(): void
    {
        Schema::drop('flights');
    }
};

마이그레이션 연결 설정

마이그레이션이 애플리케이션의 기본 데이터베이스 연결이 아닌 다른 데이터베이스 연결과 상호작용하는 경우, 마이그레이션의 $connection 속성을 설정해야 합니다:

/**
 * 마이그레이션에 사용될 데이터베이스 연결.
 *
 * @var string
 */
protected $connection = 'pgsql';
 
/**
 * 마이그레이션을 실행합니다.
 */
public function up(): void
{
    // ...
}

5 마이그레이션 실행

모든 미처리된 마이그레이션을 실행하려면, migrate Artisan 명령어를 실행하세요:

php artisan migrate

지금까지 실행된 마이그레이션을 확인하려면, migrate:status Artisan 명령어를 사용할 수 있습니다:

php artisan migrate:status

실제 마이그레이션을 실행하지 않고, 실행될 SQL 문을 보고 싶다면, migrate 명령어에 --pretend 플래그를 추가하십시오:

php artisan migrate --pretend

마이그레이션 실행 격리

여러 서버에 애플리케이션을 배포하고 배포 과정의 일부로 마이그레이션을 실행하는 경우, 두 서버가 동시에 데이터베이스를 마이그레이션하는 것을 피하고 싶을 것입니다. 이를 방지하기 위해, migrate 명령어를 호출할 때 isolated 옵션을 사용할 수 있습니다.

isolated 옵션이 제공되면, Laravel은 애플리케이션의 캐시 드라이버를 사용하여 원자적 잠금을 획득한 후 마이그레이션을 시도합니다. 이 잠금이 유지되는 동안 migrate 명령어를 실행하려는 다른 모든 시도는 실행되지 않습니다. 그러나 명령어는 여전히 성공적인 종료 상태 코드로 종료됩니다:

php artisan migrate --isolated

Warning

이 기능을 사용하려면, 애플리케이션의 기본 캐시 드라이버로 memcached, redis, dynamodb, database, file, 또는 array 캐시 드라이버를 사용해야 합니다. 또한, 모든 서버는 동일한 중앙 캐시 서버와 통신해야 합니다.

프로덕션 환경에서 마이그레이션 강제 실행

일부 마이그레이션 작업은 데이터 손실을 초래할 수 있는 파괴적 작업입니다. 이러한 명령어를 프로덕션 데이터베이스에서 실행하는 것을 방지하기 위해, 명령어가 실행되기 전에 확인을 요청받습니다. 프롬프트 없이 명령어를 강제로 실행하려면, --force 플래그를 사용하십시오:

php artisan migrate --force

5.1 마이그레이션 롤백

마지막 마이그레이션 작업을 되돌리려면 rollback Artisan 명령어를 사용할 수 있습니다. 이 명령어는 여러 개의 마이그레이션 파일을 포함할 수 있는 마지막 "배치"의 마이그레이션을 되돌립니다:

php artisan migrate:rollback

제한된 수의 마이그레이션을 되돌리려면 rollback 명령어에 step 옵션을 제공하면 됩니다. 예를 들어, 다음 명령어는 마지막 다섯 개의 마이그레이션을 되돌립니다:

php artisan migrate:rollback --step=5

특정 "배치"의 마이그레이션을 되돌리려면 rollback 명령어에 batch 옵션을 제공하면 됩니다. batch 옵션은 애플리케이션의 마이그레이션 데이터베이스 테이블 내의 배치 값에 해당합니다. 예를 들어, 다음 명령어는 배치 3의 모든 마이그레이션을 되돌립니다:

php artisan migrate:rollback --batch=3

마이그레이션이 실행될 SQL 문을 실제로 실행하지 않고 보고 싶다면, migrate:rollback 명령어에 --pretend 플래그를 제공하면 됩니다:

php artisan migrate:rollback --pretend

migrate:reset 명령어는 애플리케이션의 모든 마이그레이션을 되돌립니다:

php artisan migrate:reset

단일 명령어로 되돌리고 마이그레이션하기

migrate:refresh 명령어는 모든 마이그레이션을 되돌린 다음 migrate 명령어를 실행합니다. 이 명령어는 사실상 데이터베이스를 다시 생성합니다:

php artisan migrate:refresh

# 데이터베이스를 새로고침하고 모든 데이터베이스 시드를 실행합니다...
php artisan migrate:refresh --seed

제한된 수의 마이그레이션을 되돌리고 다시 마이그레이션하려면 refresh 명령어에 step 옵션을 제공하면 됩니다. 예를 들어, 다음 명령어는 마지막 다섯 개의 마이그레이션을 되돌리고 다시 마이그레이션합니다:

php artisan migrate:refresh --step=5

모든 테이블을 삭제하고 마이그레이션하기

migrate:fresh 명령어는 데이터베이스의 모든 테이블을 삭제한 다음 migrate 명령어를 실행합니다:

php artisan migrate:fresh

php artisan migrate:fresh --seed

기본적으로 migrate:fresh 명령어는 기본 데이터베이스 연결에서만 테이블을 삭제합니다. 그러나 --database 옵션을 사용하여 마이그레이션할 데이터베이스 연결을 지정할 수 있습니다. 데이터베이스 연결 이름은 애플리케이션의 데이터베이스 설정 파일에 정의된 연결과 일치해야 합니다:

php artisan migrate:fresh --database=admin

Warning

migrate:fresh 명령어는 접두어가 있는 테이블도 모두 삭제합니다. 이 명령어는 다른 애플리케이션과 공유하는 데이터베이스에서 개발할 때 주의해서 사용해야 합니다.

6 테이블

6.1 테이블 생성

새 데이터베이스 테이블을 생성하려면 Schema 파사드의 create 메소드를 사용합니다. create 메소드는 두 개의 인수를 받는데, 첫 번째 인수는 테이블의 이름이고, 두 번째 인수는 Blueprint 객체를 전달받는 클로저입니다. 이를 사용하여 새 테이블을 정의할 수 있습니다:

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
 
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email');
    $table->timestamps();
});

테이블을 생성할 때, 스키마 빌더의 다양한 컬럼 메소드들을 사용하여 테이블의 컬럼을 정의할 수 있습니다.

테이블/컬럼 존재 여부 확인

테이블, 컬럼 또는 인덱스의 존재 여부를 확인하려면 hasTable, hasColumn, hasIndex 메소드를 사용할 수 있습니다:

if (Schema::hasTable('users')) {
    // "users" 테이블이 있습니다...
}

if (Schema::hasColumn('users', 'email')) {
    // "users" 테이블이 있고 "email" 컬럼이 있습니다...
}

if (Schema::hasIndex('users', ['email'], 'unique')) {
    // "users" 테이블이 있고 "email" 컬럼에 고유 인덱스가 있습니다...
}

데이터베이스 연결 및 테이블 옵션

기본 데이터베이스 연결이 아닌 다른 데이터베이스 연결에서 스키마 작업을 수행하려면 connection 메소드를 사용하십시오:

Schema::connection('sqlite')->create('users', function (Blueprint $table) {
    $table->id();
});

또한, 테이블 생성 시 다음과 같은 속성과 메소드를 사용하여 다른 측면을 정의할 수 있습니다. MySQL을 사용할 때 테이블의 스토리지 엔진을 지정하려면 engine 속성을 사용할 수 있습니다:

Schema::create('users', function (Blueprint $table) {
    $table->engine('InnoDB');

    // ...
});

MySQL을 사용할 때 생성된 테이블의 문자 세트와 콜레이션을 지정하려면 charset과 collation 속성을 사용할 수 있습니다:

Schema::create('users', function (Blueprint $table) {
    $table->charset('utf8mb4');
    $table->collation('utf8mb4_unicode_ci');

    // ...
});

테이블이 "임시"임을 나타내려면 temporary 메소드를 사용할 수 있습니다. 임시 테이블은 현재 연결된 데이터베이스 세션에서만 보이며 연결이 종료되면 자동으로 삭제됩니다:

Schema::create('calculations', function (Blueprint $table) {
    $table->temporary();

    // ...
});

데이터베이스 테이블에 "주석(comment)"을 추가하려면 테이블 인스턴스에서 comment 메소드를 호출할 수 있습니다. 테이블 주석은 현재 MySQL과 PostgreSQL에서만 지원됩니다:

Schema::create('calculations', function (Blueprint $table) {
    $table->comment('Business calculations');

    // ...
});

6.2 테이블 업데이트

기존 테이블을 업데이트하려면 Schema 파사드에서 table 메소드를 사용할 수 있습니다. create 메소드와 마찬가지로 table 메소드는 테이블 이름과 Blueprint 인스턴스를 받는 클로저를 인수로 받습니다. 이 Blueprint 인스턴스를 사용하여 테이블에 컬럼 또는 인덱스를 추가할 수 있습니다:

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
 
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes');
});

이 예제에서는 'users' 테이블에 'votes'라는 정수형 컬럼을 추가하고 있습니다.

6.3 테이블 이름변경 / 삭제

기존 데이터베이스 테이블의 이름을 변경하려면 rename 메소드를 사용하세요:

use Illuminate\Support\Facades\Schema;
 
Schema::rename($from, $to);

기존 테이블을 삭제하려면 drop 또는 dropIfExists 메소드를 사용할 수 있습니다:

Schema::drop('users');
 
Schema::dropIfExists('users');

외래 키가 있는 테이블 이름변경

테이블 이름을 변경하기 전에, 마이그레이션 파일에서 외래 키 제약 조건에 명시적인 이름을 지정했는지 확인해야 합니다. 그렇지 않으면 Laravel이 관례에 따라 이름을 지정하여 외래 키 제약조건 이름이 기존 테이블 이름을 참조하게 됩니다.