컨텐츠로 건너뛰기

Astro DB

Astro DB는 Astro 전용으로 설계된 완전 관리형 SQL 데이터베이스입니다. 로컬에서 개발하거나 Astro Studio 플랫폼에서 관리되는 호스팅된 데이터베이스에 연결하세요.

설치

섹션 제목: 설치

@astrojs/db 통합 (v0.8.1 이상)을 사용하여 신규 또는 기존 Astro 프로젝트 (astro@4.5 이상 필요)에 Astro DB를 추가하세요. Astro에는 이 설정 프로세스를 자동화하는 astro add 명령이 내장되어 있습니다.

Terminal window
npx astro add db

원한다면 @astrojs/db를 수동으로 설치할 수 있습니다.

데이터베이스 정의

섹션 제목: 데이터베이스 정의

Astro DB는 데이터 구성, 개발 및 쿼리를 위한 완벽한 솔루션입니다. Docker나 네트워크 연결 없이 libSQL을 사용하여 데이터를 관리하는 astro dev를 실행할 때마다 로컬 데이터베이스가 생성됩니다.

astro add 명령으로 @astrojs/db를 설치하면 데이터베이스 테이블을 정의할 프로젝트에 db/config.ts 파일이 생성됩니다.

db/config.ts
import { defineDb } from 'astro:db';


export default defineDb({
  tables: { },
})

테이블

섹션 제목: 테이블

Astro DB의 데이터는 SQL 테이블을 사용하여 저장됩니다. 테이블은 데이터를 행과 열로 구조화하며, 여기서 열은 각 행 값의 타입을 적용합니다.

테이블을 정의하면 Astro는 프로젝트에서 해당 테이블을 쿼리하기 위해 TypeScript 인터페이스를 생성합니다. 결과적으로 데이터에 액세스할 때 속성 자동 완성 및 타입 검사를 통해 완전한 TypeScript 지원이 제공됩니다.

데이터베이스 테이블을 구성하려면 astro:db에서 defineTable() 및 column 유틸리티를 가져와 사용하세요.

이 예시에서는 author 및 body에 대한 필수 텍스트 열이 있는 Comment 테이블을 구성합니다. 그런 다음 defineDb() 내보내기를 통해 프로젝트에서 사용할 수 있도록 합니다.

db/config.ts
import { defineDb, defineTable, column } from 'astro:db';


const Comment = defineTable({
  columns: {
    author: column.text(),
    body: column.text(),
  }
})


export default defineDb({
  tables: { Comment },
})
테이블 옵션에 대한 전체 참조는 테이블 구성 참조를 확인하세요.

열 (Columns)

섹션 제목: 열 (Columns)

Astro DB는 다음 열 타입을 지원합니다.

db/config.ts
import { defineTable, column } from 'astro:db';


const Comment = defineTable({
  columns: {
    // 텍스트 문자열입니다.
    author: column.text(),
    // 정수 값입니다.
    likes: column.number(),
    // 참 또는 거짓 값입니다.
    flagged: column.boolean(),
    // JavaScript Date 객체로 쿼리되는 날짜/시간 값입니다.
    published: column.date(),
    // 타입이 설정되지 않은 JSON 객체입니다.
    metadata: column.json(),
  }
});
자세한 내용은 테이블 열 참조를 확인하세요.

테이블 참조

섹션 제목: 테이블 참조

테이블 간 관계는 데이터베이스 디자인의 일반적인 패턴입니다. 예를 들어, Blog 테이블은 Comment, Author 및 Category의 다른 테이블과 밀접하게 관련될 수 있습니다.

테이블 간 관계를 정의하고 참조 열 (reference columns) 을 사용하여 데이터베이스 스키마에 저장할 수 있습니다. 관계를 구축하려면 다음이 필요합니다.

  • 참조 테이블의 식별자 열 (identifier column) 이 필요합니다. 이는 일반적으로 primaryKey 속성이 있는 id 열입니다.
  • 참조된 id를 저장하기 위한 기본 테이블의 열 이 필요합니다. 이는 관계를 설정하기 위해 references 속성을 사용합니다.

이 예시에서는 Author 테이블의 id 열을 참조하는 Comment 테이블의 authorId 열을 보여줍니다.

