SQLite

SQLite 資料來源連接器將 Prisma ORM 連接到 SQLite 資料庫檔案。這些檔案的副檔名通常為 .db（例如：dev.db）。

預設情況下，SQLite 連接器包含一個負責連接資料庫的資料庫驅動程式。您可以透過 驅動程式轉接器 (Driver adapter)（預覽功能），使用 JavaScript 資料庫驅動程式從 Prisma Client 連接您的資料庫。

範例

若要連接至 SQLite 資料庫檔案，您需要在 Prisma schema 中設定一個 datasource 區塊。

schema.prisma

datasource db {
  provider = "sqlite"
}

datasource 區塊指定了 sqlite 資料來源連接器。

在 Prisma ORM 7 中，資料庫連線 URL 設定於 prisma.config.ts。

prisma.config.ts

import { defineConfig } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: 'file:./dev.db',
  },
})

連接 URL 總是以 file: 為前綴，後面接著指向 SQLite 資料庫檔案的檔案路徑。在此範例中，檔案位於相同目錄下，名稱為 dev.db。

使用 better-sqlite3 驅動程式

自 v5.4.0 起，您可以將 Prisma ORM 與來自 JavaScript 生態系統的資料庫驅動程式搭配使用（而不是使用 Prisma ORM 內建的驅動程式）。您可以透過使用 驅動程式轉接器 (driver adapter) 來達成此目的。

對於 SQLite 而言，better-sqlite3 是 JavaScript 生態系統中最受歡迎的驅動程式之一。

本節說明如何將其與 Prisma ORM 及 @prisma/adapter-better-sqlite3 驅動程式轉接器一起使用。

1. 安裝相依套件

首先，安裝 Prisma ORM 的 better-sqlite3 驅動程式轉接器：

npm install @prisma/adapter-better-sqlite3

2. 使用驅動程式轉接器實例化 Prisma Client

現在，當您實例化 Prisma Client 時，您需要將 Prisma ORM 驅動程式轉接器的實例傳遞給 PrismaClient 建構函式。

import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from './generated/prisma';

const adapter = new PrismaBetterSqlite3({
  url: "file:./prisma/dev.db"
})
const prisma = new PrismaClient({ adapter })

在 Bun 中使用 SQLite

在 Bun 上執行 Prisma Client 時，請使用 @prisma/adapter-libsql 驅動程式轉接器。Bun 不支援 better-sqlite3 所依賴的原生 SQLite 驅動程式（請參閱 node:sqlite 參考文件）。請實例化轉接器並將其傳遞給 PrismaClient。

import { PrismaClient } from '../prisma/generated/client';
import { PrismaLibSql } from '@prisma/adapter-libsql';

const adapter = new PrismaLibSql({
  url: process.env.DATABASE_URL ?? '',
});

const prisma = new PrismaClient({ adapter });

export default prisma;

3. 設定時間戳記格式以保持向後相容性

在使用 SQLite 的驅動程式轉接器時，您可以透過 timestampFormat 選項設定 DateTime 值在資料庫中的儲存方式。

預設情況下，驅動程式轉接器會將 DateTime 值儲存為 **ISO 8601 字串**，這是 SQLite 最方便的格式，因為 SQLite 的日期/時間函數預設期望使用 ISO 8601。

然而，如果您需要與 Prisma ORM 原生 SQLite 驅動程式 **100% 向後相容**（例如，在遷移現有資料庫時），您應該使用 unixepoch-ms 格式，該格式將時間戳記儲存為自 Unix 紀元以來的毫秒數。

import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
import { PrismaClient } from './generated/prisma';

const adapter = new PrismaBetterSqlite3({
  url: "file:./prisma/dev.db"
}, {
  timestampFormat: 'unixepoch-ms'
})
const prisma = new PrismaClient({ adapter })

資訊

timestampFormat 選項適用於 @prisma/adapter-better-sqlite3 和 @prisma/adapter-libsql 驅動程式轉接器。

何時使用各個格式

• ISO 8601（預設）：適合新專案，且與 SQLite 內建的日期/時間函數整合良好。
• unixepoch-ms：從 Prisma ORM 原生 SQLite 驅動程式遷移時必須使用，以保持與現有時間戳記資料的相容性。

SQLite 與 Prisma schema 之間的類型對應

SQLite 連接器將 資料模型 中的 純量類型 (scalar types) 對應至原生欄位類型，如下所示：

或者，請參閱 Prisma schema 參考資料，查看按 Prisma ORM 類型整理的類型對應。

從 Prisma ORM 到 SQLite 的原生類型對應

Prisma ORM	SQLite
String	TEXT
Boolean	布林值 (BOOLEAN)
Int	整數 (INTEGER)
BigInt	整數 (INTEGER)
Float	實數 (REAL)
Decimal	DECIMAL
DateTime	NUMERIC
Json	JSONB
Bytes	BLOB
Enum	TEXT

注意

SQLite 沒有專門的布林類型。雖然此表顯示 BOOLEAN，但欄位會被分配 **NUMERIC 相似性 (affinity)**（儲存 0 代表 false，1 代表 true）。了解更多。

警告

在 SQLite 中使用 enum 欄位時，請注意以下事項：

• 沒有資料庫層級的正確性強制執行：如果您繞過 Prisma ORM 並在資料庫中儲存無效的列舉 (enum) 條目，當 Prisma Client 讀取該條目時將會在執行期間失敗。
• 沒有遷移層級的正確性強制執行：類似於 MongoDB，架構變更後可能會出現錯誤的資料（因為資料庫不會檢查列舉）。

大數值的捨入誤差

SQLite 是一個弱型別資料庫。如果您的 Schema 有一個 Int 類型的欄位，Prisma ORM 會防止您插入大於整數範圍的值。然而，沒有機制能阻止資料庫直接接受更大的數字。這些手動插入的大數字在查詢時會導致捨入誤差。

為了避免此問題，Prisma ORM 4.0.0 及更高版本會在從資料庫讀取資料時檢查數字，確認它們是否符合整數範圍。如果數字不符，Prisma ORM 將會拋出 P2023 錯誤，例如：

Inconsistent column data: Conversion failed:
Value 9223372036854775807 does not fit in an INT column,
try migrating the 'int' column type to BIGINT

連接詳情

連接 URL

SQLite 連接器的連接 URL 指向檔案系統中的檔案，並在 prisma.config.ts 中進行設定。例如，以下兩個路徑是等效的，因為 .db 檔案位於同一個目錄中：

prisma.config.ts

datasource: {
  url: 'file:./dev.db',
}

與以下路徑相同：

prisma.config.ts

datasource: {
  url: 'file:dev.db',
}

您也可以指定來自根目錄或檔案系統中任何其他位置的檔案。

prisma.config.ts

datasource: {
  url: 'file:/Users/janedoe/dev.db',
}