Astro DB
Astro DB는 Astro 전용으로 설계된 완전 관리형 SQL 데이터베이스입니다. 로컬에서 개발하거나 Astro Studio 플랫폼에서 관리되는 호스팅된 데이터베이스에 연결하세요.
@astrojs/db
통합 (v0.8.1
이상)을 사용하여 신규 또는 기존 Astro 프로젝트 (astro@4.5
이상 필요)에 Astro DB를 추가하세요. Astro에는 이 설정 프로세스를 자동화하는 astro add
명령이 내장되어 있습니다.
원한다면 @astrojs/db
를 수동으로 설치할 수 있습니다.
데이터베이스 정의
섹션 제목: 데이터베이스 정의Astro DB는 데이터 구성, 개발 및 쿼리를 위한 완벽한 솔루션입니다. Docker나 네트워크 연결 없이 LibSQL을 사용하여 데이터를 관리하는 astro dev
를 실행할 때마다 로컬 데이터베이스가 생성됩니다.
astro add
명령으로 @astrojs/db
를 설치하면 데이터베이스 테이블을 정의할 프로젝트에 db/config.ts
파일이 생성됩니다.
테이블
섹션 제목: 테이블Astro DB의 데이터는 SQL 테이블을 사용하여 저장됩니다. 테이블은 데이터를 행과 열로 구조화하며, 여기서 열은 각 행 값의 타입을 적용합니다.
테이블을 정의하면 Astro는 프로젝트에서 해당 테이블을 쿼리하기 위해 TypeScript 인터페이스를 생성합니다. 결과적으로 데이터에 액세스할 때 속성 자동 완성 및 타입 검사를 통해 완전한 TypeScript 지원이 제공됩니다.
데이터베이스 테이블을 구성하려면 astro:db
에서 defineTable()
및 column
유틸리티를 가져와 사용하세요.
이 예시에서는 author
및 body
에 대한 필수 텍스트 열이 있는 Comment
테이블을 구성합니다. 그런 다음 defineDb()
내보내기를 통해 프로젝트에서 사용할 수 있도록 합니다.
열 (Columns)
섹션 제목: 열 (Columns)Astro DB는 다음 열 타입을 지원합니다.
테이블 참조
섹션 제목: 테이블 참조테이블 간 관계는 데이터베이스 디자인의 일반적인 패턴입니다. 예를 들어, Blog
테이블은 Comment
, Author
및 Category
의 다른 테이블과 밀접하게 관련될 수 있습니다.
테이블 간 관계를 정의하고 참조 열 (reference columns) 을 사용하여 데이터베이스 스키마에 저장할 수 있습니다. 관계를 구축하려면 다음이 필요합니다.
- 참조 테이블의 식별자 열 (identifier column) 이 필요합니다. 이는 일반적으로
primaryKey
속성이 있는id
열입니다. - 참조된
id
를 저장하기 위한 기본 테이블의 열 이 필요합니다. 이는 관계를 설정하기 위해references
속성을 사용합니다.
이 예시에서는 Author
테이블의 id
열을 참조하는 Comment
테이블의 authorId
열을 보여줍니다.
데이터베이스 시드
섹션 제목: 데이터베이스 시드개발 모드에서 Astro는 DB 구성을 사용하여 스키마에 따라 로컬 타입을 생성합니다. 이는 개발 서버가 시작될 때마다 새로 생성되며 타입 안전성 및 자동 완성을 통해 데이터 형태를 쿼리하고 작업할 수 있습니다.
테스트 및 디버깅을 위한 개발 데이터를 Astro 프로젝트에 시드하려면 db/seed.ts
파일을 생성하세요. astro:db
에서 db
객체와 구성된 테이블을 모두 가져옵니다. 테이블 행 데이터 객체의 배열을 제공하려면 db.insert()
함수를 사용하세요.
다음 예시에서는 Comment
테이블에 대한 개발 데이터의 두 행을 정의합니다.
개발 서버는 이 파일이 변경될 때마다 자동으로 데이터베이스를 다시 시작하여 타입을 재생성하고 seed.ts
파일에서 개발 데이터를 시드합니다.
데이터베이스 쿼리
섹션 제목: 데이터베이스 쿼리제공된 db ORM 및 쿼리 빌더를 사용하여 프로젝트의 모든 Astro 페이지 또는 엔드포인트에서 데이터베이스를 쿼리할 수 있습니다.
Drizzle ORM
섹션 제목: Drizzle ORMAstro DB에는 Drizzle ORM 클라이언트가 내장되어 있습니다. 클라이언트를 사용하는 데 필요한 설정이나 수동 구성이 없습니다. Astro DB의 db
클라이언트는 Astro를 실행할 때 데이터베이스 (로컬 또는 원격)와 통신하도록 자동으로 구성됩니다. 존재하지 않는 열이나 테이블을 참조할 때, TypeScript 오류가 발생한 타입 안정성을 갖춘 SQL 쿼리에 대해 정확한 데이터베이스 스키마 정의를 사용합니다.
Select
섹션 제목: Select다음 예시에서는 Comment
테이블의 모든 행을 선택합니다. 그러면 페이지 템플릿에서 사용할 수 있는 db/seed.ts
파일에서 시드된 개발 데이터의 전체 배열이 반환됩니다.
select()
API 참조를 확인하세요.
Insert
섹션 제목: Insert양식 요청 처리 및 원격 호스팅 데이터베이스에 데이터 삽입과 같은 사용자 입력을 허용하려면 Astro 프로젝트에 주문형 렌더링을 구성하고 배포 환경에 SSR 어댑터를 추가하세요.
이 예시에서는 구문 분석된 양식 POST 요청을 기반으로 Comment
테이블에 행을 삽입합니다.
API 엔드포인트에서 데이터베이스를 쿼리할 수도 있습니다. 이 예시에서는 id
매개변수를 사용하여 Comment
테이블에서 행을 삭제합니다.
전체 개요는 Drizzle insert()
API 참조를 확인하세요.
필터링
섹션 제목: 필터링특정 속성으로 테이블 결과를 쿼리하려면 부분 선택을 위한 Drizzle 옵션을 사용하세요. 예를 들어, select()
쿼리에 .where()
호출을 추가하고 원하는 비교를 전달합니다.
다음 예시에서는 “Astro DB”라는 문구가 포함된 Comment
테이블의 모든 행을 쿼리합니다. body
에 문구가 있는지 확인하려면 like()
연산자를 사용하세요.
Drizzle 유틸리티
섹션 제목: Drizzle 유틸리티쿼리 작성을 위한 모든 Drizzle 유틸리티는 astro:db
모듈에서 노출됩니다. 여기에는 다음이 포함됩니다.
SQL join을 사용하여 여러 테이블에서 관련 데이터를 쿼리할 수 있습니다. join 쿼리를 생성하려면 db.select()
문을 join 연산자로 확장하세요. 각 함수는 join할 테이블과 두 테이블 사이의 행을 일치시키는 조건을 인자로 전달받습니다.
이 예시에서는 innerJoin()
함수를 사용하여 authorId
열을 기반으로 Comment
의 authors를 관련 Author
정보와 join합니다. 그러면 각 Author
및 Comment
행이 최상위 속성인 객체 배열이 반환됩니다.
사용 가능한 모든 join 연산자 및 구성 옵션은 Drizzle join 참조를 확인하세요.
일괄 트랜잭션
섹션 제목: 일괄 트랜잭션모든 원격 데이터베이스 쿼리는 네트워크 요청으로 이루어집니다. 많은 수의 쿼리를 수행할 때 쿼리를 단일 트랜잭션으로 함께 “일괄 처리”하거나 쿼리가 실패할 경우 자동 롤백을 수행해야 할 수도 있습니다.
이 예시에서는 db.batch()
메서드를 사용하여 단일 요청에 여러 행을 시드합니다.
자세한 내용은 Drizzle db.batch()
문서를 참조하세요.
Astro Studio
섹션 제목: Astro StudioAstro DB는 Astro Studio 플랫폼을 연결하여 호스팅된 데이터베이스를 프로젝트에 빠르게 추가할 수 있습니다. Astro Studio 대시보드에서 새로운 호스팅 데이터베이스를 확인하고, 관리하고, 배포할 수 있습니다.
새 프로젝트를 생성하려면 미리 만들어진 템플릿을 사용하거나 Astro Studio 가이드를 방문하세요.
테이블 스키마 푸시
섹션 제목: 테이블 스키마 푸시프로젝트가 성장함에 따라 테이블 스키마가 오버타임으로 변경됩니다. 구성 변경 사항을 로컬에서 안전하게 테스트하고, 배포 시 Studio 데이터베이스에 푸시할 수 있습니다.
대시보드에서 Studio 프로젝트를 생성할 때 GitHub CI action을 생성할 수 있는 옵션이 제공됩니다. 그러면 저장소의 main 브랜치와 병합할 때 스키마 변경 사항이 자동으로 마이그레이션됩니다.
astro db push --remote
명령을 사용하여 CLI를 통해 로컬 스키마 변경 사항을 Astro Studio로 푸시할 수도 있습니다.
이 명령은 데이터 손실 없이 로컬 변경이 이루어질 수 있는지 확인하고 필요한 경우 충돌을 해결하기 위해 스키마를 안전하게 변경하는 방법을 제안합니다.
주요 스키마 변경 사항 푸시
섹션 제목: 주요 스키마 변경 사항 푸시이렇게 하면 데이터베이스가 파괴됩니다. 프로덕션 데이터가 필요하지 않은 경우에만 이 명령을 수행하세요.
Astro Studio에서 호스팅되는 기존 데이터와 호환되지 않는 방식으로 테이블 스키마를 변경해야 하는 경우 프로덕션 데이터베이스를 재설정해야 합니다.
주요 변경 사항이 포함된 테이블 스키마 업데이트를 푸시하려면 --force-reset
플래그를 추가하여 모든 프로덕션 데이터를 재설정하세요.
테이블 이름 변경
섹션 제목: 테이블 이름 변경스키마를 Astro Studio로 푸시한 후 테이블 이름을 변경할 수 있습니다.
중요한 프로덕션 데이터가 없는 경우 --force-reset
플래그를 사용하여 데이터베이스를 재설정할 수 있습니다. 이 플래그는 데이터베이스의 모든 테이블을 삭제하고 현재 스키마와 정확히 일치하는 새 테이블을 생성합니다.
프로덕션 데이터를 보존하면서 테이블 이름을 변경하려면, 기존 기능을 중단하지 않는 변경을 수행하여 로컬 스키마를 Astro Studio에 안전하게 푸시해야 합니다.
다음 예시에서는 테이블의 이름을 Comment
에서 Feedback
으로 변경합니다.
-
데이터베이스 구성 파일에서 이름을 바꾸려는 테이블에
deprecated: true
속성을 추가하세요. -
새 이름으로 새 테이블 스키마 (기존 테이블의 속성과 정확히 일치)를 추가합니다.
-
astro db push --remote
명령을 사용하여 Astro Studio로 푸시합니다. 그러면 새 테이블이 추가되고 이전 테이블은 더 이상 사용되지 않는 것으로 표시됩니다. -
이전 테이블 대신 새 테이블을 사용하도록 로컬 프로젝트 코드를 업데이트하세요. 데이터를 새 테이블로 마이그레이션해야 할 수도 있습니다.
-
이전 테이블이 프로젝트에서 더 이상 사용되지 않는다고 확신하면
config.ts
파일에서 스키마를 제거할 수 있습니다. -
astro db push --remote
명령을 사용하여 Astro Studio로 다시 푸시합니다. 이전 테이블은 삭제되고 이름이 변경된 새 테이블만 남습니다.
데이터 푸시
섹션 제목: 데이터 푸시시드 또는 데이터 마이그레이션을 위해 Studio 데이터베이스에 데이터를 푸시해야 할 수도 있습니다. 타입 안정성을 갖춘 쿼리를 작성하려면 astro:db
모듈을 사용하여 .ts
파일을 작성할 수 있습니다. 그런 다음 astro db execute <file-path> --remote
명령을 사용하여 Studio 데이터베이스에 대해 파일을 실행합니다.
다음 Comments는 astro db execute db/seed.ts --remote
명령을 사용하여 시드할 수 있습니다.
전체 명령 목록은 CLI 참조를 확인하세요.
Astro Studio에 연결
섹션 제목: Astro Studio에 연결기본적으로 Astro는 dev
또는 build
명령을 실행할 때마다 로컬 데이터베이스 파일을 사용합니다. 각 명령이 실행될 때마다 테이블이 처음부터 다시 생성되고 개발 시드 데이터가 삽입됩니다.
호스팅된 Studio 데이터베이스에 연결하려면 --remote
플래그를 추가하면 됩니다. Studio 데이터베이스에 대한 읽기 및 쓰기 액세스 권한을 모두 가지려면 프로덕션 배포에 이 플래그를 사용하세요. 이렇게 하면 사용자 데이터를 입력받고 유지할 수 있습니다.
개발 모드에서 --remote
사용에 주의하세요. 이는 라이브 프로덕션 데이터베이스에 연결되며 모든 삽입, 업데이트 또는 삭제가 유지됩니다.
원격 연결을 사용하려면 Studio에 인증하기 위한 앱 토큰이 필요합니다. 토큰 생성 및 설정 지침을 보려면 Studio 대시보드를 방문하세요.
배포할 준비가 되면 Studio 연결 및 배포 가이드를 확인하세요.
Astro DB 통합 구축
섹션 제목: Astro DB 통합 구축Astro 통합은 추가 Astro DB 테이블 및 시드 데이터를 사용하여 사용자 프로젝트를 확장할 수 있습니다.
추가 Astro DB 구성 및 시드 파일을 등록하려면 astro:db:setup
후크에서 extendDb()
메서드를 사용하세요.
defineDbIntegration()
도우미는 astro:db:setup
후크에 대한 TypeScript 지원 및 자동 완성 기능을 제공합니다.
통합 config 및 seed 파일은 해당 사용자 정의 파일과 동일한 형식을 따릅니다.
타입 안정성을 갖춘 통합 작업
섹션 제목: 타입 안정성을 갖춘 통합 작업통합 작업을 하는 동안, Astro에서 생성된 (astro:db
에서 내보낸) 테이블 타입의 이점을 활용하지 못할 수도 있습니다.
완전한 타입 안정성을 위해 asDrizzleTable()
유틸리티를 사용하여 데이터베이스 작업에 사용할 수 있는 테이블 참조 객체를 생성하세요.
예를 들어, 다음 Pets
데이터베이스 테이블을 설정하는 통합이 있다고 가정해 보겠습니다.
시드 파일은 Pets
를 가져오고 asDrizzleTable()
을 사용하여 타입 검사를 통해 테이블에 행을 삽입할 수 있습니다.
asDrizzleTable('Pets', Pets)
에 의해 반환된 값은 import { Pets } from 'astro:db'
와 동일하지만, Astro의 타입 생성을 실행할 수 없는 경우에도 사용할 수 있습니다.
데이터베이스에 쿼리하거나 삽입해야 하는 모든 통합 코드에서 이를 사용할 수 있습니다.
자체 호스팅 프로덕션 배포
섹션 제목: 자체 호스팅 프로덕션 배포가상 사설 서버와 같은 자체 관리형 호스트에 사이트를 배포하는 경우 호스팅되는 데이터베이스에 연결하는 대신 Astro Studio에서 데이터베이스 파일을 사용하도록 선택할 수 있습니다.
데이터베이스 파일을 사용하는 것은 고급 기능이므로 배포 시 데이터베이스가 재정의되어 프로덕션 데이터가 손실되지 않도록 주의해야 합니다.
또한 서버리스 배포에서는 파일 시스템이 유지되지 않으므로 이 방법은 작동하지 않습니다.
완전 관리형 솔루션의 경우 Astro Studio 플랫폼에서 호스팅되는 데이터베이스에 연결하세요.
위험을 감수하고 배포를 직접 관리할 수 있는 경우 Studio에 연결하는 대신 데이터베이스 파일을 사용할 수 있습니다.
빌드하는 동안 호스트 환경에서 .db
파일을 가리키는 경로로 ASTRO_DATABASE_FILE
환경 변수를 설정합니다.
빌드는 정적으로 이 경로를 프로덕션 데이터베이스로 컴파일합니다. 서버를 배포하고 실행하면 프로덕션 호스트에 있는 이 경로의 파일에 연결됩니다.
또한 테이블 스키마 변경 사항 푸시 (“스키마 마이그레이션” 이라고도 함)는 이 환경 변수를 사용하여 수동으로 관리해야 합니다.
배포 시 .db
파일을 재정의하면 프로덕션 데이터가 손실됩니다. 데이터 손실을 방지하려면 호스트의 배포 방법 프로세스를 주의 깊게 따르세요.