MySQL/MariaDB

MySQL 資料來源連接器將 Prisma ORM 連接到 MySQL 或 MariaDB 資料庫伺服器。

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

範例

要連接到 MySQL 資料庫伺服器，您需要在 Prisma Schema 中設定 datasource 區塊。

schema.prisma

datasource db {
  provider = "mysql"
}

datasource 區塊指定了 mysql 資料來源連接器，該連接器同時適用於 MySQL 和 MariaDB。

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

prisma.config.ts

import { defineConfig, env } from 'prisma/config'
import 'dotenv/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

此設定使用環境變數來提供資料庫連接 URL。

使用 `mariadb` 驅動程式

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

對於 MySQL 和 MariaDB，mariadb 是 JavaScript 生態系統中最受歡迎的驅動程式之一。

本節說明如何將其與 Prisma ORM 及 @prisma/adapter-mariadb 驅動程式轉接器搭配使用。

1. 安裝相依套件

首先，安裝 Prisma ORM 用於 mariadb 的驅動程式轉接器。

npm install @prisma/adapter-mariadb

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

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

import 'dotenv/config'
import { PrismaMariaDb } from '@prisma/adapter-mariadb'
import { PrismaClient } from '../generated/prisma/client'

const adapter = new PrismaMariaDb({
  host: "localhost",
  port: 3306,
  connectionLimit: 5
})
const prisma = new PrismaClient({ adapter })

連接詳情

連接 URL

以下是 MySQL 連接 URL 所需元件的總覽。

Structure of the MySQL connection URL

基礎 URL 和路徑

以下是 base URL 和 path 結構的範例，使用大寫字母作為預留位置。

mysql://USER:PASSWORD@HOST:PORT/DATABASE

下列元件構成了資料庫的 base URL，這些元件為必填項。

名稱	佔位符	描述
主機	`HOST`	資料庫伺服器的 IP 位址或網域名稱，例如 `localhost`。
連接埠	`PORT`	資料庫伺服器運行的連接埠，例如 `5432`（預設為 `3306`；若使用 Unix socket 則無須連接埠）。
User	`使用者 (USER)`	您的資料庫使用者名稱，例如 `janedoe`
密碼	`PASSWORD`	您的資料庫使用者密碼
資料庫	`DATABASE`	您想要使用的資料庫名稱，例如 `mydb`。

資訊

您必須對特殊字元進行百分比編碼 (percentage-encode)。

引數

連接 URL 也可以接受參數。以下是上述範例的相同結構，並使用大寫字母作為三個參數的預留位置。

mysql://USER:PASSWORD@HOST:PORT/DATABASE?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE

可以使用以下參數：

參數名稱	必填	預設值	描述
`connection_limit`	否	`num_cpus * 2 + 1`	連線池 (connection pool) 的最大大小（Prisma ORM v6 及更早版本）
`connect_timeout`	否	`5`	等待開啟新連接的最大秒數；`0` 表示沒有逾時限制。
`pool_timeout`	否	`10`	等待從連接池取得新連接的最大秒數；`0` 表示沒有逾時限制。
`sslcert`	否		伺服器憑證的路徑。憑證路徑會相對於 `./prisma` 資料夾進行解析。
`sslidentity`	否		PKCS12 憑證的路徑。
`sslpassword`	否		用於保護 PKCS12 檔案的密碼。
`sslaccept`	否	`accept_invalid_certs`	設定是否檢查憑證中遺失的值。可選值：`accept_invalid_certs`, `strict`。
`socket`	否		指向包含連接所用 socket 的目錄。
`socket_timeout`	否		等待單一查詢終止的秒數。

例如，如果您想將連接池大小設為 5 並將查詢逾時時間設為 3 秒，可以使用以下參數。

mysql://USER:PASSWORD@HOST:PORT/DATABASE?connection_limit=5&socket_timeout=3

Prisma ORM v7 連線池

在 Prisma ORM v7 中，驅動程式轉接器是關聯式資料庫的預設設定。連接池由您提供的 Node.js 驅動程式（如 mariadb）處理，而非透過 Prisma 的連接 URL 參數。請參閱連接池指南以了解 v7 的預設值與設定。

設定 SSL 連接

如果您的資料庫伺服器使用 SSL，可以在連接 URL 中加入各種參數。以下是可用參數的總覽：

