SQLite 컬럼 타입

공식 **SQLite 문서**에 따르면, SQLite 데이터베이스에 저장되거나 데이터베이스 엔진에 의해 조작되는 각 값은 다음의 저장 클래스 중 하나를 가집니다: NULL, INTEGER, REAL, TEXT, BLOB.

Drizzle은 이들을 모두 기본적으로 지원하지만, 충분하지 않다면 **커스텀 타입**을 자유롭게 생성할 수 있습니다.

important

이 문서의 모든 예제는 데이터베이스 컬럼명 별칭을 사용하지 않으며, 컬럼명은 TypeScript 키로부터 생성됩니다.

원한다면 컬럼명에 데이터베이스 별칭을 사용할 수 있으며, casing 파라미터를 사용하여 Drizzle의 매핑 전략을 정의할 수도 있습니다.

자세한 내용은 여기에서 확인하세요.

Integer

부호 있는 정수로, 값의 크기에 따라 0, 1, 2, 3, 4, 6, 또는 8 바이트로 저장됩니다.

import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	id: integer()
});

// integer 모드를 number, boolean, timestamp, timestamp_ms로 커스터마이징할 수 있습니다
integer({ mode: 'number' })
integer({ mode: 'boolean' })
integer({ mode: 'timestamp_ms' })
integer({ mode: 'timestamp' }) // Date

CREATE TABLE `table` (
	`id` integer
);

// integer를 자동 증가 기본 키로 만들기
integer({ mode: 'number' }).primaryKey({ autoIncrement: true })

CREATE TABLE `table` (
	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL
);

Real

부동 소수점 값으로, 8바이트 IEEE 부동 소수점 숫자로 저장됩니다.

import { real, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	real: real()
});

CREATE TABLE `table` (
	`real` real
);

Text

텍스트 문자열로, 데이터베이스 인코딩(UTF-8, UTF-16BE 또는 UTF-16LE)을 사용하여 저장됩니다.

{ enum: ["value1", "value2"] } 설정을 정의하여 insert 및 select 타입을 추론할 수 있으며, 런타임 값은 검사하지 않습니다.

import { text, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	text: text()
});

// text: "value1" | "value2" | null 로 추론됩니다
text({ enum: ["value1", "value2"] })
text({ mode: 'json' })
text({ mode: 'json' }).$type<{ foo: string }>()

CREATE TABLE `table` (
	`text` text
);

Blob

데이터의 blob으로, 입력된 그대로 정확히 저장됩니다.

blob('', { mode: 'json' }) 대신 text('', { mode: 'json' })을 사용하는 것을 권장합니다. JSON 함수를 지원하기 때문입니다:

현재 모든 JSON 함수는 인수가 BLOB인 경우 오류를 발생시킵니다. BLOB은 JSON의 바이너리 인코딩을 저장할 향후 개선 사항을 위해 예약되어 있기 때문입니다.

자세한 내용은 **https://www.sqlite.org/json1.html**을 참조하세요.

import { blob, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	blob: blob()
});

blob()
blob({ mode: 'buffer' })
blob({ mode: 'bigint' })

blob({ mode: 'json' })
blob({ mode: 'json' }).$type<{ foo: string }>()

CREATE TABLE `table` (
	`blob` blob
);

blob 추론을 위해 .$type<..>()을 지정할 수 있으며, 런타임 값은 검사하지 않습니다. 이는 기본값, 삽입 및 조회 스키마에 대한 컴파일 타임 보호를 제공합니다.

// { foo: string }로 추론됩니다
json: blob({ mode: 'json' }).$type<{ foo: string }>();

// string[]로 추론됩니다
json: blob({ mode: 'json' }).$type<string[]>();

// 컴파일되지 않습니다
json: blob({ mode: 'json' }).$type<string[]>().default({});

Boolean

SQLite는 네이티브 boolean 데이터 타입이 없지만, integer 컬럼을 boolean 모드로 지정할 수 있습니다. 이를 통해 코드에서 boolean 값을 사용할 수 있으며, Drizzle은 이를 데이터베이스에 0과 1의 정수 값으로 저장합니다.

import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	id: integer({ mode: 'boolean' })
});

CREATE TABLE `table` (
	`id` integer
);

Bigint

SQLite에는 bigint 데이터 타입이 없기 때문에, Drizzle은 blob 컬럼에 대한 특별한 bigint 모드를 제공합니다. 이 모드를 사용하면 코드에서 BigInt 인스턴스로 작업할 수 있으며, Drizzle은 이를 데이터베이스에 blob 값으로 저장합니다.