db/config.ts
const Author = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
  }
});


const Comment = defineTable({
  columns: {
    authorId: column.number({ references: () => Author.columns.id }),
    body: column.text(),
  }
});

데이터베이스 시드

섹션 제목: 데이터베이스 시드

개발 모드에서 Astro는 DB 구성을 사용하여 스키마에 따라 로컬 타입을 생성합니다. 이는 개발 서버가 시작될 때마다 새로 생성되며 타입 안전성 및 자동 완성을 통해 데이터 형태를 쿼리하고 작업할 수 있습니다.

테스트 및 디버깅을 위한 개발 데이터를 Astro 프로젝트에 시드하려면 db/seed.ts 파일을 생성하세요. astro:db에서 db 객체와 구성된 테이블을 모두 가져옵니다. 테이블 행 데이터 객체의 배열을 제공하려면 db.insert() 함수를 사용하세요.

다음 예시에서는 Comment 테이블에 대한 개발 데이터의 두 행을 정의합니다.

db/seed.ts
import { db, Comment, Author } from 'astro:db';


export default async function() {
  await db.insert(Author).values([
    { id: 1, name: "Kasim" },
    { id: 2, name: "Mina" },
  ]);


  await db.insert(Comment).values([
    { authorId: 1, body: 'Hope you like Astro DB!' },
    { authorId: 2, body: 'Enjoy!'},
  ])
}

개발 서버는 이 파일이 변경될 때마다 자동으로 데이터베이스를 다시 시작하여 타입을 재생성하고 seed.ts 파일에서 개발 데이터를 시드합니다.

데이터베이스 쿼리

섹션 제목: 데이터베이스 쿼리

제공된 db ORM 및 쿼리 빌더를 사용하여 프로젝트의 모든 Astro 페이지 또는 엔드포인트에서 데이터베이스를 쿼리할 수 있습니다.

Drizzle ORM

섹션 제목: Drizzle ORM
import { db } from 'astro:db';

Astro DB에는 Drizzle ORM 클라이언트가 내장되어 있습니다. 클라이언트를 사용하는 데 필요한 설정이나 수동 구성이 없습니다. Astro DB의 db 클라이언트는 Astro를 실행할 때 데이터베이스 (로컬 또는 원격)와 통신하도록 자동으로 구성됩니다. 존재하지 않는 열이나 테이블을 참조할 때, TypeScript 오류가 발생한 타입 안정성을 갖춘 SQL 쿼리에 대해 정확한 데이터베이스 스키마 정의를 사용합니다.

Select

섹션 제목: Select

다음 예시에서는 Comment 테이블의 모든 행을 선택합니다. 그러면 페이지 템플릿에서 사용할 수 있는 db/seed.ts 파일에서 시드된 개발 데이터의 전체 배열이 반환됩니다.

src/pages/index.astro
---
import { db, Comment } from 'astro:db';


const comments = await db.select().from(Comment);
---


<h2>Comments</h2>


{
  comments.map(({ author, body }) => (
    <article>
      <p>Author: {author}</p>
      <p>{body}</p>
    </article>
  ))
}
전체 개요는 Drizzle select() API 참조를 확인하세요.

Insert

섹션 제목: Insert

양식 요청 처리 및 원격 호스팅 데이터베이스에 데이터 삽입과 같은 사용자 입력을 허용하려면 Astro 프로젝트에 주문형 렌더링을 구성하고 배포 환경에 SSR 어댑터를 추가하세요.

이 예시에서는 구문 분석된 양식 POST 요청을 기반으로 Comment 테이블에 행을 삽입합니다.

src/pages/index.astro
---
import { db, Comment } from 'astro:db';


if (Astro.request.method === 'POST') {
  // 양식 데이터 구문 분석
  const formData = await Astro.request.formData();
  const author = formData.get('author');
  const content = formData.get('content');
  if (typeof author === 'string' && typeof content === 'string') {
    // Comment 테이블에 양식 데이터 삽입
    await db.insert(Comment).values({ author, content });
  }
}


// 각 요청에 대해 새로운 comments 목록을 렌더링
const comments = await db.select().from(Comment);
---


<form method="POST" style="display: grid">
  <label for="author">Author</label>
  <input id="author" name="author" />


  <label for="content">Content</label>
  <textarea id="content" name="content"></textarea>


  <button type="submit">Submit</button>
