Dolt 서버 연결

Beadbox는 실행 중인 Dolt SQL 서버에 연결하여, CLI에서 사용하는 동일한 beads 데이터베이스에 대해 다중 쓰기 접근과 팀 워크플로를 제공합니다.

Beadbox 0.9.12 이상 필요 버전은 설정 > 정보에서 확인하거나 아래에서 확인할 수 있습니다 /api/version.

사전 요구 사항

시작하기 전에 다음 세 가지가 실행 중이어야 합니다:

구성 요소	최소 버전	확인 방법
beads CLI (`bd`)	0.56.x+	`bd --version`
Dolt 서버	실행 중이며 연결을 수락하는 상태	`dolt sql-server` 프로젝트 디렉터리에서 실행
Beadbox	0.9.12+	설정 > 정보

Dolt 서버에는 beads_ 명명 규칙을 따르는 데이터베이스가 최소 하나 필요합니다. 이것은 Dolt 모드로 bd init을 실행할 때 beads가 생성하는 것입니다. Beadbox는 이 접두사를 사용하여 beads 데이터베이스를 발견하고 관련 없는 데이터베이스를 무시합니다.

빠른 시작 (로컬, 인증 없음)

가장 빠른 방법: 인증을 설정하지 않은 로컬 머신의 Dolt 서버에 연결합니다.

1. Dolt 서버 시작

cd ~/Projects/myproject
dolt sql-server

Dolt는 기본적으로 포트 3307에서 수신합니다.

2. Beadbox 열기

워크스페이스 선택 화면에서 서버로 추가를 클릭합니다 (첫 실행이라면 환영 화면의 고급 카드를 찾으세요).

3. 연결 정보 입력

호스트	`127.0.0.1` (자동 입력)
포트	`3307` (자동 입력)
사용자	`root` (자동 입력)
비밀번호	비워 둠
TLS	체크 해제

4. "데이터베이스 검색" 클릭

Beadbox가 서버에 연결하고 SHOW DATABASES를 실행하여 beads_* 패턴에 일치하는 모든 데이터베이스를 찾습니다.

5. 데이터베이스 선택

검색 화면에 서버에서 발견된 모든 beads 데이터베이스가 나열됩니다. 워크스페이스로 추가할 항목을 선택하세요. 각각에 로컬 디렉터리 경로가 할당됩니다.

6. "워크스페이스 추가" 클릭

Beadbox가 서버 연결 정보가 포함된 metadata.json을 가진 로컬 .beads/ 디렉터리를 생성하고, 워크스페이스를 등록하여 엽니다.

연결이 완료되었습니다. CLI에서 bd를 통해 변경한 사항이나 같은 Dolt 서버에 쓰기하는 다른 팀원의 변경 사항이 몇 초 내에 Beadbox에 표시됩니다 (서버 모드에서는 1초 간격으로 변경 사항을 폴링합니다).

인증으로 연결

Dolt 서버가 사용자 이름과 비밀번호를 요구하는 경우:

빠른 시작과 동일한 단계를 따르되, 사용자와 비밀번호 필드에 Dolt 서버 인증 정보를 입력하세요.
TLS가 필요한 경우 (원격 서버에서 흔함), TLS 사용 체크박스를 선택하세요.
데이터베이스 검색을 클릭하고 검색을 진행하세요.

비밀번호 처리 방식

비밀번호는 메모리에만 보관됩니다. Beadbox는 비밀번호를 디스크에 기록하지 않습니다.
Beadbox를 재시작하면 비밀번호가 사라집니다. 매번 재입력하지 않으려면 셸 프로필에 BEADS_DOLT_PASSWORD를 설정하세요 (비밀번호 유지 참조).
내부적으로 Beadbox는 서브프로세스 호출마다 BEADS_DOLT_PASSWORD 환경 변수를 통해 bd CLI에 비밀번호를 전달합니다.

Hosted Dolt 및 원격 서버

원격 머신, 클라우드 VM 또는 Hosted Dolt에서 실행 중인 Dolt 서버의 경우:

호스트: 서버의 호스트 이름 또는 IP를 입력합니다.
포트: 제공업체가 지정하는 포트를 사용합니다. Hosted Dolt는 일반적으로 3306을 사용합니다.
사용자/비밀번호: 제공업체에서 받은 인증 정보를 입력합니다.
TLS: "TLS 사용"을 체크하세요 (Hosted Dolt에서 필수, 모든 원격 연결에서 권장).
데이터베이스 검색을 클릭하고 평소대로 진행하세요.

