Microsoft SQL Server

Microsoft SQL Serverデータソースコネクタは、Prisma ORMをMicrosoft SQL Serverデータベースサーバーに接続します。

例

Microsoft SQL Serverデータベースに接続するには、Prismaスキーマにdatasourceブロックを設定する必要があります。

schema.prisma

datasource db {
  provider = "sqlserver"
  url      = env("DATABASE_URL")
}

datasourceブロックに渡されるフィールドは以下の通りです。

• provider: sqlserverデータソースコネクタを指定します。
• url: Microsoft SQL Serverデータベースの接続URLを指定します。この場合、接続URLを提供するために環境変数が使用されます。

node-mssqlドライバーの使用

v5.4.0以降、Prisma ORMをJavaScriptエコシステムからのデータベースドライバー（Prisma ORMの組み込みドライバーを使用する代わりに）と組み合わせて使用できます。これはドライバーアダプターを使用することで可能です。

SQLiteの場合、node-mssqlはJavaScriptエコシステムで最も人気のあるドライバーの一つです。

このセクションでは、Prisma ORMと@prisma/adapter-mssqlドライバーアダプターでそれを使用する方法を説明します。

1. driverAdaptersプレビュー機能フラグを有効にする

現在ドライバーアダプターはプレビュー段階であるため、Prismaスキーマのdatasourceブロックでその機能フラグを有効にする必要があります。

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "sqlserver"
  url      = env("DATABASE_URL")
}

スキーマに機能フラグを追加したら、Prisma Clientを再生成します。

npx prisma generate

2. 依存関係をインストールする

次に、node-mssql用のPrisma ORMのドライバーアダプターをインストールします。

npm install @prisma/adapter-mssql

3. ドライバーアダプターを使用してPrisma Clientをインスタンス化する

最後に、Prisma Clientをインスタンス化する際に、Prisma ORMのドライバーアダプターのインスタンスをPrismaClientコンストラクターに渡す必要があります。

import { PrismaMssql } from '@prisma/adapter-mssql'
import { PrismaClient } from '@prisma/client'

const config = {
  server: 'localhost',
  port: 1433,
  database: 'mydb',
  user: 'sa',
  password: 'mypassword',
  options: {
    encrypt: true, // Use this if you're on Windows Azure
    trustServerCertificate: true, // Use this if you're using self-signed certificates
  },
}

const adapter = new PrismaMssql(config)
const prisma = new PrismaClient({ adapter })

接続の詳細

Microsoft SQL Serverデータベースに接続するために使用される接続URLは、JDBC標準に準拠しています。

次の例では、TLS暗号化接続が有効なSQL認証（ユーザー名とパスワード）を使用しています。

sqlserver://HOST[:PORT];database=DATABASE;user=USER;password=PASSWORD;encrypt=true

警告

注: 接続文字列で次の文字を使用する場合は、それらをエスケープする必要があります。

:\=;/[]{}  # these are characters that will need to be escaped

これらの文字をエスケープするには、特殊文字を含む値の周囲に中括弧{}を使用します。例：

sqlserver://HOST[:PORT];database=DATABASE;user={MyServer/MyUser};password={ThisIsA:SecurePassword;};encrypt=true

引数

引数名	必須	デフォルト	コメント
database initial catalog	いいえ	master	接続するデータベース。
username user uid userid	いいえ - コメントを参照		SQL Serverログイン（例: sa）または、integratedSecurityがtrueに設定されている場合の有効なWindows (Active Directory) ユーザー名（Windowsのみ）。
password pwd	いいえ - コメントを参照		SQL Serverログイン用パスワード、または、integratedSecurityがtrueに設定されている場合のWindows (Active Directory) ユーザー名用パスワード（Windowsのみ）。
encrypt	いいえ	true	常にTLSを使用するか、ログイン手順のみに使用するかを設定します。可能な値: true (常に使用)、false (ログイン資格情報のみ)。
integratedSecurity	いいえ		Windows認証（統合セキュリティ）を有効にします。可能な値: true、false、yes、no。trueまたはyesに設定され、usernameおよびpasswordが存在する場合、ログインはWindows Active Directory経由で実行されます。ログインの詳細が個別の引数で指定されていない場合、現在ログインしているWindowsユーザーがサーバーへのログインに使用されます。
connectionLimit	いいえ	num_cpus * 2 + 1	接続プールの最大サイズ
connectTimeout	いいえ	5	新しい接続を待機する最大秒数
schema	いいえ	dbo	スキーマ名がデフォルトでない場合、すべてのクエリにプレフィックスとして追加されます。
loginTimeout connectTimeout connectionTimeout	いいえ		ログインが成功するまで待機する秒数。
socketTimeout	いいえ		各クエリが成功するまで待機する秒数。
isolationLevel	いいえ		トランザクション分離レベルを設定します。
poolTimeout	いいえ	10	プールから新しい接続を待機する最大秒数。すべての接続が使用中の場合、データベースは指定された時間待機した後にPoolTimeoutエラーを返します。
ApplicationName アプリケーション名 （大文字小文字を区別しない）	いいえ		接続のアプリケーション名を設定します。バージョン2.28.0以降。
trustServerCertificate	いいえ	false	サーバー証明書を信頼するかどうかを設定します。
trustServerCertificateCA	いいえ		サーバー証明書を認証するためにシステム証明書の代わりに使用する証明機関ファイルへのパス。pem、crt、またはder形式である必要があります。trustServerCertificateパラメータと同時に使用することはできません。

統合セキュリティの使用（Windowsのみ）

次の例では、現在ログインしているWindowsユーザーを使用してMicrosoft SQL Serverにログインします。