</form>


<!--`comments` 렌더링-->

API 엔드포인트에서 데이터베이스를 쿼리할 수도 있습니다. 이 예시에서는 id 매개변수를 사용하여 Comment 테이블에서 행을 삭제합니다.

src/pages/api/comments/[id].ts
import type { APIRoute } from "astro";
import { db, Comment, eq } from 'astro:db';


export const DELETE: APIRoute = async (ctx) => {
  await db.delete(Comment).where(eq(Comment.id, ctx.params.id ));
  return new Response(null, { status: 204 });
}

전체 개요는 Drizzle insert() API 참조를 확인하세요.

필터링

섹션 제목: 필터링

특정 속성으로 테이블 결과를 쿼리하려면 부분 선택을 위한 Drizzle 옵션을 사용하세요. 예를 들어, select() 쿼리에 .where() 호출을 추가하고 원하는 비교를 전달합니다.

다음 예시에서는 “Astro DB”라는 문구가 포함된 Comment 테이블의 모든 행을 쿼리합니다. body에 문구가 있는지 확인하려면 like() 연산자를 사용하세요.

src/pages/index.astro
---
import { db, Comment, like } from 'astro:db';


const comments = await db.select().from(Comment).where(
    like(Comment.body, '%Astro DB%')
);
---

Drizzle 유틸리티

섹션 제목: Drizzle 유틸리티

쿼리 작성을 위한 모든 Drizzle 유틸리티는 astro:db 모듈에서 노출됩니다. 여기에는 다음이 포함됩니다.

import { eq, gt, count, sql } from 'astro:db';

관계

섹션 제목: 관계

SQL join을 사용하여 여러 테이블에서 관련 데이터를 쿼리할 수 있습니다. join 쿼리를 생성하려면 db.select() 문을 join 연산자로 확장하세요. 각 함수는 join할 테이블과 두 테이블 사이의 행을 일치시키는 조건을 인자로 전달받습니다.

이 예시에서는 innerJoin() 함수를 사용하여 authorId 열을 기반으로 Comment의 authors를 관련 Author 정보와 join합니다. 그러면 각 Author 및 Comment 행이 최상위 속성인 객체 배열이 반환됩니다.

src/pages/index.astro
---
import { db, eq, Comment, Author } from 'astro:db';


const comments = await db.select()
  .from(Comment)
  .innerJoin(Author, eq(Comment.authorId, Author.id));
---


<h2>Comments</h2>


{
  comments.map(({ Author, Comment }) => (
    <article>
      <p>Author: {Author.name}</p>
      <p>{Comment.body}</p>
    </article>
  ))
}

사용 가능한 모든 join 연산자 및 구성 옵션은 Drizzle join 참조를 확인하세요.

일괄 트랜잭션

섹션 제목: 일괄 트랜잭션

모든 원격 데이터베이스 쿼리는 네트워크 요청으로 이루어집니다. 많은 수의 쿼리를 수행할 때 쿼리를 단일 트랜잭션으로 함께 “일괄 처리”하거나 쿼리가 실패할 경우 자동 롤백을 수행해야 할 수도 있습니다.

이 예시에서는 db.batch() 메서드를 사용하여 단일 요청에 여러 행을 시드합니다.

db/seed.ts
import { db, Author, Comment } from 'astro:db';


export default async function () {
  const queries = [];
  // 단일 네트워크 요청으로 원격 데이터베이스에 100개의 샘플 comments를 시드합니다.
  for (let i = 0; i < 100; i++) {
    queries.push(db.insert(Comment).values({ body: `Test comment ${i}` }));
  }
  await db.batch(queries);
}

자세한 내용은 Drizzle db.batch() 문서를 참조하세요.

Astro Studio

섹션 제목: Astro Studio
Studio 기능

Astro DB는 Astro Studio 플랫폼을 연결하여 호스팅된 데이터베이스를 프로젝트에 빠르게 추가할 수 있습니다. Astro Studio 대시보드에서 새로운 호스팅 데이터베이스를 확인하고, 관리하고, 배포할 수 있습니다.