sslcert=<PATH>：伺服器憑證路徑。這是資料庫伺服器用來簽署客戶端憑證的根憑證。如果您的系統受信任憑證存放區中不存在該憑證，則必須提供此項。對於 Google Cloud，這通常是 server-ca.pem。憑證路徑會相對於 ./prisma 資料夾進行解析。
sslidentity=<PATH>：由客戶端憑證與金鑰建立的 PKCS12 憑證資料庫路徑。這是在 PKCS12 格式下的 SSL 識別檔案，您將使用客戶端金鑰與憑證來產生它。它將這兩個檔案結合為一個檔案，並透過密碼進行保護（請參閱下一個參數）。您可以使用 openssl 命令來建立此檔案。
```
openssl pkcs12 -export -out client-identity.p12 -inkey client-key.pem -in client-cert.pem
```
sslpassword=<PASSWORD>：用於保護 PKCS12 檔案的密碼。上一步中列出的 openssl 命令在建立 PKCS12 檔案時會要求設定密碼，您必須在此處提供完全相同的密碼。
sslaccept=(strict|accept_invalid_certs):
- strict：憑證中任何遺失的值都會導致錯誤。對於 Google Cloud，特別是當資料庫沒有網域名稱時，憑證可能會缺少網域/IP 位址，從而導致連接錯誤。
- accept_invalid_certs (預設)：繞過此檢查。請注意此設定帶來的安全後果。

您的資料庫連接 URL 看起來會類似這樣：

mysql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=client-identity.p12&sslpassword=mypassword&sslcert=rootca.cert

透過 Sockets 連接

要透過 socket 連接到 MySQL/MariaDB 資料庫，您必須將 socket 欄位作為 查詢參數 (query parameter) 加入連接 URL（而非將其設定為 URI 的 host 部分）。此參數的值必須指向包含 socket 的目錄，例如在 Ubuntu 或 Debian 預設安裝的 MySQL/MariaDB 上：mysql://USER:PASSWORD@HOST/DATABASE?socket=/run/mysqld/mysqld.sock

請注意，localhost 是必填項，但該值本身會被忽略，可以填寫任何內容。

注意：您可以在此 GitHub issue 中找到更多背景資訊。

MySQL 到 Prisma Schema 的類型映射

MySQL 連接器將 Prisma ORM 資料模型中的純量類型 (scalar types) 映射至原生的欄位類型，如下所示：

或者，請參閱 Prisma Schema 參考以獲取按 Prisma ORM 類型分類的類型映射。

Prisma ORM 到 MySQL 的原生類型映射

Prisma ORM	MySQL	註解
`String`	`VARCHAR(191)`
`Boolean`	`BOOLEAN`	在 MySQL 中，`BOOLEAN` 是 `TINYINT(1)` 的同義詞。
`Int`	`INT`
`BigInt`	`BIGINT`
`Float`	`DOUBLE`
`Decimal`	`DECIMAL(65,30)`
`DateTime`	`DATETIME(3)`	目前，Prisma ORM 不支援 MySQL 中的零日期 (`0000-00-00`, `00:00:00`)。
`Json`	`JSON`	僅在 MySQL 5.7+ 中支援。
`Bytes`	`LONGBLOB`

Prisma ORM 到 MariaDB 的原生類型映射

Prisma ORM	MariaDB	註解
`String`	`VARCHAR(191)`
`Boolean`	`BOOLEAN`	在 MariaDB 中，`BOOLEAN` 是 `TINYINT(1)` 的同義詞。
`Int`	`INT`
`BigInt`	`BIGINT`
`Float`	`DOUBLE`
`Decimal`	`DECIMAL(65,30)`
`DateTime`	`DATETIME(3)`
`Json`	`LONGTEXT`	請參閱 https://mariadb.com/kb/en/json-data-type/
`Bytes`	`LONGBLOB`

原生類型映射

對 MySQL 資料庫進行內省 (introspection) 時，資料庫類型會根據下表映射至 Prisma ORM：

