@astrojs/ db
Astro DB는 Astro 생태계를 위해 설계된 완전 관리형 SQL 데이터베이스입니다. Astro에서 로컬로 개발하고 Astro Studio 대시보드에서 배포하세요.
Astro DB를 사용하면 콘텐츠를 관계형 데이터베이스로 쿼리하고 모델링할 수 있는 강력하고 타입 안정성을 갖춘 로컬에서 동작하는 도구를 갖게 됩니다. 대화형 Studio 대시보드를 통해 호스팅된 원격 데이터를 확인하고 관리하고 배포하세요.
Astro에는 공식 통합 설정을 자동화하는 astro add
명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.
새 터미널 창에서 다음 명령 중 하나를 실행합니다.
수동 설치
섹션 제목: 수동 설치처음부터 직접 설정하려면 astro add
를 건너뛰고 다음 지침에 따라 Astro DB를 직접 설치하세요.
1. 패키지 관리자를 통해 npm에서 통합 설치
섹션 제목: 1. 패키지 관리자를 통해 npm에서 통합 설치2. astro.config.mjs
파일에 통합 추가
섹션 제목: 2. astro.config.mjs 파일에 통합 추가3. 데이터베이스 구성
섹션 제목: 3. 데이터베이스 구성프로젝트 루트에 db/config.ts
파일을 생성합니다. 이 파일은 Astro가 자동으로 로드하여 데이터베이스 테이블을 구성하는 데 사용되는 특수 파일입니다.
테이블 구성 참조
섹션 제목: 테이블 구성 참조columns
섹션 제목: columns테이블 열은 columns
객체를 사용하여 구성됩니다.
열은 column
유틸리티를 사용하여 구성됩니다. column
은 다음 타입을 지원합니다:
column.text(...)
- 일반 또는 서식 있는 텍스트 콘텐츠 저장column.number(...)
- 정수 및 부동 소수점 값 저장column.boolean(...)
- 참/거짓 값 저장column.date(...)
- 데이터 저장을 위해 ISO 문자열로 구문 분석된Date
객체를 저장column.json(...)
- 데이터 저장을 위해 문자열로 구문 분석된 임의의 JSON Blob을 저장
모든 열에는 몇 가지 공유 구성 값이 있습니다.
primaryKey
-number
또는text
열을 고유 식별자로 설정합니다.optional
- Astro DB는 기본적으로 모든 열에NOT NULL
을 사용합니다. null 값을 허용하려면optional
을true
로 설정하세요.default
- 새로 삽입된 항목의 기본값을 설정합니다. 이는 에 대해 정적 값이나 타임스탬프와 같이 생성된 값을 나타내는sql
문자열을 허용합니다.unique
- 열을 고유한 것으로 표시합니다. 이렇게 하면 테이블의 항목 전체에서 값이 중복되는 것을 방지할 수 있습니다.references
- 각 열과 관련된 테이블을 참조합니다. 이는 외래 키 제약 조건을 설정합니다. 즉, 각 열 값은 참조된 테이블에서 일치하는 값을 가져야 합니다.
indexes
섹션 제목: indexes테이블 인덱스는 특정 열 또는 열 조합에 대한 조회 속도를 향상시키는 데 사용됩니다. indexes
속성은 인덱스를 생성할 열을 지정하는 구성 객체의 배열을 값으로 전달받습니다.
그러면 authorId
및 published
열에 Comment_authorId_published_idx
라는 이름의 고유 인덱스가 생성됩니다.
각 인덱스에 대해 다음 구성 옵션을 사용할 수 있습니다.
on
:string | string[]
- 인덱싱할 단일 열 또는 열 이름 배열입니다.unique
:boolean
- 인덱스가 생성된 열 전체에 고유한 값을 적용하려면true
로 설정합니다.name
:string
(선택 사항) - 고유 인덱스의 사용자 정의 이름입니다. 이는 색인화되는 테이블 및 열 이름을 기반으로 Astro에서 생성된 이름을 재정의합니다 (예:Comment_authorId_published_idx
). 사용자 정의 이름은 전역적이므로 인덱스 이름이 테이블 간에 충돌하지 않는지 확인하세요.
foreignKeys
섹션 제목: foreignKeysforeignKeys
는 여러 테이블 열을 연결하기 위한 고급 API입니다. 단일 열만 참조해야 하는 경우 열 references
속성을 사용하세요.
외래 키는 두 테이블 간 관계를 설정하는 데 사용됩니다. foreignKeys
속성은 테이블 간 하나 이상의 열을 연결할 수 있는 구성 객체의 배열을 허용합니다.
각 외래 키 구성 객체는 다음 속성을 허용합니다.
columns
:string[]
- 참조된 테이블과 관련된 열 이름의 배열입니다.references
:() => Column[]
- 참조된 테이블에서 열 배열을 반환하는 함수입니다.
Astro DB CLI 참조
섹션 제목: Astro DB CLI 참조Astro DB에는 호스팅된 프로젝트 데이터베이스 및 Astro Studio 계정과 상호 작용하는 CLI 명령 세트가 포함되어 있습니다.
이러한 명령은 GitHub CI action을 사용할 때 자동으로 호출되며 astro db
CLI를 사용하여 수동으로 호출할 수 있습니다.
astro db push
섹션 제목: astro db push플래그:
--force-reset
주요 스키마 변경이 필요한 경우 모든 프로덕션 데이터를 재설정합니다.
데이터베이스 구성 변경 사항을 프로젝트 데이터베이스에 안전하게 푸시합니다. 그러면 데이터 손실 위험이 있는지 확인하고 권장되는 마이그레이션 단계를 안내합니다. 주요 스키마 변경을 수행해야 하는 경우 --force-reset
플래그를 사용하여 모든 프로덕션 데이터를 재설정하세요.
astro db verify
섹션 제목: astro db verify로컬 데이터베이스 구성과 원격 데이터베이스 구성 간 차이점을 확인합니다. 이는 astro db push
에 의해 자동으로 실행됩니다. verify
는 로컬 db/config.ts
파일을 원격 데이터베이스와 비교하고 변경 사항이 감지되면 경고합니다.
astro db execute <file-path>
섹션 제목: astro db execute <file-path>플래그:
--remote
Studio 프로젝트 데이터베이스에 대해 실행하세요. 개발 서버에 대한 실행을 생략합니다.
데이터베이스를 읽거나 쓰려면 .ts
또는 .js
파일을 실행하세요. 이는 파일 경로를 인수로 받아들이고 astro:db
모듈을 사용하여 타입 안정성을 갖춘 쿼리를 작성할 수 있도록 지원합니다. Studio 프로젝트 데이터베이스에 대해 실행하려면 --remote
플래그를 사용하고, 개발 서버에 대해 실행하려면 플래그를 생략하세요. 개발 데이터를 시드하는 방법에 대한 예시 파일을 참조하세요.
astro db shell --query <sql-string>
섹션 제목: astro db shell --query <sql-string>플래그:
--query
실행할 원시 SQL 쿼리입니다.--remote
Studio 프로젝트 데이터베이스에 대해 실행하세요. 개발 서버에 대한 실행을 생략합니다.
데이터베이스에 대해 원시 SQL 쿼리를 실행합니다. Studio 프로젝트 데이터베이스에 대해 실행하려면 --remote
플래그를 사용하고, 개발 서버에 대해 실행하려면 플래그를 생략하세요.
Astro DB 유틸리티 참조
섹션 제목: Astro DB 유틸리티 참조isDbError()
섹션 제목: isDbError()isDbError()
함수는 오류가 libSQL 데이터베이스 예외인지 확인합니다. 여기에는 참조 사용 시 외래 키 제약 조건 오류가 포함되거나 데이터 삽입 시 필드 누락이 포함될 수 있습니다. isDbError()
를 try / catch 블록과 결합하여 애플리케이션의 데이터베이스 오류를 처리할 수 있습니다.