비밀번호 유지

Beadbox는 비밀번호를 메모리에만 보관하므로 재시작 시 사라집니다. 인증이 필요한 서버(로컬 또는 원격)에서 재입력을 건너뛰려면 셸 프로필에 설정하세요:

export BEADS_DOLT_PASSWORD="your-password-here"

Beadbox는 모든 서버 모드 워크스페이스에서 이 설정을 자동으로 감지합니다. UI의 비밀번호 필드와 둘 다 설정된 경우 UI가 우선합니다.

작동 원리

서버 워크스페이스를 추가하면 Beadbox는 세 가지 작업을 수행합니다:

1. 연결 메타데이터 기록

로컬 프로젝트 디렉터리의 .beads/metadata.json에 서버 연결 정보를 기록합니다:

{
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 3307,
  "dolt_database": "beads_myproject",
  "dolt_server_user": "root",
  "database": "dolt"
}

TLS가 활성화된 경우 "dolt_server_tls": true 키가 추가됩니다. 이 파일은 로컬 내장 데이터베이스 대신 원격 서버에 연결하도록 bd에 지시합니다. 비밀번호는 의도적으로 이 파일에 포함되지 않습니다.

2. 워크스페이스 등록

로컬 디렉터리가 ~/.beads/registry.json에 추가되어 Beadbox와 bd가 다음 실행 시 찾을 수 있게 됩니다.

3. 런타임 인증 정보 전달

Beadbox가 이 워크스페이스에서 bd 명령어를 호출할 때마다 서브프로세스 환경에 BEADS_DOLT_PASSWORD를 설정합니다. 비밀번호는 프로세스 메모리에만 존재합니다.

문제 해결

연결 거부

Error: connect ECONNREFUSED 127.0.0.1:3307

Dolt가 실행 중인가요? ps aux | grep dolt로 확인하거나 프로젝트 디렉터리에서 dolt sql-server를 실행해 보세요.
포트가 맞나요? Dolt의 기본 포트는 3307이지만, 다른 포트로 설정되어 있을 수 있습니다.
방화벽 문제인가요? 원격 서버에서는 인바운드 연결을 위해 포트가 열려 있는지 확인하세요.

접근 거부

Error: Access denied for user 'root'

비밀번호가 필요한가요? Dolt 서버에 인증이 활성화되어 있을 수 있습니다. 연결 양식에 비밀번호를 입력하세요.
사용자 이름이 맞나요? 사용자 이름이 읽기 권한이 있는 Dolt 사용자와 일치하는지 확인하세요.
비밀번호가 맞나요? 비밀번호는 세션 간에 저장되지 않습니다. Beadbox를 재시작한 후 다시 입력하세요.

TLS 핸드셰이크 실패

Error: TLS handshake failed

TLS 체크박스 불일치 서버가 TLS를 요구하면 "TLS 사용"을 체크하세요. TLS를 지원하지 않으면 체크를 해제하세요. 어느 쪽이든 잘못 설정하면 핸드셰이크 오류가 발생합니다.
자체 서명 인증서 Dolt 서버가 자체 서명 인증서를 사용하는 경우, CA를 시스템 트러스트 스토어에 추가해야 할 수 있습니다. bd CLI는 시스템 루트 CA 풀을 사용하며 신뢰할 수 없는 인증서를 거부합니다.

데이터베이스를 찾을 수 없음

No beads databases found on 127.0.0.1:3307.
Databases must follow the beads_* naming pattern.

명명 규칙 Beadbox는 이름이 beads_로 시작하는 데이터베이스만 검색합니다. 데이터베이스 이름이 다른 경우, 이름을 변경하거나 Dolt 모드에서 bd init으로 새 데이터베이스를 생성하세요.
데이터베이스가 있지만 보이지 않나요? 사용자 계정에 모든 데이터베이스를 볼 수 있는 권한이 없을 수 있습니다.
새로운 서버인가요? beads를 초기화하지 않고 Dolt를 시작한 경우, beads 데이터베이스가 아직 없습니다. Dolt 모드가 설정된 프로젝트 디렉터리에서 bd init을 실행한 후 검색을 다시 시도하세요.