SQLite

SQLite 数据源连接器将 Prisma ORM 连接到 SQLite 数据库文件。这些文件始终以 .db 结尾（例如：dev.db）。

默认情况下，SQLite 连接器包含一个负责连接到数据库的数据库驱动程序。您可以使用 驱动程序适配器（预览版）通过 Prisma Client 使用 JavaScript 数据库驱动程序连接到您的数据库。

示例

要连接到 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 的内置驱动程序）一起使用。您可以通过使用 驱动程序适配器 来实现。

对于 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 })

将 SQLite 与 Bun 一起使用

当在 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 连接器将 数据模型 中的 标量类型 映射到原生列类型，如下所示：

或者，请参阅 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 并在数据库中存储无效的枚举条目，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',
}