데이터베이스 옵션

EmDash는 여러 데이터베이스 백엔드를 지원합니다. 배포 대상에 따라 선택하세요.

개요

Cloudflare D1

D1은 Cloudflare의 서버리스 SQLite 데이터베이스입니다. Cloudflare Workers에 배포할 때 사용하세요.

import { d1 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
		}),
	],
});

구성

설정

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "emdash-db"
    }
  ]
}

[[d1_databases]]
binding = "DB"
database_name = "emdash-db"

읽기 복제본

D1은 읽기 복제를 지원하여 전역 분산 사이트의 읽기 지연 시간을 줄입니다. 활성화되면 읽기 쿼리가 항상 기본 데이터베이스에 접근하는 대신 근처의 복제본으로 라우팅됩니다.

EmDash는 D1 Sessions API를 사용하여 이를 투명하게 관리합니다. session 옵션으로 활성화하세요:

import { d1 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			database: d1({
				binding: "DB",
				session: "auto",
			}),
		}),
	],
});

세션 모드

작동 방식

• 익명 방문자는 first-unconstrained를 얻습니다 — 읽기는 가장 낮은 지연 시간을 위해 가장 가까운 복제본으로 이동합니다. 익명 사용자는 쓰기를 하지 않으므로 일관성 보장이 필요하지 않습니다.
• 인증된 사용자(편집자, 작성자)는 북마크 기반 세션을 얻습니다. 쓰기 후 북마크 쿠키는 다음 요청이 최소한 해당 상태를 볼 수 있도록 보장합니다.
• 쓰기 요청(POST, PUT, DELETE)은 항상 기본 데이터베이스에서 시작됩니다.
• 빌드 시 쿼리(Astro 콘텐츠 컬렉션)는 세션을 완전히 우회하고 기본 데이터베이스를 직접 사용합니다.

libSQL

libSQL은 원격 연결을 지원하는 SQLite의 포크입니다. Cloudflare D1 없이 원격 데이터베이스가 필요한 경우 사용하세요.

import { libsql } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: libsql({
				url: process.env.LIBSQL_DATABASE_URL,
				authToken: process.env.LIBSQL_AUTH_TOKEN,
			}),
		}),
	],
});

구성

로컬 개발

개발 중에는 로컬 libSQL 파일을 사용하세요:

database: libsql({ url: "file:./data.db" });

PostgreSQL

PostgreSQL은 완전한 관계형 데이터베이스가 필요한 Node.js 배포를 지원합니다.

import { postgres } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: postgres({
				connectionString: process.env.DATABASE_URL,
			}),
		}),
	],
});

구성

연결 문자열 또는 개별 매개변수로 연결할 수 있습니다:

// 연결 문자열
database: postgres({
	connectionString: "postgres://user:password@localhost:5432/emdash",
});

// 개별 매개변수
database: postgres({
	host: "localhost",
	port: 5432,
	database: "emdash",
	user: "emdash",
	password: process.env.DB_PASSWORD,
	ssl: true,
});

연결 풀링

어댑터는 내부적으로 pg.Pool을 사용합니다. 배포에 따라 풀 크기를 조정하세요:

database: postgres({
	connectionString: process.env.DATABASE_URL,
	pool: { min: 2, max: 20 },
});

SQLite

better-sqlite3를 사용하는 SQLite는 Node.js 배포를 위한 가장 간단한 옵션입니다.

import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data.db" }),
		}),
	],
});

구성

파일 경로

url은 file:로 시작해야 합니다:

// 상대 경로
database: sqlite({ url: "file:./data/emdash.db" });

// 절대 경로
database: sqlite({ url: "file:/var/data/emdash.db" });

// 환경 변수에서
database: sqlite({ url: `file:${process.env.DATABASE_PATH}` });

마이그레이션

EmDash는 지원되는 모든 방언(D1, SQLite, libSQL, PostgreSQL)에 대해 첫 번째 요청 시 마이그레이션을 자동으로 실행합니다. 마이그레이션은 emdash 패키지와 함께 번들로 제공되며 빌드에 포함됩니다.

데이터베이스가 비어 있고(컬렉션 없음) 설정 마법사가 완료되지 않은 경우, EmDash는 첫 번째 부팅 시 시드 파일도 적용합니다. 시드는 .emdash/seed.json, package.json#emdash.seed의 경로 또는 seed/seed.json에서 읽습니다 — 가장 먼저 발견된 것 — 그리고 컴파일 시간에 빌드에 인라인됩니다. 없으면 내장 기본 시드가 사용됩니다. 기존 데이터베이스에 대한 후속 부팅은 콘텐츠를 그대로 둡니다.

환경 기반 구성

환경마다 다른 데이터베이스를 사용하세요:

import { sqlite, libsql, postgres } from "emdash/db";
import { d1 } from "@emdash-cms/cloudflare";

const database = import.meta.env.PROD ? d1({ binding: "DB" }) : sqlite({ url: "file:./data.db" });

export default defineConfig({
	integrations: [emdash({ database })],
});

빌드 모드 대신 환경 변수를 기반으로 선택할 수도 있습니다:

const database = process.env.DATABASE_URL
	? postgres({ connectionString: process.env.DATABASE_URL })
	: sqlite({ url: "file:./data.db" });