Astro Studio 웹 포털을 사용하면 웹 인터페이스나 CLI 명령을 사용하여 원격 호스팅 Astro DB 데이터베이스에 연결하고 관리할 수 있습니다.

Studio 대시보드에서 계정 관리, 도움말 및 지원 메시지 콘솔에 액세스할 수 있습니다.

Astro Studio를 방문하여 회원가입 또는 로그인을 해주세요.

새 Studio 프로젝트 생성

섹션 제목: 새 Studio 프로젝트 생성
Studio 기능

Astro Studio에서 프로젝트를 생성하는 방법에는 두 가지가 있습니다.

  1. Astro Studio 웹 UI를 사용하여 신규 또는 기존 GitHub 저장소에서 생성합니다.

    시작하려면 헤더에 있는 “create project” 버튼을 클릭하고 지침을 따르세요. Astro Studio는 GitHub 저장소를 연결하고 프로젝트를 위한 새로운 호스팅 데이터베이스를 생성합니다.

  2. Astro Studio CLI를 사용하여 로컬 Astro 프로젝트에서 생성합니다. 다음 명령을 실행하여 시작할 수 있습니다.

    Terminal window
    # GitHub 계정으로 Astro Studio에 로그인합니다.
    npx astro login
    

    # 프롬프트를 따라 새 프로젝트에 연결합니다.
    npx astro link
    

    # (선택 사항) 로컬 DB 구성을 원격 데이터베이스에 푸시합니다.
    npx astro db push

    로그인 및 연결이 성공적으로 완료되었다면 모든 Astro DB 명령을 실행하여 원격 데이터베이스를 관리할 수 있습니다.

    사용 가능한 모든 명령은 Astro DB CLI 참조를 확인하세요.

Studio 연결을 사용하여 배포

섹션 제목: Studio 연결을 사용하여 배포
Studio 기능

Studio 데이터베이스에 대한 라이브 연결을 통해 Astro DB 프로젝트를 배포할 수 있습니다. 이는 정적 빌드나 SSR 어댑터를 사용하는 모든 배포 플랫폼에서 가능합니다.

먼저 --remote 플래그를 사용하여 Studio와 연결하도록 빌드 명령을 구성합니다. 이 예시에서는 프로젝트의 package.json 파일에 있는 "build" 스크립트에 플래그를 적용합니다. 배포 플랫폼이 빌드 명령을 허용하는 경우 npm run build로 설정되어 있는지 확인하세요.

package.json
{
  "scripts": {
    "build": "astro build --remote"
  }
}

Studio 앱 토큰 생성

섹션 제목: Studio 앱 토큰 생성
Studio 기능

프로덕션 배포에서 Studio 데이터베이스에 액세스하려면 앱 토큰을 생성해야 합니다. Settings 탭으로 이동하고 Tokens를 선택하여 Studio 프로젝트 대시보드에서 앱 토큰을 생성할 수 있습니다.

생성된 토큰을 복사하고 ASTRO_STUDIO_APP_TOKEN를 이름으로 사용하여 배포 플랫폼에서 환경 변수 / 환경 비밀로 적용합니다.

GitHub CI Action 설정

섹션 제목: GitHub CI Action 설정
Studio 기능

Studio CI action을 사용하면 스키마 변경 사항을 Studio 데이터베이스에 자동으로 푸시할 수 있습니다. 이를 통해 변경 사항이 안전하게 적용될 수 있는지 확인하고 main에 병합할 때마다 구성을 최신 상태로 유지합니다.

GitHub 문서에 따라 ASTRO_STUDIO_APP_TOKEN이라는 이름과 Studio 앱 토큰을 비밀 값으로 사용하여 저장소에 새 비밀을 구성하세요.

비밀이 구성되면 프로젝트의 .github/workflows 디렉터리에 새 GitHub Actions 워크플로 파일을 생성하여 단계별로 저장소를 체크아웃하고 Node.js를 설치하고 withastro/action-studio action을 사용하여 스키마 변경 사항을 동기화하세요.

이 action은 모든 이벤트 트리거에서 astro db verify를 실행하여 스키마 변경 사항이 안전하게 적용될 수 있는지 확인합니다. push 트리거를 별도로 추가하면 action이 해당 변경 사항을 Studio 데이터베이스에 푸시합니다.

