メインコンテンツにスキップ

Microsoft SQL Server

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

例​

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

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

datasource ブロックに渡されるフィールドは次のとおりです

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

接続の詳細​

Microsoft SQL Serverデータベースへの接続に使用される接続 URL は、JDBC 標準 に従います。

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

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

注意：接続文字列で次のいずれかの文字を使用している場合、それらをエスケープする必要があります。

:\=;/[]{}  # 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いいえtrueTLS を常に使用するか、ログイン手順のみに使用するかを設定します。可能な値：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://localhost:1433;database=sample;integratedSecurity=true;trustServerCertificate=true;

次の例では、特定のアクティブディレクトリユーザーを使用して Microsoft SQL Server にログインします

sqlserver://localhost: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 schema間の型マッピング​

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

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

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

制限事項と既知の問題​

Prisma Migrate の注意点​

Prisma Migrate は 2.13.0 以降でサポートされています。ただし、次の注意点があります

データベーススキーマ名​

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

循環参照​

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

詳細については、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 制約 を持つ列に NULL 値を 1 つだけ許可します。例：

  • ユーザーのテーブルには、license_number という名前の列があります
  • license_number フィールドには UNIQUE 制約があります
  • license_number フィールドは 1 つ の NULL 値のみを許可します

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

ただし、インデックスを作成すると、データベースで license_number を外部キーとして (または対応する Prisma Schema でリレーションスカラーフィールドとして) 使用することが不可能になります

生クエリに関する考慮事項​

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 はクラスター化インデックススキャンではなく、クラスター化インデックスシークを実行できます。