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

번역일: 2026년 6월 25일

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

소개

마이그레이션은 데이터베이스를 위한 버전 관리 시스템입니다. 팀원들이 애플리케이션의 데이터베이스 스키마를 정의하고 공유할 수 있게 해줍니다. 소스 컨트롤에서 변경 사항을 받아온 뒤 "팀원에게 직접 컬럼을 추가해 달라고 부탁해야 했던" 경험이 있다면, 마이그레이션이 바로 그 문제를 해결하기 위한 도구입니다.

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

마이그레이션 생성

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

php artisan make:migration create_flights_table

Laravel은 마이그레이션 이름에서 테이블 이름과 새 테이블 생성 여부를 자동으로 추론하려고 시도합니다. 이름에서 테이블 이름을 파악할 수 있다면, 해당 테이블명이 미리 채워진 마이그레이션 파일을 생성합니다. 그렇지 않은 경우에는 파일을 직접 수정하여 테이블명을 지정하면 됩니다.

생성될 마이그레이션 파일의 경로를 직접 지정하고 싶다면 --path 옵션을 사용하세요. 경로는 애플리케이션의 루트 경로를 기준으로 한 상대 경로여야 합니다.

NOTE

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

마이그레이션 스쿼싱

애플리케이션을 개발하다 보면 마이그레이션 파일이 수백 개까지 쌓일 수 있습니다. database/migrations 디렉터리가 지나치게 비대해진다면, 마이그레이션 전체를 하나의 SQL 파일로 합치는 "스쿼싱"을 활용할 수 있습니다. schema:dump 명령어를 실행하면 됩니다.

php artisan schema:dump# 현재 데이터베이스 스키마를 덤프하고, 기존 마이그레이션 파일을 모두 삭제...php artisan schema:dump --prune

이 명령어를 실행하면 Laravel은 database/schema 디렉터리에 스키마 파일을 생성합니다. 파일 이름은 사용한 데이터베이스 커넥션 이름을 따릅니다. 이후 마이그레이션을 실행할 때 아직 실행된 마이그레이션이 없으면, Laravel은 먼저 해당 스키마 파일의 SQL을 실행합니다. 스키마 파일 실행 후에는 스키마 덤프에 포함되지 않은 나머지 마이그레이션만 추가로 실행합니다.

테스트 환경에서 로컬 개발과 다른 데이터베이스 커넥션을 사용한다면, 해당 커넥션으로도 스키마 파일을 덤프해두어야 테스트 시 데이터베이스를 올바르게 구성할 수 있습니다. 일반적으로 다음 순서로 진행합니다.

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

데이터베이스 스키마 파일은 소스 컨트롤에 커밋해두는 것이 좋습니다. 새로운 팀원이 합류했을 때 초기 데이터베이스 구조를 빠르게 구성할 수 있습니다.

WARNING

마이그레이션 스쿼싱은 MySQL, PostgreSQL, SQLite에서만 지원되며, 각 데이터베이스의 커맨드라인 클라이언트를 사용합니다.

마이그레이션 구조