이 예시 GitHub Action _studio.yml은 main 브랜치가 업데이트될 때마다 변경 사항을 푸시합니다.

.github/workflows/_studio.yml
name: Astro Studio


env:
  ASTRO_STUDIO_APP_TOKEN: ${{secrets.ASTRO_STUDIO_APP_TOKEN }}


on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, reopened, synchronize]


jobs:
  DB:
    permissions:
      contents: read
      actions: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: jaid/action-npm-install@v1.2.1
      - uses: withastro/action-studio@main

테이블 스키마 푸시

섹션 제목: 테이블 스키마 푸시
Studio 기능

프로젝트가 성장함에 따라 테이블 스키마가 오버타임으로 변경됩니다. 구성 변경 사항을 로컬에서 안전하게 테스트하고, 배포 시 Studio 데이터베이스에 푸시할 수 있습니다.

대시보드에서 Studio 프로젝트를 생성할 때 GitHub CI action을 생성할 수 있는 옵션이 제공됩니다. 그러면 저장소의 main 브랜치와 병합할 때 스키마 변경 사항이 자동으로 마이그레이션됩니다.

astro db push --remote 명령을 사용하여 CLI를 통해 로컬 스키마 변경 사항을 Astro Studio로 푸시할 수도 있습니다.

Terminal window
npm run astro db push --remote

이 명령은 데이터 손실 없이 로컬 변경이 이루어질 수 있는지 확인하고 필요한 경우 충돌을 해결하기 위해 스키마를 안전하게 변경하는 방법을 제안합니다.

주요 스키마 변경 사항 푸시

섹션 제목: 주요 스키마 변경 사항 푸시

Astro Studio에서 호스팅되는 기존 데이터와 호환되지 않는 방식으로 테이블 스키마를 변경해야 하는 경우 프로덕션 데이터베이스를 재설정해야 합니다.

주요 변경 사항이 포함된 테이블 스키마 업데이트를 푸시하려면 --force-reset 플래그를 추가하여 모든 프로덕션 데이터를 재설정하세요.

Terminal window
npm run astro db push --remote --force-reset

테이블 이름 변경

섹션 제목: 테이블 이름 변경
Studio 기능

스키마를 Astro Studio로 푸시한 후 테이블 이름을 변경할 수 있습니다.

중요한 프로덕션 데이터가 없는 경우 --force-reset 플래그를 사용하여 데이터베이스를 재설정할 수 있습니다. 이 플래그는 데이터베이스의 모든 테이블을 삭제하고 현재 스키마와 정확히 일치하는 새 테이블을 생성합니다.

프로덕션 데이터를 보존하면서 테이블 이름을 변경하려면, 기존 기능을 중단하지 않는 변경을 수행하여 로컬 스키마를 Astro Studio에 안전하게 푸시해야 합니다.

다음 예시에서는 테이블의 이름을 Comment에서 Feedback으로 변경합니다.

  1. 데이터베이스 구성 파일에서 이름을 바꾸려는 테이블에 deprecated: true 속성을 추가하세요.

    db/config.ts
    const Comment = defineTable({
      deprecated: true,
      columns: {
        author: column.text(),
        body: column.text(),
      }
    });

  2. 새 이름으로 새 테이블 스키마 (기존 테이블의 속성과 정확히 일치)를 추가합니다.

    db/config.ts
    const Comment = defineTable({
      deprecated: true,
      columns: {
        author: column.text(),
        body: column.text(),
      }
    });
    

    const Feedback = defineTable({
      columns: {
        author: column.text(),
        body: column.text(),
      }
    });

  3. astro db push --remote 명령을 사용하여 Astro Studio로 푸시합니다. 그러면 새 테이블이 추가되고 이전 테이블은 더 이상 사용되지 않는 것으로 표시됩니다.

  4. 이전 테이블 대신 새 테이블을 사용하도록 로컬 프로젝트 코드를 업데이트하세요. 데이터를 새 테이블로 마이그레이션해야 할 수도 있습니다.

  5. 이전 테이블이 프로젝트에서 더 이상 사용되지 않는다고 확신하면 config.ts 파일에서 스키마를 제거할 수 있습니다.

    db/config.ts
    const Comment = defineTable({
      deprecated: true,
      columns: {
        author: column.text(),
        body: column.text(),
      }
    });
    

    const Feedback = defineTable({
      columns: {
        author: column.text(),
        body: column.text(),
      }
    });

  6. astro db push --remote 명령을 사용하여 Astro Studio로 다시 푸시합니다. 이전 테이블은 삭제되고 이름이 변경된 새 테이블만 남습니다.