MySQL	Prisma ORM	支援	原生資料庫類型屬性	註解
`serial`	`BigInt`	✔️	`@db.UnsignedBigInt @default(autoincrement())`
`bigint`	`BigInt`	✔️	`@db.BigInt`
`bigint unsigned`	`BigInt`	✔️	`@db.UnsignedBigInt`
`bit`	`Bytes`	✔️	`@db.Bit(x)`	`bit(1)` 映射至 `Boolean`，所有其他 `bit(x)` 映射至 `Bytes`。
`boolean` \| `tinyint(1)`	`Boolean`	✔️	`@db.TinyInt(1)`
`varbinary`	`Bytes`	✔️	`@db.VarBinary`
`longblob`	`Bytes`	✔️	`@db.LongBlob`
`tinyblob`	`Bytes`	✔️	`@db.TinyBlob`
`mediumblob`	`Bytes`	✔️	`@db.MediumBlob`
`blob`	`Bytes`	✔️	`@db.Blob`
`binary`	`Bytes`	✔️	`@db.Binary`
`date`	`DateTime`	✔️	`@db.Date`
`datetime`	`DateTime`	✔️	`@db.DateTime`
`timestamp`	`DateTime`	✔️	`@db.TimeStamp`
`time`	`DateTime`	✔️	`@db.Time`
`decimal(a,b)`	`Decimal`	✔️	`@db.Decimal(x,y)`
`numeric(a,b)`	`Decimal`	✔️	`@db.Decimal(x,y)`
`enum`	`Enum`	✔️	不適用
`float`	`Float`	✔️	`@db.Float`
`double`	`Float`	✔️	`@db.Double`
`smallint`	`Int`	✔️	`@db.SmallInt`
`smallint unsigned`	`Int`	✔️	`@db.UnsignedSmallInt`
`mediumint`	`Int`	✔️	`@db.MediumInt`
`mediumint unsigned`	`Int`	✔️	`@db.UnsignedMediumInt`
`int`	`Int`	✔️	`@db.Int`
`int unsigned`	`Int`	✔️	`@db.UnsignedInt`
`tinyint`	`Int`	✔️	`@db.TinyInt(x)`	`tinyint(1)` 映射至 `Boolean`，所有其他 `tinyint(x)` 映射至 `Int`。
`tinyint unsigned`	`Int`	✔️	`@db.UnsignedTinyInt(x)`	`tinyint(1) unsigned` 不會映射至 `Boolean`。
`year`	`Int`	✔️	`@db.Year`
`json`	`Json`	✔️	`@db.Json`	僅在 MySQL 5.7+ 中支援。
`char`	`String`	✔️	`@db.Char(x)`
`varchar`	`String`	✔️	`@db.VarChar(x)`
`tinytext`	`String`	✔️	`@db.TinyText`
`text`	`String`	✔️	`@db.Text`
`mediumtext`	`String`	✔️	`@db.MediumText`
`longtext`	`String`	✔️	`@db.LongText`
`set`	`Unsupported`	尚未支援
`geometry`	`Unsupported`	尚未支援
`point`	`Unsupported`	尚未支援
`linestring`	`Unsupported`	尚未支援
`polygon (多邊形)`	`Unsupported`	尚未支援
`multipoint`	`Unsupported`	尚未支援
`multilinestring`	`Unsupported`	尚未支援
`multipolygon`	`Unsupported`	尚未支援
`geometrycollection`	`Unsupported`	尚未支援

內省 (Introspection) 會將尚未支援的原生資料庫類型添加為 Unsupported 欄位

schema.prisma

model Device {
  id   Int                   @id @default(autoincrement())
  name String
  data Unsupported("circle")
}

引擎 (Engine)

如果您使用的 MySQL 版本預設引擎為 MyISAM，建立資料表時必須指定 ENGINE = InnoDB;。如果您內省了使用不同引擎的資料庫，Prisma Schema 中的關係將不會被建立（或者若關係已存在，則會遺失）。

權限

全新安裝的 MySQL/MariaDB 預設只有一個 root 資料庫使用者。請勿在 Prisma 設定中使用 root 使用者，請為每個應用程式建立專屬的資料庫與使用者。在大多數 Linux 主機（如 Ubuntu）上，您可以以 Linux root 使用者身分直接執行（該使用者自動擁有資料庫 root 存取權）：

mysql -e "CREATE DATABASE IF NOT EXISTS $DB_PRISMA;"
mysql -e "GRANT ALL PRIVILEGES ON $DB_PRISMA.* TO $DB_USER@'%' IDENTIFIED BY '$DB_PASSWORD';"

上述權限足以執行 prisma db pull 與 prisma db push 命令。若要執行 prisma migrate 命令，則需要授予額外的權限。

mysql -e "GRANT CREATE, DROP, REFERENCES, ALTER ON *.* TO $DB_USER@'%';"

範例​

使用 mariadb 驅動程式​

1. 安裝相依套件​

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

連接詳情​

連接 URL​

基礎 URL 和路徑​

引數​

設定 SSL 連接​

透過 Sockets 連接​

MySQL 到 Prisma Schema 的類型映射​

Prisma ORM 到 MySQL 的原生類型映射​

Prisma ORM 到 MariaDB 的原生類型映射​

原生類型映射​

引擎 (Engine)​

權限​

範例