Snowflake 워크스페이스 폴더 네이밍 권장 규칙

실무를 하다 보면, 작은 것부터 헷갈리는 법!

 

나연 대표님~ 아래 내용을 직원들에게 공유해주고, 습관 들이라고 해주세요~

 

---

 

공식 권장 패턴: TEAM_PROJECT_NAME (밑줄 구분, 명확하고 일관된 패턴)

실무 가이드

규칙	예시	설명
소문자 or snake_case	crm_analytics/	가장 보편적
목적 + 주제 조합	data_eng_pipeline/	팀_프로젝트
숫자 접두사 (정렬용)	01_ingestion/, 02_transform/	단계별 정렬하기 유리
환경 구분	dev/, staging/, prod/	배포 단계

피해야 할 것

• 공백 포함 (경로 참조 시 문제 가능)
• 한글 폴더명 (CLI 호환성 이슈) : CLI를 AI 코딩 툴에서 많이 사용하는데, 그럴 때 오류나기 쉬워요.
• 특수문자 (@, #, & 등) : 탐색기 폴더에 특수문자 넣지 못하는 것과 비슷해요^^ 쉽죠?
• 너무 깊은 중첩 (3단계 이내 권장)

 

두 가지 포인트로 정리하면:

1. 로컬 Git 폴더도 동일한 숫자 + 소문자 + snake_case 또는 kebab-case 가 좋습니다.

• 파일시스템 레벨(워크스페이스든 macOS든)에서는 소문자 kebab-case가 범용 베스트 프랙티스입니다.
• macOS는 기본적으로 case-insensitive이므로, 대소문자 혼용하면 Git에서 rename 충돌이 생길 수 있어서 소문자 통일이 안전합니다.
• 워크스페이스와 로컬 Git 구조를 동일하게 유지하면 동기화/이동이 편합니다.

2. Snowflake 오브젝트명은 자동으로 대문자로 치환합니다.

Snowflake는 identifier를 쌍따옴표("...")로 감싸지 않는 한 자동으로 UPPERCASE로 저장합니다. 즉:

CREATE TABLE my_table ...  -- 내부적으로 MY_TABLE로 저장됨
SELECT * FROM my_table;    -- MY_TABLE을 찾아감 (정상 동작)

 

그래서 SQL 파일 안에서 select * from db_gold.sch_gld_open.v_something 이라고 소문자로 써도 실행에는 문제 없습니다. Snowflake가 알아서 대문자로 resolve합니다.

 

하지만 소문자로 지정된 경우에는 반드시 쌍따옴표로 감싸서 쿼리해야 합니다.

-- Snopwflake 사용자의 아이디가 u_nabi 인 경우
-- 이 유저에게 tag를 설정하고 싶으면

ALTER USER "u_nabi" SET TAG my_db.my_schema.my_tag = '나연의비서';

-- 위와 같이 꼭 쌍따옴표를 써야 한다.

 

 

결론: 레이어를 분리해서 생각하면 됩니다

레이어	컨벤션	이유
파일/폴더명 (Git, 워크스페이스)	01-cost/coco_limit.sql	OS 호환성, Git 안정성
SQL 내 오브젝트명	대문자든 소문자든 무관	Snowflake가 자동 UPPERCASE 처리
AGENTS.md 등 문서 참조	UPPERCASE	Snowflake 카탈로그와 1:1 매칭 용이

파일명은 소문자로 관리하고, SQL 본문이나 문서에서 오브젝트를 언급할 때는 UPPERCASE로 쓰는 게 가독성과 일관성 모두 잡는 방식입니다.