데이터 푸시

섹션 제목: 데이터 푸시
Studio 기능

시드 또는 데이터 마이그레이션을 위해 Studio 데이터베이스에 데이터를 푸시해야 할 수도 있습니다. 타입 안정성을 갖춘 쿼리를 작성하려면 astro:db 모듈을 사용하여 .ts 파일을 작성할 수 있습니다. 그런 다음 astro db execute <file-path> --remote 명령을 사용하여 Studio 데이터베이스에 대해 파일을 실행합니다.

다음 Comments는 astro db execute db/seed.ts --remote 명령을 사용하여 시드할 수 있습니다.

db/seed.ts
import { Comment } from 'astro:db';


export default async function () {
  await db.insert(Comment).values([
    { authorId: 1, body: 'Hope you like Astro DB!' },
    { authorId: 2, body: 'Enjoy!' },
  ])
}

전체 명령 목록은 CLI 참조를 확인하세요.

Astro Studio에 연결

섹션 제목: Astro Studio에 연결
Studio 기능

기본적으로 Astro는 dev 또는 build 명령을 실행할 때마다 로컬 데이터베이스 파일을 사용합니다. 각 명령이 실행될 때마다 테이블이 처음부터 다시 생성되고 개발 시드 데이터가 삽입됩니다.

호스팅된 Studio 데이터베이스에 연결하려면 --remote 플래그를 추가하면 됩니다. Studio 데이터베이스에 대한 읽기 및 쓰기 액세스 권한을 모두 가지려면 프로덕션 배포에 이 플래그를 사용하세요. 이렇게 하면 사용자 데이터를 입력받고 유지할 수 있습니다.

Terminal window
# 원격 연결 및 빌드
astro build --remote


# 원격 연결 및 개발
astro dev --remote

원격 연결을 사용하려면 Studio에 인증하기 위한 앱 토큰이 필요합니다. 토큰 생성 및 설정 지침을 보려면 Studio 대시보드를 방문하세요.

배포할 준비가 되면 Studio 연결 및 배포 가이드를 확인하세요.

Astro Studio에서 Turso로 마이그레이션

섹션 제목: Astro Studio에서 Turso로 마이그레이션
  1. Studio 대시보드에서 마이그레이션하려는 프로젝트로 이동합니다. settings 탭에서 “Export Database” 버튼을 사용해 데이터베이스 덤프를 다운로드합니다.
  2. 공식 지침에 따라 Turso CLI를 설치하고, Turso 계정의 가입 또는 로그인을 진행합니다.
  3. turso db create 명령을 사용하여 Turso에서 새 데이터베이스를 생성합니다.
    Terminal window
    turso db create [database-name]
  4. Turso CLI를 사용하여 데이터베이스 URL을 가져와서 환경 변수 ASTRO_DB_REMOTE_URL로 사용합니다.
    Terminal window
    turso db show [database-name]
    ASTRO_DB_REMOTE_URL=[your-database-url]
  5. 데이터베이스에 액세스할 수 있는 토큰을 생성하고 환경 변수 ASTRO_DB_APP_TOKEN으로 사용합니다.
    Terminal window
    turso db tokens create [database-name]
    ASTRO_DB_APP_TOKEN=[your-app-token]
  6. DB 스키마와 메타데이터를 새 Turso 데이터베이스로 푸시하세요.
    Terminal window
    astro db push --remote
  7. 1단계의 데이터베이스 덤프를 새 Turso DB로 가져옵니다.
    Terminal window
    turso db shell [database-name] < ./path/to/dump.sql
  8. 프로젝트가 새 데이터베이스에 연결되었음을 확인했으면 Astro Studio에서 프로젝트를 안전하게 삭제할 수 있습니다.

libSQL

섹션 제목: libSQL

Added in: @astrojs/db@0.14.0 New

