커넥션 생성
데이터베이스 연결 정보를 설정하고 커넥션을 생성하는 방법을 안내합니다.
커넥션 추가
프로젝트에 새 데이터베이스 커넥션을 추가합니다.
커넥션 추가 버튼 클릭
좌측 패널의 커넥션 목록에서 "+" 버튼을 클릭합니다.
DBMS 선택
연결할 데이터베이스 종류를 선택합니다. MariaDB, MySQL, Oracle, PostgreSQL, SQL Server, SQLite, H2를 지원합니다.
연결 정보 입력
연결 정보 항목
| 항목 | 설명 | 예시 |
|---|---|---|
| 커넥션 이름 | 구분을 위한 표시 이름 | 개발DB, 운영DB |
| 호스트 | 데이터베이스 서버 주소 | localhost, 192.168.1.100 |
| 포트 | 데이터베이스 서비스 포트 | 3306 (MySQL), 5432 (PostgreSQL) |
| 데이터베이스 | 연결할 데이터베이스(스키마) 이름 | myapp_dev |
| 사용자명 | 데이터베이스 접속 계정 | root, admin |
| 비밀번호 | 접속 계정의 비밀번호 | - |
호스트, 포트, 데이터베이스명, 사용자명, 비밀번호를 입력합니다.
URL 필드에 전체 JDBC URL를 입력하면, Host, Port, Database 등의 정보가 파싱되어 각 입력 필드에 자동으로 매핑됩니다.
URL의 쿼리 파라미터는 키 유형에 따라 SSL/SSH 탭의 SSL 설정 항목이나 Properties 탭에 해당 정보가 자동으로 설정됩니다.
useSSL, sslMode, requireSsl 등)→ SSL/SSH 탭의 SSL 설정 항목으로 매핑됩니다.
기타 파라미터 (useUnicode, characterEncoding, serverTimezone 등)→ Properties 탭에 key-value 형태로 추가됩니다.
커스텀 JDBC 드라이버 등록
JDBC Driver 필드 우측의 설정(톱니바퀴) 버튼을 클릭하면 JDBC Driver Manager가 열립니다. NeoSQL에 번들된 기본(built-in) 드라이버 목록을 확인할 수 있고, Add Custom Driver 버튼을 통해 사용할 .jar 파일을 직접 업로드해 커스텀 드라이버를 등록할 수 있습니다.
| 항목 | 설명 | 예시 |
|---|---|---|
| DBMS Type | 대상 데이터베이스 종류 | - |
| Driver ID | 드라이버 고유 식별자 | oracle-ojdbc10 |
| Label | 드라이버 선택 목록에 표시될 이름 | Oracle (ojdbc10) |
| Driver Class | JDBC Driver 클래스 | oracle.jdbc.OracleDriver |
| Version | 드라이버 버전 | 19.8.0.0 |
| JAR Files | 사용할 드라이버 .jar 파일 | - |
참고: 커스텀 드라이버 등록은 데스크톱 모드에서만 가능합니다. Web App에서는 NeoSQL에 번들된 기본 드라이버만 사용할 수 있습니다.
미설치 커스텀 드라이버 자동 안내
프로젝트 백업 가져오기 · 팀 동기화 · 다른 PC 로 이주 등으로 들여온 커넥션이 이 PC 에 설치되지 않은 커스텀 드라이버를 참조하면, 프로젝트를 열 때 NeoSQL 이 자동으로 드라이버 설치 모달을 표시합니다. 누락된 드라이버의 메타데이터(Driver ID · Class · Version 등)는 미리 채워져 있어 그대로 저장하기만 하면 됩니다.
이때 모달의 Replace bundled 옵션을 켜면 별도 .jar 파일 업로드 없이 NeoSQL 에 번들된 드라이버 JAR 을 그대로 재사용해 설치를 끝낼 수 있어, 백업·동기화로 받은 커넥션을 빠르게 복구할 수 있습니다.
드라이버 삭제
등록한 커스텀 드라이버는 JDBC Driver Manager 의 드라이버 목록 행 끝에 있는 빨간 휴지통 아이콘으로 삭제할 수 있습니다.
연결 테스트 및 저장
"연결 테스트" 버튼으로 연결을 확인한 후 "저장" 버튼을 클릭합니다.
참고: 연결 테스트 실패 시 호스트 주소, 포트, 방화벽 설정, 데이터베이스 접속 권한을 확인하세요.
Connection Properties
JDBC 연결에 사용할 추가 속성을 key-value 형태로 지정합니다. 커넥션 설정 화면의 Properties 탭에서 설정할 수 있습니다.
입력 필드에 key와 value를 입력한 후 ADD 버튼을 클릭하면 속성이 추가됩니다. 추가된 속성은 하단 목록에 표시되며, 각 항목을 삭제할 수 있습니다.
사용 예시
| key | value | 설명 |
|---|---|---|
connectTimeout | 10000 | 연결 타임아웃 (밀리초) |
useUnicode | true | 유니코드 지원 활성화 |
characterEncoding | utf8mb4 | 문자 인코딩 설정 |
serverTimezone | Asia/Seoul | 서버 타임존 설정 |
참고: 각 DBMS별 기본 연결 속성은 자동으로 적용됩니다. 여기서 지정한 속성은 기본값을 덮어씁니다. 사용 가능한 속성은 각 JDBC 드라이버 문서를 참조하세요.
Public 커넥션 vs Private 커넥션
NeoSQL은 입력한 연결 정보를 기반으로, 팀원과 공유 가능한 Public 커넥션과 본인만 사용하는 Private 커넥션으로 자동 분류합니다.
Private 자동 분류 규칙
다음 조건 중 하나라도 만족하면 해당 커넥션은 자동으로 Private 으로 분류됩니다:
- SQLite — 드라이버가
org.sqlite.JDBC이거나 URL이jdbc:sqlite:로 시작 - H2 Embedded — URL이
jdbc:h2:로 시작하면서jdbc:h2:tcp:·jdbc:h2:ssl:가 아닌 경우 (파일/메모리 모드) - 로컬호스트 — Host 가
localhost,127.0.0.1,::1,0.0.0.0중 하나
참고: 사내망 IP 대역(10.x, 172.16~31.x, 192.168.x) 과 host.docker.internal 은 Private 자동 분류에서 제외됩니다.
Public ↔ Private 전환 시 동작
연결 정보를 수정해 분류 결과가 바뀌면 다음과 같이 동작합니다:
- Public → Private — 이 커넥션을 참조하는 팀 ERD가 있으면 확인 모달이 표시되고, 승인 시 해당 ERD들은 자동으로 개인 ERD로 전환됩니다. 다른 팀원의 화면에서는 동기화를 통해 사라집니다.
- Private → Public — 개인 ERD가 자동으로 팀 ERD로 복원되지는 않습니다. 실수로 개인 메모 등이 공유되는 것을 막기 위한 안전장치입니다.
Web App 에서 Private 커넥션 사용 불가
Web 모드에서는 Private 커넥션을 생성·사용할 수 없습니다. Web 모드에서 커넥션 생성 시 Host를 localhost로 지정할 수 없으며, DBMS 선택 시 SQLite/H2 Embedded는 선택 불가합니다.
Desktop 모드를 통해 이미 만들어진 Private 커넥션은 사이드바에서 잠금 아이콘과 함께 비활성으로 표시됩니다.
