로컬 MySQL DB를 Railway로 마이그레이션 하기

Frontend Dev Log

로컬 MySQL DB를 Railway로 마이그레이션 하기

jinuk-io 2025. 5. 31. 21:56

현재 스타트업을 준비하면서 mvp를 만들고 있는데, 시연을 위해 로컬에 만들어뒀던 mysql DB를 클라우드 환경으로 옮겨야 했고, Railway를 선택했다.

왜 이전해야 했냐면, 프론트엔드와 백엔드가 통합된 Next.js 구조에서 실제 배포된 환경에서도 DB에 접근이 가능해야 했기 때문이다.

mvp 개발 설계 당시 선택지로는 Neon, Supabase, Railway 등 여러 서비스가 있었지만, 나는 Railway를 선택했다.

[당시 사용 기술 및 환경]

Next.js (Typescript + Prisma)
MySQL 9.3.0 (Homebrew)
Railway (MySQL 호스팅)
DBeaver (GUI 확인 도구)
Terminal

왜 Railway를 선택했는가

일단 설정이 매우 빠르고 직관적이다. MySQL, PostgreSQL 등 다양한 데이터베이스를 몇 번의 클릭만으로 만들 수 있다는 점이 매무 마음에 들었다.

https://docs.railway.com/guides/build-a-database-service

추가로

Free Tier로 이용하기 충분했다. mvp 특성상 쓸데없는 지출은 삼가야 했고, Railway는 딱 적당할 정도의 프리티어가 제공되었다.
.env 환경변수 연동도 편하게 할 수 있다. Railway는 자동으로 MYSQLHOST, MYSQLPORT, MYSQLDATABASE 등 환경 변수를 제공해주기 때문에, Next.js Prisma ORM + env 파일을 통한 연동이 간편했다.
GUI도 깔끔해서 사용하기 쉬었다. 굉장히 쉬워서 GUI 진입 장벽이 낮다고 느꼈다.

이런 근거를 토대로, Railway를 선택하게 되었으며, 'Local에 만들어뒀던 mysql DB를 덤프시켜서 사용하자'라는 결정을 내렸다.

Step 1: mysql-client 설치 및 설정

이번 작업의 핵심은 mysqldump를 이용해 로컬 mysql 데이터를 .sql 파일로 export하고, Railway에 Import시키는 것이었다. 나는 맥북 터미널을 사용하고 있어. homebrew를 이용해 mysql-client를 별도로 설치했다.

brew install mysql-client

mysql-client는 왜 설치해야 하나?

mysql-client는 mysqldump, mysql 등 MySQL 서버와 통신하거나 백업/복원을 수행할 수 있는 도구 모음이다. 이번 작업에서 로컬 DB를 mysqldump하고, Railway에서 import(mysql)하기 위해 필수적인 과정이다.

macOS에는 기본적으로 포함되어 있지 않기 때문에, Homebrew로 따로 설치하고 PATH를 설정해줘야 한다. 서버 전체를 설치할 필요 없이, 클라이언트 도구만 설치하면 DB 백업 및 복원이 가능해 가볍고 편리하다.

설치 과정에서는 다음과 같은 메시지를 확인할 수 있다.

mysql-client는 keg-only이기 때문에 기본 PATH에 자동으로 연결되지 않는다. 따라서 아래처럼 직접 PATH를 설정해주어야 한다.

echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

이렇게 설정한 뒤, mysqldump 명령어가 정상 동작하는지 확인해준다.

mysqldump --version

정상적으로 설치되었다면 이렇게 버전 정보가 출력된다.

설치가 완료되면 다음 단계인 로컬 DB 덤프 파일 생성으로 넘어갈 수 있다.

Step 2: 로컬 DB 덤프 파일 생성

이제 mysqldump가 준비되었으니, 본격적으로 로컬 mysql 데이터베이스를 덤프시킬 차례다.

dump란 말 그대로, 현재 DB에 존재하는 모든 스키마(Table Structure), Index, 그리고 데이터 자체를 .sql 형식으로 내보내는 export 작업이다. 내가 덤프하려던 데이터베이스의 이름은 medi였고, 로컬 mysql 서버에는 루트 계정으로 접근할 수 있었다.