마이그레이션 클래스는 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 { // ... }

마이그레이션 실행

아직 실행되지 않은 모든 마이그레이션을 실행하려면 migrate Artisan 명령어를 사용합니다.

php artisan migrate

지금까지 실행된 마이그레이션 목록을 확인하려면 migrate:status 명령어를 사용합니다.

php artisan migrate:status

실제로 실행하지 않고 마이그레이션이 실행할 SQL 구문을 미리 확인하고 싶다면 --pretend 플래그를 사용합니다.

php artisan migrate --pretend

마이그레이션 중복 실행 방지

여러 서버에 애플리케이션을 배포하면서 마이그레이션을 배포 프로세스의 일부로 실행하는 경우, 두 서버가 동시에 마이그레이션을 실행하는 상황을 피해야 할 수 있습니다. 이런 경우 isolated 옵션을 사용하세요.

isolated 옵션을 지정하면, Laravel은 마이그레이션 실행 전에 애플리케이션의 캐시 드라이버를 통해 원자적 락(atomic lock)을 획득합니다. 락이 걸려 있는 동안에는 다른 migrate 명령어 실행 시도가 실제로 실행되지 않으며, 명령어는 성공 상태 코드로 종료됩니다.

php artisan migrate --isolated

WARNING

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

프로덕션 환경에서 강제 실행

일부 마이그레이션은 데이터 손실을 유발할 수 있는 파괴적인 작업을 포함합니다. 프로덕션 데이터베이스에서 이런 명령어를 실수로 실행하지 않도록, 실행 전에 확인 메시지가 표시됩니다. 확인 없이 강제로 실행하려면 --force 플래그를 사용하세요.

php artisan migrate --force

마이그레이션 롤백

가장 최근에 실행된 마이그레이션 배치를 롤백하려면 migrate:rollback 명령어를 사용합니다. 하나의 배치에는 여러 마이그레이션 파일이 포함될 수 있습니다.

php artisan migrate:rollback

step 옵션으로 롤백할 마이그레이션 수를 제한할 수 있습니다. 예를 들어 아래 명령어는 마지막 5개의 마이그레이션을 롤백합니다.

php artisan migrate:rollback --step=5

batch 옵션으로 특정 배치 번호의 마이그레이션을 롤백할 수도 있습니다. batch 값은 애플리케이션의 migrations 테이블에 기록된 값에 해당합니다. 예를 들어 아래 명령어는 배치 3에 해당하는 마이그레이션을 모두 롤백합니다.

php artisan migrate:rollback --batch=3

실제로 롤백하지 않고 실행될 SQL 구문만 미리 확인하려면 --pretend 플래그를 사용합니다.

php artisan migrate:rollback --pretend

애플리케이션의 모든 마이그레이션을 롤백하려면 migrate:reset 명령어를 사용합니다.

php artisan migrate:reset

롤백과 마이그레이션을 한 번에 실행

migrate:refresh 명령어는 모든 마이그레이션을 롤백한 뒤 다시 migrate를 실행합니다. 데이터베이스 전체를 처음부터 다시 구성할 때 유용합니다.

php artisan migrate:refresh# 데이터베이스를 초기화하고 시더도 함께 실행...php artisan migrate:refresh --seed

step 옵션으로 최근 N개의 마이그레이션만 롤백하고 재실행할 수도 있습니다.

php artisan migrate:refresh --step=5

모든 테이블 삭제 후 마이그레이션

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

php artisan migrate:freshphp artisan migrate:fresh --seed

기본적으로 migrate:fresh는 기본 데이터베이스 커넥션의 테이블만 삭제합니다. --database 옵션으로 특정 커넥션을 지정할 수 있으며, 커넥션 이름은 database 설정 파일에 정의된 이름이어야 합니다.

php artisan migrate:fresh --database=admin

WARNING

migrate:fresh 명령어는 테이블 프리픽스 여부와 관계없이 데이터베이스의 모든 테이블을 삭제합니다. 여러 애플리케이션이 공유하는 데이터베이스에서 사용할 때는 각별히 주의하세요.

테이블

테이블 생성

새 데이터베이스 테이블을 생성하려면 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 메서드로 테이블이나 컬럼의 존재 여부를 확인할 수 있습니다.

if (Schema::hasTable('users')) { // "users" 테이블이 존재함... } if (Schema::hasColumn('users', 'email')) { // "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 메서드를 사용합니다. 테이블 코멘트는 현재 MySQL과 PostgreSQL에서만 지원됩니다.

Schema::create('calculations', function (Blueprint $table) { $table->comment('업무용 계산 테이블'); // ... });

테이블 수정

기존 테이블을 수정하려면 Schema 파사드의 table 메서드를 사용합니다. create 메서드와 마찬가지로, 테이블 이름과 Blueprint 인스턴스를 받는 클로저를 인수로 전달합니다.

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

테이블 이름 변경 / 삭제

기존 테이블의 이름을 변경하려면 rename 메서드를 사용합니다.

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

테이블을 삭제하려면 drop 또는 dropIfExists 메서드를 사용합니다.

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

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

테이블 이름을 변경하기 전에, 마이그레이션 파일에서 해당 테이블의 외래 키 제약 조건에 명시적인 이름이 부여되어 있는지 확인하세요. 이름을 직접 지정하지 않으면 Laravel이 규칙에 따라 자동으로 생성한 이름(기존 테이블명 기반)이 그대로 남아 참조 불일치가 발생할 수 있습니다.

컬럼

컬럼 생성

기존 테이블에 컬럼을 추가할 때도 Schema 파사드의 table 메서드를 사용합니다. 클로저 안에서 Illuminate\Database\Schema\Blueprint 인스턴스를 통해 컬럼을 추가합니다.

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

사용 가능한 컬럼 타입

스키마 빌더 Blueprint는 데이터베이스 테이블에 추가할 수 있는 다양한 컬럼 타입 메서드를 제공합니다.

bigIncrements bigInteger binary boolean char dateTimeTz dateTime date decimal double enum float foreignId foreignIdFor foreignUlid foreignUuid geometryCollection geometry id increments integer ipAddress json jsonb lineString longText macAddress mediumIncrements mediumInteger mediumText morphs multiLineString multiPoint multiPolygon nullableMorphs nullableTimestamps nullableUlidMorphs nullableUuidMorphs point polygon rememberToken set smallIncrements smallInteger softDeletesTz softDeletes string text timeTz time timestampTz timestamp timestampsTz timestamps tinyIncrements tinyInteger tinyText unsignedBigInteger unsignedDecimal unsignedInteger unsignedMediumInteger unsignedSmallInteger unsignedTinyInteger ulidMorphs uuidMorphs ulid uuid year

`bigIncrements()` {.collection-method .first-collection-method}

자동 증가하는 UNSIGNED BIGINT 컬럼(기본 키)을 생성합니다.

$table->bigIncrements('id');

`bigInteger()` {.collection-method}

BIGINT 컬럼을 생성합니다.

$table->bigInteger('votes');

`binary()` {.collection-method}

BLOB 컬럼을 생성합니다.

$table->binary('photo');

`boolean()` {.collection-method}

BOOLEAN 컬럼을 생성합니다.

$table->boolean('confirmed');

`char()` {.collection-method}

지정한 길이의 CHAR 컬럼을 생성합니다.

$table->char('name', 100);

`dateTimeTz()` {.collection-method}

선택적 정밀도(총 자릿수)를 가진 타임존 포함 DATETIME 컬럼을 생성합니다.

$table->dateTimeTz('created_at', $precision = 0);

`dateTime()` {.collection-method}

선택적 정밀도(총 자릿수)를 가진 DATETIME 컬럼을 생성합니다.

$table->dateTime('created_at', $precision = 0);

`date()` {.collection-method}

DATE 컬럼을 생성합니다.

$table->date('created_at');

`decimal()` {.collection-method}

지정한 정밀도(총 자릿수)와 소수 자릿수를 가진 DECIMAL 컬럼을 생성합니다.

$table->decimal('amount', $precision = 8, $scale = 2);

`double()` {.collection-method}

지정한 정밀도(총 자릿수)와 소수 자릿수를 가진 DOUBLE 컬럼을 생성합니다.

$table->double('amount', 8, 2);

`enum()` {.collection-method}

지정한 허용값을 가진 `ENUM

이 문서는 Laravel 공식 문서(MIT)를 한국 개발자를 위해 번역·재구성한 것입니다.

번역일: 2026년 6월 25일