Astro DB는 서버의 libSQL 원격 프로토콜을 노출하는 모든 플랫폼에서 모든 libSQL 서버에 연결하거나 자체 호스팅할 수 있습니다.

Astro DB를 libSQL 데이터베이스에 연결하려면 다음 환경 변수를 설정하세요:

  • ASTRO_DB_REMOTE_URL: libSQL 서버에 대한 연결 URL
  • ASTRO_DB_APP_TOKEN: libSQL 서버에 대한 인증 토큰

데이터베이스에 변경 사항을 배포하고 푸시하는 명령은 libSQL을 사용할 때 Astro Studio에서 호스팅하는 데이터베이스에 연결할 때와 동일합니다. 그러나 --remote 옵션이 있는 astro build 및 astro db push와 같은 명령을 실행할 때는 두 환경 변수를 모두 로컬로 설정해야 합니다.

libSQL 연결의 세부 정보 (예: 암호화 키, 복제, 동기화 간격)는 원격 연결 URL에서 쿼리 매개변수로 구성될 수 있습니다.

예를 들어 로컬 파일이 암호화된 libSQL 서버에 포함된 복제본으로 작동하도록 하려면 다음 환경 변수를 설정할 수 있습니다.

.env
ASTRO_DB_REMOTE_URL=file://local-copy.db?encryptionKey=your-encryption-key&syncInterval=60&syncUrl=libsql%3A%2F%2Fyour.server.io
ASTRO_DB_APP_TOKEN=token-to-your-remote-url

URL 스킴 및 호스트

섹션 제목: URL 스킴 및 호스트

