Database: Migrations
- Introduction
- Generating Migrations
- Migration Structure
- Running Migrations
- Tables
- Columns
- Indexes
- Events
Introduction
마이그레이션은 데이터베이스의 버전 관리를 가능하게 해주며, 팀원들이 애플리케이션의 데이터베이스 스키마 정의를 명확히 공유하도록 도와줍니다. 만약 여러분이 소스 컨트롤에서 변경 사항을 받은 동료에게 "데이터베이스에 컬럼을 직접 추가해 주세요"라고 안내했던 경험이 있다면, 바로 그 문제를 마이그레이션으로 해결할 수 있습니다.
Laravel의 Schema facade는 Laravel에서 지원하는 모든 데이터베이스 시스템에서 데이터베이스 테이블을 생성하고 조작할 수 있도록 데이터베이스에 독립적인 기능을 제공합니다. 일반적으로 마이그레이션은 이 파사드를 활용하여 데이터베이스의 테이블과 컬럼을 생성 및 수정합니다.
Generating Migrations
make:migration Artisan command를 사용해 데이터베이스 마이그레이션 파일을 생성할 수 있습니다. 새로 생성된 마이그레이션 파일은 database/migrations 디렉터리에 저장됩니다. 각 마이그레이션 파일명에는 타임스탬프가 포함되어 있어 Laravel이 마이그레이션 실행 순서를 결정할 수 있습니다.
php artisan make:migration create_flights_table
Laravel은 마이그레이션 파일의 이름을 참고하여 어떤 테이블을 대상으로 하는지, 그리고 새 테이블을 생성하는지 여부를 추론하려 시도합니다. Laravel이 마이그레이션 이름에서 테이블명을 알아낼 수 있다면, 생성된 마이그레이션 파일의 내용을 미리 채워줍니다. 만약 자동으로 추론되지 않는다면, 마이그레이션 파일에서 직접 테이블명을 지정하시면 됩니다.
생성된 마이그레이션의 저장 경로를 따로 지정하고 싶다면, make:migration 명령어 실행 시 --path 옵션을 사용할 수 있습니다. 입력하는 경로는 애플리케이션의 최상위 경로에서 상대경로로 작성해야 합니다.
마이그레이션 스텁(stub)은 stub publishing을 통해 커스터마이징할 수 있습니다.
Squashing Migrations
애플리케이션을 개발하다 보면 시간이 지나면서 마이그레이션 파일이 점점 많아질 수 있습니다. 이로 인해 database/migrations 디렉터리에 수백 개의 마이그레이션이 쌓여 비대해질 수 있습니다. 이런 경우, 마이그레이션을 하나의 SQL 파일로 "스쿼시(squash)"하여 관리할 수 있습니다. 시작하려면 schema:dump 명령어를 실행하세요.
php artisan schema:dump
# Dump the current database schema and prune all existing migrations...
php artisan schema:dump --prune
이 명령어를 실행하면, Laravel은 애플리케이션의 database/schema 디렉터리에 "스키마" 파일을 생성합니다. 파일명은 데이터베이스 연결 이름과 일치합니다. 이제 데이터베이스에 마이그레이션을 적용하려고 할 때, 아직 마이그레이션이 실행된 적이 없다면 Laravel은 우선 해당 데이터베이스 연결의 스키마 파일에 들어 있는 SQL을 실행합니다. 스키마 파일 실행 후, 스키마 덤프에 포함되지 않은 나머지 마이그레이션만 추가로 실행합니다.
애플리케이션 테스트에서 로컬 개발 시 사용하는 데이터베이스와 다른 데이터베이스 연결을 사용한다면, 반드시 그 데이터베이스 연결을 사용해서도 스키마 파일을 덤프하세요. 이렇게 하면 테스트 실행 시 데이터베이스를 올바르게 구축할 수 있습니다. 일반적으로 로컬 개발용 연결의 스키마를 먼저 덤프한 후, 테스트용 연결에 대해 덤프를 진행합니다.
php artisan schema:dump
php artisan schema:dump --database=testing --prune
생성한 데이터베이스 스키마 파일은 소스 컨트롤에 커밋하는 것이 좋습니다. 이렇게 하면 팀의 신규 개발자가 빠르게 초기 데이터베이스 구조를 생성할 수 있습니다.
마이그레이션 스쿼싱 기능은 MySQL, PostgreSQL, SQLite 데이터베이스에서만 지원되며, 데이터베이스의 커맨드라인 클라이언트를 활용합니다.
Migration Structure
마이그레이션 클래스는 up과 down 두 개의 메서드를 가집니다. up 메서드는 데이터베이스에 새로운 테이블, 컬럼, 인덱스를 추가하는 작업에 사용하며, down 메서드는 up에서 수행한 작업을 되돌릴 수 있도록 반대로 동작해야 합니다.
이 두 메서드 내부에서는 Laravel 스키마 빌더(schema builder)를 사용하여 직관적으로 테이블을 생성하거나 수정할 수 있습니다. Schema 빌더에서 사용할 수 있는 모든 메서드에 대해 더 자세한 정보가 필요하다면 check out its documentation를 참고하시기 바랍니다. 예를 들어, 아래 마이그레이션에서는 flights 테이블을 생성합니다.
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
/**
* Run the migrations.
*/
public function up(): void
{
Schema::create('flights', function (Blueprint $table) {
$table->id();
$table->string('name');
$table->string('airline');
$table->timestamps();
});
}
/**
* Reverse the migrations.
*/
public function down(): void
{
Schema::drop('flights');
}
};
Setting the Migration Connection
마이그레이션이 애플리케이션의 기본 데이터베이스 연결이 아닌 다른 데이터베이스 연결을 사용해야 한다면, 마이그레이션 클래스의 $connection 속성을 설정해 주세요.
/**
* The database connection that should be used by the migration.
*
* @var string
*/
protected $connection = 'pgsql';
/**
* Run the migrations.
*/
public function up(): void
{
// ...
}
Running Migrations
아직 실행하지 않은 모든 마이그레이션을 한 번에 적용하려면, migrate Artisan 명령어를 실행하세요.
php artisan migrate
지금까지 어떤 마이그레이션이 실행되었는지 확인하려면, migrate:status Artisan 명령어를 사용할 수 있습니다.
php artisan migrate:status
마이그레이션이 실제로 실행되지는 않고, 어떤 SQL 문이 실행될지 미리 보고 싶다면, migrate 명령에 --pretend 플래그를 추가할 수 있습니다.
php artisan migrate --pretend
Isolating Migration Execution
여러 서버에 애플리케이션을 배포하고, 배포 과정 중에 마이그레이션을 실행하는 경우, 두 서버가 동시에 같은 데이터베이스에 마이그레이션을 적용하는 상황을 피하고 싶을 수 있습니다. 이러한 경우, migrate 명령 실행 시 isolated 옵션을 사용할 수 있습니다.
isolated 옵션을 지정하면, Laravel이 마이그레이션을 실행하기 전에 애플리케이션의 캐시 드라이버를 활용하여 원자적(atomic) 락을 획득합니다. 락이 유지되는 동안 migrate 명령을 실행하려는 다른 모든 시도는 실제로 수행되지 않으며, 단지 성공적인 종료 코드와 함께 종료됩니다.
php artisan migrate --isolated
이 기능을 사용하려면, 애플리케이션의 기본 캐시 드라이버로
memcached,redis,dynamodb,database,file또는array중 하나가 설정되어 있어야 합니다. 또한 모든 서버는 동일한 중앙 캐시 서버와 통신해야 합니다.
Forcing Migrations to Run in Production
일부 마이그레이션 작업은 파괴적일 수 있어 데이터 손실이 발생할 수도 있습니다. 이를 방지하기 위해, 프로덕션 데이터베이스에서 해당 명령을 실행하려고 하면 추가로 실행 여부를 확인하는 프롬프트가 표시됩니다. 프롬프트 없이 즉시 실행하려면 --force 플래그를 사용하세요.
php artisan migrate --force
Rolling Back Migrations
가장 최근에 실행된 마이그레이션 작업을 되돌리려면 rollback Artisan 명령어를 사용할 수 있습니다. 이 명령은 하나의 "배치(batch)"에 해당하는(여러 마이그레이션 파일 포함 가능) 모든 작업을 롤백합니다.
php artisan migrate:rollback
rollback 명령어에 step 옵션을 추가하면 최근 N개의 마이그레이션만 롤백할 수도 있습니다. 예를 들어, 다음 명령은 마지막 5개의 마이그레이션만 롤백합니다.
php artisan migrate:rollback --step=5
특정 "배치(batch)"의 마이그레이션만 롤백하려면, rollback 명령어에 batch 옵션을 추가하면 됩니다. 이때 batch 값은 애플리케이션의 migrations 데이터베이스 테이블 내 배치 값에 해당합니다. 예를 들어, 다음 명령은 3번 배치에 속한 모든 마이그레이션만 롤백합니다.
php artisan migrate:rollback --batch=3
실제로 롤백을 실행하지 않고, 어떤 SQL 문이 실행될지 미리 확인하고 싶다면 migrate:rollback 명령에 --pretend 플래그를 추가하세요.
php artisan migrate:rollback --pretend
migrate:reset 명령어를 사용하면, 애플리케이션의 모든 마이그레이션을 한 번에 롤백할 수 있습니다.
php artisan migrate:reset
Roll Back and Migrate Using a Single Command
migrate:refresh 명령어는 모든 마이그레이션을 롤백한 후 migrate 명령을 다시 실행합니다. 즉, 전체 데이터베이스를 한 번에 새로 만드는 효과가 있습니다.
php artisan migrate:refresh
# Refresh the database and run all database seeds...
php artisan migrate:refresh --seed
refresh 명령어에 step 옵션을 지정하면, 최근 N개의 마이그레이션만 롤백하고 다시 마이그레이션할 수 있습니다. 예를 들어, 아래 명령은 최근 5개의 마이그레이션만 롤백 후 재실행합니다.
php artisan migrate:refresh --step=5
Drop All Tables and Migrate
migrate:fresh 명령어는 데이터베이스의 모든 테이블을 삭제한 뒤, migrate 명령을 실행합니다.
php artisan migrate:fresh
php artisan migrate:fresh --seed
기본적으로 migrate:fresh 명령어는 기본 데이터베이스 연결의 테이블만 삭제합니다. 하지만 --database 옵션을 사용해 특정 데이터베이스 연결을 지정할 수도 있습니다. 연결명은 애플리케이션의 database configuration file에 정의된 값과 일치해야 합니다.
php artisan migrate:fresh --database=admin
migrate:fresh명령어는 테이블의 접두사와 상관없이 데이터베이스의 모든 테이블을 삭제합니다. 다른 애플리케이션과 공유하는 데이터베이스에서 사용할 때는 각별히 주의하세요.
Tables
Creating Tables
새로운 데이터베이스 테이블을 생성하려면, 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();
});
테이블 생성시, 스키마 빌더의 column methods를 자유롭게 사용하여 테이블의 컬럼을 정의할 수 있습니다.
Determining Table / Column Existence
hasTable과 hasColumn 메서드를 사용하면, 테이블이나 컬럼이 존재하는지 확인할 수 있습니다.
if (Schema::hasTable('users')) {
// The "users" table exists...
}
if (Schema::hasColumn('users', 'email')) {
// The "users" table exists and has an "email" column...
}
Database Connection and Table Options
기본 데이터베이스 연결이 아닌 다른 연결에 대해 스키마 작업을 수행하고 싶다면, 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)"로 만들고 싶다면, temporary 메서드를 사용하세요. 임시 테이블은 현재 연결의 데이터베이스 세션에서만 보이고, 연결을 종료하면 자동으로 삭제됩니다.
Schema::create('calculations', function (Blueprint $table) {
$table->temporary();
// ...
});
데이터베이스 테이블에 "코멘트(comment)"를 추가하고 싶다면, 테이블 인스턴스의 comment 메서드를 호출할 수 있습니다. 테이블 코멘트는 현재 MySQL과 Postgres에서만 지원됩니다.
Schema::create('calculations', function (Blueprint $table) {
$table->comment('Business calculations');
// ...
});
Updating Tables
기존 테이블을 수정하려면 Schema 파사드의 table 메서드를 사용하세요. create 메서드와 마찬가지로, table 메서드는 첫 번째 인자로 테이블명, 두 번째 인자로 컬럼이나 인덱스를 추가할 수 있는 Blueprint 인스턴스를 전달하는 클로저를 받습니다.
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('users', function (Blueprint $table) {
$table->integer('votes');
});
Renaming / Dropping Tables
기존 데이터베이스 테이블의 이름을 바꾸려면 rename 메서드를 사용하세요.
use Illuminate\Support\Facades\Schema;
Schema::rename($from, $to);
기존 테이블을 삭제하려면 drop 또는 dropIfExists 메서드를 사용할 수 있습니다.
Schema::drop('users');
Schema::dropIfExists('users');
Renaming Tables With Foreign Keys
테이블 이름을 변경하기 전에는, 해당 테이블의 외래 키 제약(foreign key constraint)에 대해 마이그레이션 파일 내에서 반드시 명시적으로 이름을 지정했는지 확인해야 합니다. 그렇지 않으면, 외래 키 제약 이름이 이전 테이블명을 참조할 수 있습니다.
Columns
Creating Columns
기존 테이블을 수정하려면 Schema 파사드의 table 메서드를 사용하세요. create 메서드와 마찬가지로, table 메서드는 첫 번째 인자로 테이블명, 두 번째 인자로 컬럼을 추가할 수 있는 Illuminate\Database\Schema\Blueprint 인스턴스를 전달하는 클로저를 받습니다.
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('users', function (Blueprint $table) {
$table->integer('votes');
});
Available Column Types
스키마 빌더(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()
bigIncrements 메서드는 자동 증가하는 UNSIGNED BIGINT (기본 키) 컬럼을 생성합니다.
$table->bigIncrements('id');
bigInteger()
bigInteger 메서드는 BIGINT 타입의 컬럼을 생성합니다.
$table->bigInteger('votes');
binary()
binary 메서드는 BLOB 타입의 컬럼을 생성합니다.
$table->binary('photo');
boolean()
boolean 메서드는 BOOLEAN 타입의 컬럼을 생성합니다.
$table->boolean('confirmed');
char()
char 메서드는 지정한 길이만큼의 CHAR 타입 컬럼을 생성합니다.
$table->char('name', 100);
dateTimeTz()
dateTimeTz 메서드는(정밀도 지정 가능) 타임존이 포함된 DATETIME 타입의 컬럼을 생성합니다.
$table->dateTimeTz('created_at', $precision = 0);
dateTime()
dateTime 메서드는(정밀도 지정 가능) DATETIME 타입의 컬럼을 생성합니다.
$table->dateTime('created_at', $precision = 0);
date()
date 메서드는 DATE 타입의 컬럼을 생성합니다.
$table->date('created_at');
decimal()
decimal 메서드는 지정한 전체 자리수(precision)와 소수점 이하 자리수(scale)를 갖는 DECIMAL 타입의 컬럼을 생성합니다.
$table->decimal('amount', $precision = 8, $scale = 2);
double()
double 메서드는 지정한 precision(전체 자릿수)과 scale(소수 자릿수)로 DOUBLE과 동등한 컬럼을 생성합니다.
$table->double('amount', 8, 2);
enum()
enum 메서드는 주어진 값 목록으로 제한되는 ENUM과 동등한 컬럼을 생성합니다.
$table->enum('difficulty', ['easy', 'hard']);
float()
float 메서드는 지정한 precision(전체 자릿수)과 scale(소수 자릿수)로 FLOAT과 동등한 컬럼을 생성합니다.
$table->float('amount', 8, 2);
foreignId()
foreignId 메서드는 UNSIGNED BIGINT와 동등한 컬럼을 생성합니다.
$table->foreignId('user_id');
foreignIdFor()
foreignIdFor 메서드는 주어진 모델 클래스에 대해 {column}_id와 동등한 컬럼을 추가합니다. 컬럼 타입은 모델의 키 타입에 따라 UNSIGNED BIGINT, CHAR(36), 또는 CHAR(26)이 됩니다.
$table->foreignIdFor(User::class);
foreignUlid()
foreignUlid 메서드는 ULID와 동등한 컬럼을 생성합니다.
$table->foreignUlid('user_id');
foreignUuid()
foreignUuid 메서드는 UUID와 동등한 컬럼을 생성합니다.
$table->foreignUuid('user_id');
geometryCollection()
geometryCollection 메서드는 GEOMETRYCOLLECTION과 동등한 컬럼을 생성합니다.
$table->geometryCollection('positions');
geometry()
geometry 메서드는 GEOMETRY와 동등한 컬럼을 생성합니다.
$table->geometry('positions');
id()
id 메서드는 bigIncrements 메서드의 별칭입니다. 기본적으로 id 컬럼을 생성하지만, 다른 컬럼명을 지정하고 싶다면 이름을 직접 전달할 수 있습니다.
$table->id();
increments()
increments 메서드는 자동 증가하는 UNSIGNED INTEGER 타입의 컬럼을 기본키로 생성합니다.
$table->increments('id');
integer()
integer 메서드는 INTEGER와 동등한 컬럼을 생성합니다.
$table->integer('votes');
ipAddress()
ipAddress 메서드는 VARCHAR와 동등한 컬럼을 생성합니다.
$table->ipAddress('visitor');
Postgres를 사용할 때는 INET 컬럼이 생성됩니다.
json()
json 메서드는 JSON과 동등한 컬럼을 생성합니다.
$table->json('options');
jsonb()
jsonb 메서드는 JSONB와 동등한 컬럼을 생성합니다.
$table->jsonb('options');
lineString()
lineString 메서드는 LINESTRING과 동등한 컬럼을 생성합니다.
$table->lineString('positions');
longText()
longText 메서드는 LONGTEXT와 동등한 컬럼을 생성합니다.
$table->longText('description');
macAddress()
macAddress 메서드는 MAC 주소를 저장하기 위한 컬럼을 생성합니다. PostgreSQL 등 일부 데이터베이스는 이 용도를 위한 전용 컬럼 타입을 제공합니다. 그 외에는 문자열 타입 컬럼이 사용됩니다.
$table->macAddress('device');
mediumIncrements()
mediumIncrements 메서드는 자동 증가하는 UNSIGNED MEDIUMINT 타입의 컬럼을 기본키로 생성합니다.
$table->mediumIncrements('id');
mediumInteger()
mediumInteger 메서드는 MEDIUMINT와 동등한 컬럼을 생성합니다.
$table->mediumInteger('votes');
mediumText()
mediumText 메서드는 MEDIUMTEXT와 동등한 컬럼을 생성합니다.
$table->mediumText('description');
morphs()
morphs 메서드는 {column}_id와 동등한 컬럼과 {column}_type VARCHAR와 동등한 컬럼을 함께 추가하는 편의 메서드입니다. {column}_id 타입은 모델의 키 타입에 따라 UNSIGNED BIGINT, CHAR(36), 또는 CHAR(26)이 됩니다.
이 메서드는 다형성 Eloquent relationship를 만들 때 필요한 컬럼을 정의하기 위해 사용됩니다. 아래 예시에서는 taggable_id와 taggable_type 컬럼이 생성됩니다.
$table->morphs('taggable');
multiLineString()
multiLineString 메서드는 MULTILINESTRING과 동등한 컬럼을 생성합니다.
$table->multiLineString('positions');
multiPoint()
multiPoint 메서드는 MULTIPOINT와 동등한 컬럼을 생성합니다.
$table->multiPoint('positions');
multiPolygon()
multiPolygon 메서드는 MULTIPOLYGON과 동등한 컬럼을 생성합니다.
$table->multiPolygon('positions');
nullableTimestamps()
nullableTimestamps 메서드는 timestamps 메서드의 별칭입니다.
$table->nullableTimestamps(0);
nullableMorphs()
이 메서드는 morphs 메서드와 유사하지만, 생성되는 컬럼들이 "nullable"로 지정된다는 점이 다릅니다.
$table->nullableMorphs('taggable');
nullableUlidMorphs()
이 메서드는 ulidMorphs 메서드와 유사하지만, 생성되는 컬럼들이 "nullable"로 지정됩니다.
$table->nullableUlidMorphs('taggable');
nullableUuidMorphs()
이 메서드는 uuidMorphs 메서드와 유사하지만, 생성되는 컬럼들이 "nullable"로 지정됩니다.
$table->nullableUuidMorphs('taggable');
point()
point 메서드는 POINT와 동등한 컬럼을 생성합니다.
$table->point('position');
polygon()
polygon 메서드는 POLYGON과 동등한 컬럼을 생성합니다.
$table->polygon('position');
rememberToken()
rememberToken 메서드는 현 사용자의 "remember me" authentication token을 저장하기 위한 nullable, VARCHAR(100)과 동등한 컬럼을 생성합니다.
$table->rememberToken();
set()
set 메서드는 전달된 값 목록으로 제한되는 SET과 동등한 컬럼을 생성합니다.
$table->set('flavors', ['strawberry', 'vanilla']);
smallIncrements()
smallIncrements 메서드는 자동 증가하는 UNSIGNED SMALLINT 타입의 컬럼을 기본키로 생성합니다.
$table->smallIncrements('id');
smallInteger()
smallInteger 메서드는 SMALLINT와 동등한 컬럼을 생성합니다.
$table->smallInteger('votes');
softDeletesTz()
softDeletesTz 메서드는 nullable한 deleted_at TIMESTAMP(타임존 포함)과 동등한 컬럼을 precision(총 자릿수) 옵션과 함께 추가합니다. 이 컬럼은 Eloquent의 "soft delete" 기능에 필요한 deleted_at 타임스탬프 값을 저장하는 용도입니다.
$table->softDeletesTz($column = 'deleted_at', $precision = 0);
softDeletes()
softDeletes 메서드는 nullable한 deleted_at TIMESTAMP와 동등한 컬럼을 precision(총 자릿수) 옵션과 함께 추가합니다. 이 컬럼은 Eloquent의 "soft delete" 기능에 필요한 deleted_at 타임스탬프 값을 저장하는 용도입니다.
$table->softDeletes($column = 'deleted_at', $precision = 0);
string()
string 메서드는 지정한 길이의 VARCHAR와 동등한 컬럼을 생성합니다.
$table->string('name', 100);
text()
text 메서드는 TEXT와 동등한 컬럼을 생성합니다.
$table->text('description');
timeTz()
timeTz 메서드는 지정된 precision(총 자릿수) 옵션으로 타임존이 포함된 TIME과 동등한 컬럼을 생성합니다.
$table->timeTz('sunrise', $precision = 0);
time()
time 메서드는 지정된 precision(총 자릿수) 옵션으로 TIME과 동등한 컬럼을 생성합니다.
$table->time('sunrise', $precision = 0);
timestampTz()
timestampTz 메서드는 지정된 precision(총 자릿수) 옵션으로 타임존이 포함된 TIMESTAMP와 동등한 컬럼을 생성합니다.
$table->timestampTz('added_at', $precision = 0);
timestamp()
timestamp 메서드는 지정된 precision(총 자릿수) 옵션으로 TIMESTAMP와 동등한 컬럼을 생성합니다.
$table->timestamp('added_at', $precision = 0);
timestampsTz()
timestampsTz 메서드는 지정된 precision(총 자릿수) 옵션으로 created_at과 updated_at 타임존이 있는 TIMESTAMP와 동등한 컬럼을 생성합니다.
$table->timestampsTz($precision = 0);
timestamps()
timestamps 메서드는 지정된 precision(총 자릿수) 옵션으로 created_at과 updated_at TIMESTAMP와 동등한 컬럼을 생성합니다.
$table->timestamps($precision = 0);
tinyIncrements()
tinyIncrements 메서드는 자동 증가하는 UNSIGNED TINYINT 타입의 컬럼을 기본키로 생성합니다.
$table->tinyIncrements('id');
tinyInteger()
tinyInteger 메서드는 TINYINT와 동등한 컬럼을 생성합니다.
$table->tinyInteger('votes');
tinyText()
tinyText 메서드는 TINYTEXT와 동등한 컬럼을 생성합니다.
$table->tinyText('notes');
unsignedBigInteger()
unsignedBigInteger 메서드는 UNSIGNED BIGINT와 동등한 컬럼을 생성합니다.
$table->unsignedBigInteger('votes');
unsignedDecimal()
unsignedDecimal 메서드는 지정된 precision(총 자릿수) 및 scale(소수 자릿수)로 UNSIGNED DECIMAL과 동등한 컬럼을 생성합니다.
$table->unsignedDecimal('amount', $precision = 8, $scale = 2);
unsignedInteger()
unsignedInteger 메서드는 UNSIGNED INTEGER와 동등한 컬럼을 생성합니다.
$table->unsignedInteger('votes');
unsignedMediumInteger()
unsignedMediumInteger 메서드는 UNSIGNED MEDIUMINT와 동등한 컬럼을 생성합니다.
$table->unsignedMediumInteger('votes');
unsignedSmallInteger()
unsignedSmallInteger 메서드는 UNSIGNED SMALLINT와 동등한 컬럼을 생성합니다.
$table->unsignedSmallInteger('votes');
unsignedTinyInteger()
unsignedTinyInteger 메서드는 UNSIGNED TINYINT와 동등한 컬럼을 생성합니다.
$table->unsignedTinyInteger('votes');
ulidMorphs()
ulidMorphs 메서드는 {column}_id CHAR(26)과 동등한 컬럼과 {column}_type VARCHAR와 동등한 컬럼을 한 번에 추가하는 편의 메서드입니다.
이 메서드는 ULID 식별자를 사용하는 다형성 Eloquent relationship에 필요한 컬럼을 정의할 때 사용됩니다. 아래 예시에서는 taggable_id와 taggable_type 컬럼이 생성됩니다.
$table->ulidMorphs('taggable');
uuidMorphs()
uuidMorphs 메서드는 {column}_id CHAR(36)과 동등한 컬럼과 {column}_type VARCHAR와 동등한 컬럼을 한 번에 추가하는 편의 메서드입니다.
이 메서드는 UUID 식별자를 사용하는 다형성 Eloquent relationship에 필요한 컬럼을 정의할 때 사용됩니다. 아래 예시에서는 taggable_id와 taggable_type 컬럼이 생성됩니다.
$table->uuidMorphs('taggable');
ulid()
ulid 메서드는 ULID와 동등한 컬럼을 생성합니다.
$table->ulid('id');
uuid()
uuid 메서드는 UUID와 동등한 컬럼을 생성합니다.
$table->uuid('id');
year()
year 메서드는 YEAR와 동등한 컬럼을 생성합니다.
$table->year('birth_year');
Column Modifiers
위에서 소개한 컬럼 타입 외에도, 데이터베이스 테이블에 컬럼을 추가할 때 사용할 수 있는 다양한 "컬럼 수정자(modifiers)"가 있습니다. 예를 들어 컬럼을 "nullable"로 지정하고 싶을 때는 nullable 메서드를 사용할 수 있습니다.
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('users', function (Blueprint $table) {
$table->string('email')->nullable();
});
아래 표는 사용 가능한 모든 컬럼 수정자를 정리한 것입니다. 이 목록에는 index modifiers는 포함되어 있지 않습니다.
| Modifier | 설명 |
|---|---|
->after('column') | 지정한 컬럼 바로 "뒤"에 해당 컬럼을 배치합니다 (MySQL). |
->autoIncrement() | INTEGER 컬럼을 auto-increment(기본키)로 설정합니다. |
->charset('utf8mb4') | 컬럼의 문자셋(charset)을 지정합니다 (MySQL). |
->collation('utf8mb4_unicode_ci') | 컬럼의 정렬 방식(collation)을 지정합니다 (MySQL/PostgreSQL/SQL Server). |
->comment('my comment') | 컬럼에 주석(comment)을 추가합니다 (MySQL/PostgreSQL). |
->default($value) | 컬럼의 "기본값(default)"을 지정합니다. |
->first() | 해당 컬럼을 테이블의 "가장 처음"에 배치합니다 (MySQL). |
->from($integer) | 자동증가 필드의 시작값을 지정합니다 (MySQL / PostgreSQL). |
->invisible() | SELECT * 쿼리에서 해당 컬럼을 "감춤" 상태로 지정합니다 (MySQL). |
->nullable($value = true) | 이 컬럼에 NULL 값을 저장할 수 있도록 허용합니다. |
->storedAs($expression) | 저장된 계산 컬럼(stored generated column)을 생성합니다 (MySQL / PostgreSQL). |
->unsigned() | INTEGER 컬럼을 UNSIGNED로 지정합니다 (MySQL). |
->useCurrent() | TIMESTAMP 컬럼의 기본값을 CURRENT_TIMESTAMP로 지정합니다. |
->useCurrentOnUpdate() | 레코드가 수정될 때 TIMESTAMP 컬럼에 CURRENT_TIMESTAMP가 자동으로 반영되도록 합니다 (MySQL). |
->virtualAs($expression) | 가상 생성 컬럼(virtual generated column)을 생성합니다 (MySQL / PostgreSQL / SQLite). |
->generatedAs($expression) | 지정한 시퀀스 옵션으로 아이덴티티 컬럼(identity column)을 생성합니다 (PostgreSQL). |
->always() | 아이덴티티 컬럼에서 입력값보다 시퀀스 값을 우선적으로 지정합니다 (PostgreSQL). |
->isGeometry() | 공간 컬럼의 타입을 기본값인 geography 대신 geometry로 지정합니다 (PostgreSQL). |
Default Expressions
default 수정자는 값 또는 Illuminate\Database\Query\Expression 인스턴스를 인수로 받을 수 있습니다. Expression 인스턴스를 사용하면 Laravel이 해당 값을 따옴표로 감싸지 않으므로 데이터베이스 고유의 함수를 사용할 수 있습니다. 이 기능이 특히 유용한 대표적인 사례는 JSON 컬럼에 기본값을 할당해야 할 때입니다.
<?php
use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Query\Expression;
use Illuminate\Database\Migrations\Migration;
return new class extends Migration
{
/**
* Run the migrations.
*/
public function up(): void
{
Schema::create('flights', function (Blueprint $table) {
$table->id();
$table->json('movies')->default(new Expression('(JSON_ARRAY())'));
$table->timestamps();
});
}
};
기본 표현식의 지원 여부는 데이터베이스 드라이버, 데이터베이스 버전, 컬럼 타입에 따라 다릅니다. 반드시 본인의 데이터베이스 공식 문서를 확인하십시오.
Column Order
MySQL 데이터베이스를 사용할 때, after 메서드를 활용하여 기존 컬럼 뒤에 새로운 컬럼들을 추가할 수 있습니다.
$table->after('password', function (Blueprint $table) {
$table->string('address_line1');
$table->string('address_line2');
$table->string('city');
});
Modifying Columns
change 메서드를 사용하면 기존 컬럼의 타입과 속성을 자유롭게 수정할 수 있습니다. 예를 들어, string 타입 컬럼의 길이를 늘리고 싶을 때 사용할 수 있습니다. change 메서드의 실제 사용 예를 보겠습니다. 아래처럼 name 컬럼의 길이를 25에서 50으로 늘리려면, 해당 컬럼의 새로운 속성을 정의한 후 change 메서드를 호출하면 됩니다.
Schema::table('users', function (Blueprint $table) {
$table->string('name', 50)->change();
});
컬럼을 수정할 때는, 해당 컬럼에 계속 적용하고 싶은 모든 수정자(modifier)를 명시적으로 포함해야 합니다. 명시하지 않은 속성은 삭제됩니다. 예를 들어, unsigned, default, comment 속성을 그대로 유지하려면 수정 시 각각의 수정자를 반드시 다시 선언해 주어야 합니다.
Schema::table('users', function (Blueprint $table) {
$table->integer('votes')->unsigned()->default(1)->comment('my comment')->change();
});
Modifying Columns on SQLite
애플리케이션에서 SQLite 데이터베이스를 사용 중이라면, 컬럼을 수정하기 전에 Composer 패키지 매니저로 doctrine/dbal 패키지를 반드시 설치해야 합니다. Doctrine DBAL 라이브러리를 사용하면 컬럼의 현재 상태를 파악하고, 원하는 변경 작업에 필요한 SQL 쿼리를 생성하게 됩니다.
composer require doctrine/dbal
만약 timestamp 메서드로 생성한 컬럼을 수정하려는 경우, 애플리케이션의 config/database.php 설정 파일에 아래와 같은 구성을 추가해야 합니다.
use Illuminate\Database\DBAL\TimestampType;
'dbal' => [
'types' => [
'timestamp' => TimestampType::class,
],
],
doctrine/dbal패키지를 사용할 때 아래 컬럼 타입만 수정이 가능합니다:bigInteger,binary,boolean,char,date,dateTime,dateTimeTz,decimal,double,integer,json,longText,mediumText,smallInteger,string,text,time,tinyText,unsignedBigInteger,unsignedInteger,unsignedSmallInteger,ulid,uuid.
Renaming Columns
컬럼의 이름을 변경하려면, 스키마 빌더가 제공하는 renameColumn 메서드를 사용하면 됩니다.
Schema::table('users', function (Blueprint $table) {
$table->renameColumn('from', 'to');
});
Renaming Columns on Legacy Databases
아래에 안내된 버전보다 낮은 데이터베이스 버전을 사용 중이라면, 컬럼 이름을 변경하기 전에 Composer 패키지 매니저를 통해 doctrine/dbal 라이브러리를 설치해야 합니다.
- MySQL <
8.0.3 - MariaDB <
10.5.2 - SQLite <
3.25.0
Dropping Columns
컬럼을 삭제하려면, 스키마 빌더에서 dropColumn 메서드를 사용할 수 있습니다.
Schema::table('users', function (Blueprint $table) {
$table->dropColumn('votes');
});
여러 개의 컬럼을 한 번에 삭제하려면, 컬럼명 배열을 dropColumn 메서드에 전달하면 됩니다.
Schema::table('users', function (Blueprint $table) {
$table->dropColumn(['votes', 'avatar', 'location']);
});
Dropping Columns on Legacy Databases
SQLite가 3.35.0 미만 버전이라면, dropColumn 메서드를 사용하기 전에 Composer로 doctrine/dbal 패키지를 설치해야 합니다. 이 패키지를 사용할 때 단일 마이그레이션 내에서 여러 컬럼을 동시에 삭제하거나 수정하는 작업은 지원되지 않습니다.
Available Command Aliases
Laravel은 자주 사용되는 컬럼을 삭제하기 위한 여러 편리한 메서드를 제공합니다. 아래 표에서 각 명령어의 기능을 확인할 수 있습니다.
| Command | Description |
|---|---|
$table->dropMorphs('morphable'); | morphable_id와 morphable_type 컬럼을 삭제합니다. |
$table->dropRememberToken(); | remember_token 컬럼을 삭제합니다. |
$table->dropSoftDeletes(); | deleted_at 컬럼을 삭제합니다. |
$table->dropSoftDeletesTz(); | dropSoftDeletes() 메서드의 별칭입니다. |
$table->dropTimestamps(); | created_at, updated_at 컬럼을 삭제합니다. |
$table->dropTimestampsTz(); | dropTimestamps() 메서드의 별칭입니다. |
Indexes
Creating Indexes
Laravel의 스키마 빌더는 여러 종류의 인덱스를 지원합니다. 아래 예제에서는 email 컬럼을 새로 추가하고 해당 컬럼 값이 유일해야 함을 명시합니다. 이때 unique 메서드를 컬럼 정의 뒤에 체이닝하면 인덱스가 생성됩니다.
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('users', function (Blueprint $table) {
$table->string('email')->unique();
});
또는, 컬럼을 정의한 이후에 인덱스를 별도로 생성할 수도 있습니다. 이 경우, 스키마 블루프린트에서 unique 메서드를 호출하면 됩니다. 이 메서드는 유니크 인덱스를 적용할 컬럼명을 인수로 받습니다.
$table->unique('email');
인덱스 메서드에 컬럼명 배열을 넘기면 복합(또는 조합) 인덱스도 생성할 수 있습니다.
$table->index(['account_id', 'created_at']);
인덱스를 생성할 때 Laravel이 기본적으로 테이블명, 컬럼명, 인덱스 타입을 조합해 인덱스명을 자동 생성하지만, 두 번째 인수로 직접 인덱스명을 지정할 수도 있습니다.
$table->unique('email', 'unique_email');
Available Index Types
Laravel의 스키마 빌더 블루프린트 클래스는 Laravel에서 지원하는 모든 인덱스 타입을 메서드로 제공합니다. 각 인덱스 메서드는 옵션으로 인덱스명을 두 번째 인수로 받을 수 있습니다. 인덱스명을 생략하면, 테이블명과 컬럼명(들), 인덱스 타입을 조합해 인덱스명이 자동으로 생성됩니다. 아래 표에서 주요 인덱스 메서드를 확인할 수 있습니다.
| Command | Description |
|---|---|
$table->primary('id'); | 기본키를 추가합니다. |
$table->primary(['id', 'parent_id']); | 복합 기본키를 추가합니다. |
$table->unique('email'); | 유니크 인덱스를 추가합니다. |
$table->index('state'); | 일반 인덱스를 추가합니다. |
$table->fullText('body'); | 전문(full text) 인덱스를 추가합니다 (MySQL/PostgreSQL). |
$table->fullText('body')->language('english'); | 지정한 언어의 전문 인덱스를 추가합니다 (PostgreSQL). |
$table->spatialIndex('location'); | 공간 인덱스를 추가합니다 (SQLite 제외). |
Index Lengths and MySQL / MariaDB
Laravel은 기본적으로 utf8mb4 문자 집합을 사용합니다. MySQL이 5.7.7 미만 버전이거나 MariaDB가 10.2.2 미만 버전이라면, 마이그레이션에서 생성되는 문자열의 기본 길이를 수동으로 설정해야 인덱스를 정상적으로 생성할 수 있습니다. 이때 App\Providers\AppServiceProvider의 boot 메서드에서 Schema::defaultStringLength 메서드를 호출해 기본 문자열 길이를 설정할 수 있습니다.
use Illuminate\Support\Facades\Schema;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Schema::defaultStringLength(191);
}
또는 데이터베이스의 innodb_large_prefix 옵션을 활성화해서 사용할 수도 있습니다. 해당 옵션 활성화 방법은 데이터베이스 공식 문서를 참조하시기 바랍니다.
Renaming Indexes
인덱스의 이름을 변경하려면, 스키마 빌더 블루프린트가 제공하는 renameIndex 메서드를 사용합니다. 첫 번째 인수로 현재 인덱스명, 두 번째 인수로 원하는 새 인덱스명을 전달하세요.
$table->renameIndex('from', 'to')
애플리케이션이 SQLite 데이터베이스를 사용 중인 경우,
renameIndex메서드를 사용하기 전에 반드시 Composer로doctrine/dbal패키지를 설치해야 합니다.
Dropping Indexes
인덱스를 삭제하려면, 반드시 인덱스명을 인수로 지정해야 합니다. Laravel은 테이블명, 인덱싱되는 컬럼명, 인덱스 타입을 조합해 인덱스명을 자동으로 부여합니다. 아래는 사용 예시입니다.
| Command | Description |
|---|---|
$table->dropPrimary('users_id_primary'); | "users" 테이블의 기본키를 삭제합니다. |
$table->dropUnique('users_email_unique'); | "users" 테이블의 유니크 인덱스를 삭제합니다. |
$table->dropIndex('geo_state_index'); | "geo" 테이블의 일반 인덱스를 삭제합니다. |
$table->dropFullText('posts_body_fulltext'); | "posts" 테이블의 전문 인덱스를 삭제합니다. |
$table->dropSpatialIndex('geo_location_spatialindex'); | "geo" 테이블의 공간 인덱스를 삭제합니다 (SQLite 제외). |
여러 컬럼명을 배열로 전달해 인덱스를 삭제하면, 지정한 테이블명, 컬럼명, 인덱스 타입 기준으로 Laravel이 인덱스명을 자동으로 생성해 삭제하게 됩니다.
Schema::table('geo', function (Blueprint $table) {
$table->dropIndex(['state']); // Drops index 'geo_state_index'
});
Foreign Key Constraints
Laravel은 데이터베이스 수준의 참조 무결성을 강제하는 외래 키(foreign key) 제약조건 기능도 제공합니다. 예를 들어, posts 테이블의 user_id 컬럼이 users 테이블의 id 컬럼을 참조하도록 정의할 수 있습니다.
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('posts', function (Blueprint $table) {
$table->unsignedBigInteger('user_id');
$table->foreign('user_id')->references('id')->on('users');
});
이 문법은 다소 장황하므로, Laravel은 규약(convention)을 활용해 더 간결하게 작성할 수 있는 별도의 메서드도 제공합니다. foreignId 메서드를 사용하면 위 코드를 아래처럼 줄일 수 있습니다.
Schema::table('posts', function (Blueprint $table) {
$table->foreignId('user_id')->constrained();
});
foreignId 메서드는 UNSIGNED BIGINT에 해당하는 컬럼을 생성하며, constrained 메서드는 규약에 따라 참조할 테이블과 컬럼을 자동으로 결정합니다. 만약 테이블명이 Laravel의 규약과 다르다면, constrained 메서드에 직접 테이블명을 지정할 수도 있습니다. 또한, 생성되는 인덱스명도 인수로 명시적으로 지정할 수 있습니다.
Schema::table('posts', function (Blueprint $table) {
$table->foreignId('user_id')->constrained(
table: 'users', indexName: 'posts_user_id'
);
});
제약조건의 "on delete", "on update" 행동도 아래처럼 지정할 수 있습니다.
$table->foreignId('user_id')
->constrained()
->onUpdate('cascade')
->onDelete('cascade');
이러한 동작을 위한 더욱 명시적이고 직관적인 문법도 제공됩니다.
| Method | Description |
|---|---|
$table->cascadeOnUpdate(); | 업데이트시 연결된 데이터도 함께 수정됩니다. |
$table->restrictOnUpdate(); | 업데이트가 제한됩니다. |
$table->noActionOnUpdate(); | 업데이트 시 별도의 동작이 없습니다. |
$table->cascadeOnDelete(); | 삭제 시 연결된 데이터도 함께 삭제됩니다. |
$table->restrictOnDelete(); | 삭제가 제한됩니다. |
$table->nullOnDelete(); | 삭제 시 외래 키 값을 null로 설정합니다. |
추가적인 column modifiers는 반드시 constrained 메서드 전에 호출해야 합니다.
$table->foreignId('user_id')
->nullable()
->constrained();
Dropping Foreign Keys
외래 키를 삭제하려면, 삭제할 외래 키 제약조건명을 dropForeign 메서드에 인수로 전달하면 됩니다. 외래 키 제약조건명은 인덱스와 같은 규칙을 따르며, 테이블명-컬럼명_조합 뒤에 "_foreign"이 붙는 형태입니다.
$table->dropForeign('posts_user_id_foreign');
또 다른 방법으로, 외래 키를 보유한 컬럼명을 배열로 dropForeign 메서드에 전달해도 됩니다. 이 배열은 Laravel의 제약조건 명명 규칙에 따라 외래 키 제약조건명으로 변환됩니다.
$table->dropForeign(['user_id']);
Toggling Foreign Key Constraints
마이그레이션 내에서 아래 메서드로 외래 키 제약조건을 전역적으로 활성화하거나 비활성화할 수 있습니다.
Schema::enableForeignKeyConstraints();
Schema::disableForeignKeyConstraints();
Schema::withoutForeignKeyConstraints(function () {
// Constraints disabled within this closure...
});
SQLite는 기본적으로 외래 키 제약조건이 비활성화되어 있습니다. SQLite를 사용할 경우, 마이그레이션에서 외래 키를 생성하기 전에 enable foreign key support이 데이터베이스 설정에 활성화되어 있는지 반드시 확인하십시오. 또한, SQLite는 테이블 생성 시에만 외래 키 제약조건을 지원하며, not when tables are altered.
Events
각 마이그레이션 작업은 event를 자동으로 디스패치(dispatch)합니다. 아래 이벤트들은 모두 기본 클래스인 Illuminate\Database\Events\MigrationEvent를 상속합니다.
| Class | Description |
|---|---|
Illuminate\Database\Events\MigrationsStarted | 여러 개의 마이그레이션 실행이 곧 시작됨을 알립니다. |
Illuminate\Database\Events\MigrationsEnded | 여러 개의 마이그레이션 실행이 모두 완료되었음을 알립니다. |
Illuminate\Database\Events\MigrationStarted | 단일 마이그레이션 시작 직전 이벤트입니다. |
Illuminate\Database\Events\MigrationEnded | 단일 마이그레이션 종료 후 이벤트입니다. |
Illuminate\Database\Events\SchemaDumped | 데이터베이스 스키마 덤프가 완료되었음을 알립니다. |
Illuminate\Database\Events\SchemaLoaded | 기존 데이터베이스 스키마 덤프가 로드되었음을 알립니다. |