sqlserver://:1433;database=sample;integratedSecurity=true;trustServerCertificate=true;

次の例では、特定のActive Directoryユーザーを使用してMicrosoft SQL Serverにログインします。

sqlserver://:1433;database=sample;integratedSecurity=true;username=prisma;password=aBcD1234;trustServerCertificate=true;

名前付きインスタンスへの接続

次の例では、統合セキュリティを使用してMicrosoft SQL Serverの名前付きインスタンス (mycomputer\sql2019) に接続します。

sqlserver://mycomputer\sql2019;database=sample;integratedSecurity=true;trustServerCertificate=true;

Microsoft SQL ServerからPrismaスキーマへの型マッピング

Prisma ORMの型で整理された型マッピングについては、Prismaスキーマのリファレンスドキュメントを参照してください。

サポートされているバージョン

サポートされているデータベースを参照してください。

制限事項と既知の問題

Prisma Migrateの注意点

Prisma Migrateは2.13.0以降でサポートされており、以下の注意点があります。

データベーススキーマ名

SQL Serverには、PostgreSQLでおなじみのSET search_pathコマンドに相当するものがありません。これは、マイグレーションを作成する際に、本番データベースで使用されているものと同じスキーマ名を接続URLで定義する必要があることを意味します。ほとんどのユーザーにとって、これはdbo（デフォルト値）です。ただし、本番データベースが別のスキーマ名を使用している場合、すべてのマイグレーションSQLを手動で編集して本番を反映させるか、マイグレーションを作成する前に接続URLを変更する（例: schema=name）必要があります。

循環参照

循環参照は、各モデルが別のモデルを参照して閉じたループを作成する場合に、モデル間で発生する可能性があります。Microsoft SQL Serverデータベースを使用する場合、関連における参照アクションがNoAction以外に設定されていると、Prisma ORMは検証エラーを表示します。

詳細については、SQL Serverにおける参照アクションの特別ルールを参照してください。

破壊的変更

特定のマイグレーションは、予想よりも多くの変更を引き起こす可能性があります。例えば：

• autoincrement()の追加または削除。これはカラムを変更するだけでは達成できず、テーブル（すべての制約、インデックス、外部キーを含む）を再作成し、テーブル間ですべてのデータを移動する必要があります。
• さらに、テーブルからすべてのカラムを削除することはできません（PostgreSQLやMySQLでは可能）。マイグレーションですべてのテーブルカラムを再作成する必要がある場合、テーブルも再作成されます。

共有デフォルト値はサポートされていません

場合によっては、ユーザーはデフォルト値を共有オブジェクトとして定義したいことがあります。

default_objects.sql

CREATE DEFAULT catcat AS 'musti';

CREATE TABLE cats (
    id INT IDENTITY PRIMARY KEY,
    name NVARCHAR(1000)
);

sp_bindefault 'catcat', 'dbo.cats.name';

ストアドプロシージャsp_bindefaultを使用すると、デフォルト値catcatを複数のテーブルで使用できます。Prisma ORMがデフォルト値を管理する方法はテーブルごとです。

default_per_table.sql

CREATE TABLE cats (
    id INT IDENTITY PRIMARY KEY,
    name NVARCHAR(1000) CONSTRAINT DF_cat_name DEFAULT 'musti'
);

最後の例は、イントロスペクションすると、次のモデルになります。

schema.prisma

model cats {
  id   Int     @id @default(autoincrement())
  name String? @default("musti")
}

そして最初のものはデフォルト値がイントロスペクトされません。

schema.prisma

model cats {
  id   Int     @id @default(autoincrement())
  name String?
}

Prisma Migrateを共有デフォルトオブジェクトとともに使用する場合、それらへの変更はSQLで手動で行う必要があります。

データモデルの制限事項

UNIQUE制約とフィルターされたインデックスを持つカラムを外部キーとして使用できない

Microsoft SQL Serverは、UNIQUE制約を持つカラムに1つのNULL値のみを許可します。例：

• ユーザーテーブルにlicense_numberという名前のカラムがある
• license_numberフィールドにはUNIQUE制約がある
• license_numberフィールドは1つのNULL値のみを許可する

この問題を回避する標準的な方法は、NULL値を除外するフィルター付きユニークインデックスを作成することです。これにより、複数のNULL値を挿入できます。データベースにインデックスを作成しない場合、Prisma Clientでカラムに複数のnull値を挿入しようとするとエラーが発生します。

しかし、インデックスを作成すると、データベース内でlicense_numberを外部キーとして（または対応するPrismaスキーマで関連スカラーフィールドとして）使用できなくなります。

生クエリの考慮事項

String @db.VarChar(n)フィールド / VARCHAR(N)カラムを持つ生クエリ

生クエリのStringクエリパラメータは、常にSQL ServerにNVARCHAR(4000)（Stringの長さが4000以下の場合）またはNVARCHAR(MAX)としてエンコードされます。StringクエリパラメータをString @db.VarChar(N)/VARCHAR(N)型のカラムと比較すると、SQL Serverで暗黙的な変換が発生し、インデックスパフォーマンスに影響を与え、高いCPU使用率につながる可能性があります。

例を以下に示します。

model user {
  id Int @id
  name String @db.VarChar(40)
}

このクエリは影響を受けます。

await prisma.$queryRaw`SELECT * FROM user WHERE name = ${"John"}`

この問題を避けるため、生クエリでは常にStringクエリパラメータをVARCHAR(N)に手動でキャストすることをお勧めします。

await prisma.$queryRaw`SELECT * FROM user WHERE name = CAST(${"John"} AS VARCHAR(40))`

これにより、SQL Serverはクラスター化インデックススキャンではなく、クラスター化インデックスシークを実行できます。