덤프 파일 생성 과정은 다음과 같다.

mysqldump -u root -p medi > dump.sql

-u root: mysql 사용자명 (보통은 root)
-p: 비밀번호를 입력하겠다는 의미. 비밀번호는 즉시 쓰지 않고, 프롬포트에서 입력 받는 게 좋다고 생각한다.
medi: 덤프하려는 로컬 DB 이름
> dump.sql: 덤프 결과를 dump.sql 파일로 저장

$ mysqldump -u root -p medi > dump.sql
Enter password: ********

비밀번호를 입력하면 입력한 내용은 표시되지 않지만 정삭 동작하게 된다. 입력 후 몇 초 후 dump.sql이라는 파일이 현재 디렉토리에 생성된다. 이미지에 Enter password: 에는 이미 비밀번호가 입력되어 있는 상태이다.

생성된 dump.sql은 어떤 파일일까?

-- MySQL dump 10.13  Distrib 9.3.0, for macos14.7 (arm64)
--
-- Host: localhost    Database: medi
-- ------------------------------------------------------
-- Server version       8.0.36

DROP TABLE IF EXISTS `UserAccount`;
CREATE TABLE `UserAccount` (
  `id` int NOT NULL AUTO_INCREMENT,
  `email` varchar(255) NOT NULL,
  ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

INSERT INTO `UserAccount` VALUES (1,'test@example.com',...);
...

이 파일은 그대로 Railway나 다른 mysql 서버에 복원시킬 수 있다. 쉽게 말해, mysql의 모든 구조와 데이터를 담고 있는 백업 파일이다.

여기서 알아둬야 할 점이 몇 개 있다.

덤프 전에 DB가 실행 중이어야 하고, 접근 가능한 상태여야 한다.
대용량 DB의 경우, --single-transaction 또는 --quick옵션을 추가하면 더 안정적으로 export 시킬 수 있다.
일부 테이블만 덤프하려면 mysqldump -u root -p medi table1 table2 > partial.sql처럼 테이블 이름을 명시하면 된다.

Step 3: Railway MySQL 프로젝트 생성 및 접속 정보 확인

이제 덤프한 .sql 파일을 업로드할 클라우드 DB 환경이 필요하다. 나는 이번 프로젝트에서 Railway를 사용했는데, 이유는 위에서 말했듯이 설정이 매우 간단하며 빠르고, 초기에는 무료로 사용할 수 있기에 적합하다.

먼저 Railway에 DB를 만들어둬야 하기에 접속하여 프로젝트를 생성한다.

간단하게 과정을 설명하면,

https://railway.app 접속
GitHub 계정으로 로그인
New Project 클릭
Provision MySQL을 선택

이 과정을 거치면 Railway는 자동으로 mysql 인스턴스를 생성하고, 관련 환경 변수를 자동으로 함께 세팅해준다.

이후 Railway에서 DB 접속 정보를 확인하면 된다.

이런 식으로 접속 정보를 확인할 수 있다.

이 정보는 Railway내 내가 만든 프로젝트(mysql) 내

Connect 탭: 각종 클라이언트 툴(MySQL CLI, DBeaver 등)에 연결하는 코드가 제공됨.
Variables 탭: .env 환경 변수 형식으로 바로 사용할 수 있도록 제공됨.

Railway는 .env 파일에서 바로 가져다 쓸 수 있도록 형식을 만들어두므로 쉽게 연결이 가능하다. Prisma ORM같은 툴을 사용하는 경우 특히 편리하다고 생각한다.

해당 정보는

외부 접속이 가능한 호스트를 제공하므로, 비밀번호는 꼭 비공개 환경변수로 관리해야 한다.
DB 관리 툴이나 CLI에 접속할 때는 꼭 port, host, user, database를 정확히 입력해야 하며
다른 로컬 mysql 포트와 충돌하지 않게 해야한다.

여기까지 했다면, 이제 로컬에서 만든 dump.sql파일을 Railway의 클라우드 MySQL 서버로 Import하면 된다.

Step 4: dump.sql 파일을 Railway DB에 업로드 하기

앞 단계까지 로컬 MySQL에서 .sql 덤프 파일을 만들고, Railway의 mysql 접속 정보를 확보했다. 이제 남은 건 간단하다. 터미널에서 dump 파일을 Railway DB에 업로드하면 끝이다.

mysql -h metro.proxy.rlwy.net \
  -P 28508 \
  -u root \
  -p \
  medi < dump.sql

명령어를 해설은 다음과 같다.

옵션	설명
-h	Railway에서 제공한 DB Host 정보
-P	Railway DB 포트 번호
-u	사용자 이름 (보통은 root임)
-p	비밀번호 입력 프롬포트 띄우기
medi	데이터베이스 이름 - Railway에서 생성한 이름과 일치해야 함
< dump.sql	아까 생성한 SQL 덤프 파일을 해당 DB에 업로드

$ mysql -h metro.proxy.rlwy.net -P 28508 -u root -p medi < dump.sql
Enter password: ********

터미널에서는 이렇게 실행하면 된다.

비밀번호는 Railway에서 발급받은 비밀번호를 입력하면 된다. 정상적으로 업로드되면 별다른 출력 없이 커서가 바로 내려오고, import는 완료된다.

이렇게 하면 덤프 끝이다.

Step 5: DBeaver로 정상 업로드 확인

CLI에서 조용히 끝났더라도 실제로 정상적으로 데이터가 올라갔는지 확인하는 게 중요하다. 나는 평소에 DBeaver를 사용하기 때문에, DBeaver로 확인을 하겠다.

이런 과정을 통해 연결할 수 있다.

DBeaver 실행 → Database > New Database Connection
MySQL 선택 → Next
그리고 아래 정보를 입력하면 된다.

Host	metro.proxy.rlwy.net
Port	28508
Database	medi
Username	root
Password	Railway에서 받은 비밀번호

이렇게 DBeaver랑 Railway DB를 연결한 후 테이블에 들어가면, 데이터까지 모두 정상적으로 들어가 있꼬, 구조와 컬럼 타입도 로컬에서 쓰던 것과 100% 일치하는 걸 확인할 수 있다.

끝내는 말

로컬 DB를 클라우드로 옮기는 작업을 진행해봤다. dump 과정 자체는 생각보다 복잡하지 않고, 명확한 구조로 정리를 해두면 프로젝트를 할 때 생각보다 요긴하게 쓰일 것이라고 생각한다.

특히 이번에 내가 사용한 Railway는 설정이 간단하고, 무료 플랜이 있어서 실습에도 좋을 것이라고 생각한다. 사이드 프로젝트를 할 때도 돈 안 드리고 써볼만 하다고 생각한다. 만약, 어떤 서비스를 만들어서 배포했는데 데이터베이스가 읽히지 않으면 DB를 로컬에 둬서 그럴 것이다. 그럴 때 이런 dump.sql파일을 만들어서 DB 마이그레이션을 해보면 좋을 것이다.

전체 과정 자동화용 Shell Script:

#!/bin/bash

# === 사용자 설정 ===
LOCAL_DB_NAME="medi"
RAILWAY_HOST="metro.proxy.rlwy.net"
RAILWAY_PORT=28508
RAILWAY_USER="root"
RAILWAY_DB_NAME="medi"

# === 덤프 생성 ===
echo "로컬 MySQL DB를 덤프합니다..."
mysqldump -u root -p $LOCAL_DB_NAME > dump.sql

# === Railway로 import ===
echo "☁️ Railway MySQL에 업로드합니다..."
mysql -h $RAILWAY_HOST -P $RAILWAY_PORT -u $RAILWAY_USER -p $RAILWAY_DB_NAME < dump.sql

echo "완료되었습니다. dump.sql이 Railway로 업로드되었습니다."

어디까지나 MacOS 기준으로 작성되었으며, mysql-client가 설치되어 있어야 한다. (Step 1참고)