import { blob, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	id: blob({ mode: 'bigint' })
});

CREATE TABLE `table` (
	`id` blob
);

Numeric

import { blob, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	numeric: numeric(),
	numericNum: numeric({ mode: 'number' }),
	numericBig: numeric({ mode: 'bigint' }),
});

CREATE TABLE `table` (
	`numeric` numeric,
	`numericNum` numeric,
	`numericBig` numeric
);

---

데이터 타입 커스터마이징

모든 컬럼 빌더는 .$type() 메서드를 가지고 있으며, 이를 통해 컬럼의 데이터 타입을 커스터마이징할 수 있습니다. 예를 들어, unknown 또는 브랜드 타입과 함께 사용할 때 유용합니다.

type UserId = number & { __brand: 'user_id' };
type Data = {
	foo: string;
	bar: number;
};

const users = sqliteTable('users', {
  id: integer().$type<UserId>().primaryKey(),
  jsonField: blob().$type<Data>(),
});

Not null

NOT NULL 제약조건은 연결된 컬럼이 NULL 값을 포함할 수 없음을 지정합니다.

const table = sqliteTable('table', { 
	numInt: integer().notNull() 
});

CREATE TABLE table (
	`numInt` integer NOT NULL
);

기본값

DEFAULT 절은 INSERT 수행 시 사용자가 명시적으로 값을 제공하지 않을 경우 컬럼에 사용할 기본값을 지정합니다. 컬럼 정의에 명시적인 DEFAULT 절이 없으면, 컬럼의 기본값은 NULL입니다.

명시적인 DEFAULT 절은 기본값이 NULL, 문자열 상수, blob 상수, 부호 있는 숫자 또는 괄호로 묶인 상수 표현식임을 지정할 수 있습니다.

import { sql } from "drizzle-orm";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
	int1: integer().default(42),
	int2: integer().default(sql`(abs(42))`)
});

CREATE TABLE `table` (
	`int1` integer DEFAULT 42,
	`int2` integer DEFAULT (abs(42))
);

기본값은 특수 대소문자 구분 없는 키워드 CURRENT_TIME, CURRENT_DATE 또는 CURRENT_TIMESTAMP 중 하나일 수도 있습니다.

import { sql } from "drizzle-orm";
import { text, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable("table", {
  time: text().default(sql`(CURRENT_TIME)`),
  date: text().default(sql`(CURRENT_DATE)`),
  timestamp: text().default(sql`(CURRENT_TIMESTAMP)`),
});

CREATE TABLE `table` (
	`time` text DEFAULT (CURRENT_TIME),
	`date` text DEFAULT (CURRENT_DATE),
	`timestamp` text DEFAULT (CURRENT_TIMESTAMP)
);

동일한 함수의 다른 별칭인 $default() 또는 $defaultFn()을 사용할 때, 런타임에 기본값을 생성하고 모든 삽입 쿼리에서 이 값을 사용할 수 있습니다. 이러한 함수는 uuid, cuid, cuid2 등 다양한 구현을 활용하는 데 도움이 됩니다.

참고: 이 값은 drizzle-kit 동작에 영향을 주지 않으며, drizzle-orm에서 런타임에만 사용됩니다.

import { text, sqliteTable } from "drizzle-orm/sqlite-core";
import { createId } from '@paralleldrive/cuid2';

const table = sqliteTable('table', {
	id: text().$defaultFn(() => createId()),
});

동일한 함수의 다른 별칭인 $onUpdate() 또는 $onUpdateFn()을 사용할 때, 런타임에 기본값을 생성하고 모든 업데이트 쿼리에서 이 값을 사용할 수 있습니다.

컬럼에 동적 업데이트 값을 추가합니다. 행이 업데이트될 때 함수가 호출되며, 값이 제공되지 않은 경우 반환된 값이 컬럼 값으로 사용됩니다. 기본값(또는 $defaultFn)이 제공되지 않은 경우, 행이 삽입될 때도 함수가 호출되고 반환된 값이 컬럼 값으로 사용됩니다.

참고: 이 값은 drizzle-kit 동작에 영향을 주지 않으며, drizzle-orm에서 런타임에만 사용됩니다.

import { text, sqliteTable } from "drizzle-orm/sqlite-core";

const table = sqliteTable('table', {
    alwaysNull: text().$type<string | null>().$onUpdate(() => null),
});

PostgreSQL

MySQL

SQLite

SingleStore

MSSQL

CockroachDB