libSQL은 원격 서버의 전송 프로토콜로 HTTP와 WebSockets을 모두 지원합니다. 또한 로컬 파일이나 인메모리 DB 사용도 지원합니다. 이러한 프로토콜은 연결 URL에서 다음 URL 스킴을 사용하여 구성할 수 있습니다:

  • memory: 인메모리 DB를 사용합니다. 이 경우 호스트는 비어 있어야 합니다.
  • file: 로컬 파일을 사용합니다. 호스트는 파일 경로입니다 (file:path/to/file.db).
  • libsql: 라이브러리에서 선호하는 프로토콜을 통해 원격 서버를 사용합니다 (버전에 따라 다를 수 있음). 호스트는 서버의 주소 (libsql://your.server.io)입니다.
  • http: HTTP를 통해 원격 서버를 사용합니다. 보안 연결을 사용하려면 https:를 사용할 수 있습니다. 호스트는 libsql:와 동일합니다.
  • ws: WebSockets을 통해 원격 서버를 사용합니다. wss:를 사용하여 보안 연결을 활성화할 수 있습니다. 호스트는 libsql:와 동일합니다.

encryptionKey

섹션 제목: encryptionKey

libSQL은 암호화된 데이터베이스를 기본적으로 지원합니다. 이 검색 매개변수를 전달하면 지정된 키를 사용하여 암호화를 활성화합니다:

.env
ASTRO_DB_REMOTE_URL=file:path/to/file.db?encryptionKey=your-encryption-key

syncUrl

섹션 제목: syncUrl

임베디드 복제본은 초고속 읽기를 위해 로컬 파일이나 메모리에 데이터베이스의 전체 동기화 복사본을 저장할 수 있는 libSQL 클라이언트의 기능입니다. 쓰기는 syncUrl에 정의된 원격 데이터베이스로 전송되어 로컬 복사본과 동기화됩니다.

이 속성을 사용하여 별도의 연결 URL을 전달하여 DB를 다른 데이터베이스의 임베디드 복제본으로 전환합니다. 이 속성은 file: 및 memory: 스킴에서만 사용해야 합니다. 매개변수는 URL로 인코딩되어야 합니다.

예를 들어 데이터베이스의 인메모리 임베디드 복제본을 libsql://your.server.io에 만들려면 연결 URL을 다음과 같이 설정할 수 있습니다.

.env
ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io

syncInterval

섹션 제목: syncInterval

임베디드 복제본 동기화 간격 (초)입니다. 기본적으로 시작 시와 쓰기 후에만 동기화됩니다.

이 속성은 syncUrl도 설정된 경우에만 사용됩니다. 예를 들어 인메모리 임베디드 복제본이 매분 동기화되도록 설정하려면 다음 환경 변수를 설정합니다:

.env
ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io&syncInterval=60

Astro DB 통합 구축

섹션 제목: Astro DB 통합 구축

Astro 통합은 추가 Astro DB 테이블 및 시드 데이터를 사용하여 사용자 프로젝트를 확장할 수 있습니다.

추가 Astro DB 구성 및 시드 파일을 등록하려면 astro:db:setup 후크에서 extendDb() 메서드를 사용하세요. defineDbIntegration() 도우미는 astro:db:setup 후크에 대한 TypeScript 지원 및 자동 완성 기능을 제공합니다.

my-integration/index.ts
import { defineDbIntegration } from '@astrojs/db/utils';


export default function MyIntegration() {
  return defineDbIntegration({
    name: 'my-astro-db-powered-integration',
    hooks: {
      'astro:db:setup': ({ extendDb }) => {
        extendDb({
          configEntrypoint: '@astronaut/my-package/config',
          seedEntrypoint: '@astronaut/my-package/seed',
        });
      },
      // 기타 통합 후크...
    },
  });
}

통합 config 및 seed 파일은 해당 사용자 정의 파일과 동일한 형식을 따릅니다.

타입 안정성을 갖춘 통합 작업

섹션 제목: 타입 안정성을 갖춘 통합 작업

통합 작업을 하는 동안, Astro에서 생성된 (astro:db에서 내보낸) 테이블 타입의 이점을 활용하지 못할 수도 있습니다. 완전한 타입 안정성을 위해 asDrizzleTable() 유틸리티를 사용하여 데이터베이스 작업에 사용할 수 있는 테이블 참조 객체를 생성하세요.

예를 들어, 다음 Pets 데이터베이스 테이블을 설정하는 통합이 있다고 가정해 보겠습니다.

my-integration/config.ts
import { defineDb, defineTable, column } from 'astro:db';


export const Pets = defineTable({
  columns: {
    name: column.text(),
    species: column.text(),
  },
});


export default defineDb({ tables: { Pets } });

시드 파일은 Pets를 가져오고 asDrizzleTable()을 사용하여 타입 검사를 통해 테이블에 행을 삽입할 수 있습니다.

my-integration/seed.ts
import { asDrizzleTable } from '@astrojs/db/utils';
import { db } from 'astro:db';
import { Pets } from './config';


export default async function() {
  const typeSafePets = asDrizzleTable('Pets', Pets);


  await db.insert(typeSafePets).values([
    { name: 'Palomita', species: 'cat' },
    { name: 'Pan', species: 'dog' },
  ]);
}

asDrizzleTable('Pets', Pets)에 의해 반환된 값은 import { Pets } from 'astro:db'와 동일하지만, Astro의 타입 생성을 실행할 수 없는 경우에도 사용할 수 있습니다. 데이터베이스에 쿼리하거나 삽입해야 하는 모든 통합 코드에서 이를 사용할 수 있습니다.

자체 호스팅 프로덕션 배포

섹션 제목: 자체 호스팅 프로덕션 배포

가상 사설 서버와 같은 자체 관리형 호스트에 사이트를 배포하는 경우 호스팅되는 데이터베이스에 연결하는 대신 Astro Studio에서 데이터베이스 파일을 사용하도록 선택할 수 있습니다.

위험을 감수하고 배포를 직접 관리할 수 있는 경우 Studio에 연결하는 대신 데이터베이스 파일을 사용할 수 있습니다.

빌드하는 동안 호스트 환경에서 .db 파일을 가리키는 경로로 ASTRO_DATABASE_FILE 환경 변수를 설정합니다.

Terminal window
ASTRO_DATABASE_FILE=/srv/files/database.db astro build

빌드는 정적으로 이 경로를 프로덕션 데이터베이스로 컴파일합니다. 서버를 배포하고 실행하면 프로덕션 호스트에 있는 이 경로의 파일에 연결됩니다.

또한 테이블 스키마 변경 사항 푸시 (“스키마 마이그레이션” 이라고도 함)는 이 환경 변수를 사용하여 수동으로 관리해야 합니다.

기여하기

여러분의 생각을 들려주세요!

GitHub Issue 생성

우리에게 가장 빨리 문제를 알려줄 수 있어요.

커뮤니티