Prisma ORM 環境変数と設定の管理

環境変数とは、マシンローカル環境に保存される文字列データのキーと値のペアです。詳細については、環境変数リファレンスドキュメントを参照してください。

通常、変数の名前は大文字で、その後に等号、そして変数の値が続きます。

MY_VALUE=prisma

環境変数は、プロセスが実行されている環境に属します。どのプログラムもこれらの環境変数を読み取り、作成できます。これらは、簡単な情報を保存するための安価で効果的な方法です。

ヒント

Prisma ORM v6.4.0 では、prisma.config.ts ファイルを Early Access としてリリースしました。このファイルを使用すると、環境変数と設定をより柔軟な方法で管理できます。

詳細についてはリファレンスをご覧ください。また、GitHubディスカッションでフィードバックを共有することを忘れないでください！

Prisma ORMが環境変数を使用する方法

Prisma ORMは常にシステムの環境から環境変数を読み取ります。

prisma init でプロジェクトに Prisma ORM を初期化すると、connection url を環境変数として設定するための便利な .env ファイルが作成されます。Prisma CLI または Prisma Client を使用すると、.env ファイルの内容とそこで定義された変数が process.env オブジェクトに追加され、Prisma ORM はそこで読み取って使用できます。

.env ファイルの使用

警告

.env ファイルをバージョン管理にコミットしないでください!

Prisma CLI は、次の場所で .env ファイルを順番に探します。

1. プロジェクトのルートフォルダー (./.env) 内
2. --schema 引数で指定されたスキーマと同じフォルダーから
3. package.json の "prisma": {"schema": "/path/to/schema.prisma"} から取得されたスキーマと同じフォルダーから
4. ./prisma フォルダーから

.env ファイルがステップ 1 にある場合でも、追加の競合する .env 変数がステップ 2〜4 にある場合、CLI はエラーをスローします。たとえば、2 つの異なる .env ファイルで DATABASE_URL 変数を指定すると、次のエラーが表示されます。

Error: There is a conflict between env vars in .env and prisma/.env
Conflicting env vars:
  DATABASE_URL

We suggest to move the contents of prisma/.env to .env to consolidate your env vars.

次の表は、Prisma CLI が .env ファイルを探す場所を示しています。

コマンド	スキーマの場所	チェックされる .env ファイルの場所（順序付き）
prisma [コマンド]	./prisma/schema.prisma	./.env ./prisma/.env
prisma [command] --schema=./a/b/schema.prisma	./a/b/schema.prisma	./.env ./a/b/.env ./prisma/.env
prisma [コマンド]	"prisma": {"schema": "/path/to/schema.prisma"}	./.env ./path/to/schema/.env ./prisma/.env
prisma [コマンド]	スキーマなし（たとえば、空のディレクトリで prisma db pull を実行する場合）	./.env ./prisma/.env

その .env ファイルで定義された環境変数は、Prisma CLI コマンドを実行すると自動的にロードされます。

情報

複数の .env ファイルを使用したいですか？アプリケーションで複数の .env ファイルを設定して使用する方法については、複数の .env ファイルの使用を参照してください。

環境変数が2か所で定義されている場合に何が起こるかについては、dotenv のドキュメントの説明を参照してください。

.env ファイルを使用した変数の展開

.env ファイルに保存された変数は、dotenv-expandで指定された形式を使用して展開できます。

./.env

DATABASE_URL=postgresql://test:test@localhost:5432/test
DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=public

さらに、.env ファイルの外部で設定されている環境変数を展開で使用できます。たとえば、Heroku などの PaaS で設定されているデータベース URL などです。

# environment variable already set in the environment of the system
export DATABASE_URL=postgresql://test:test@localhost:5432/test

./.env

DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=foo

これにより、環境変数 DATABASE_URL_WITH_SCHEMA が値 postgresql://test:test@localhost:5432/test?schema=foo で Prisma ORM で使用できるようになります。

コードで環境変数を使用する

実行時に環境変数を評価する場合は、アプリケーションコードで手動でロードする必要があります（たとえば、dotenvを使用するなど）。

import * as dotenv from 'dotenv'

dotenv.config() // Load the environment variables
console.log(`The connection URL is ${process.env.DATABASE_URL}`)

環境変数のカスタムファイル名を使用している場合は、そのファイル名を使用するように dotenv を構成できます。

import * as dotenv from 'dotenv'

var envFile = path.resolve(join(__dirname, "myenv.env"))
dotenv.config({path: envFile}) // Load the environment variables
console.log(`The connection URL is ${process.env.DATABASE_URL}`)

複数の環境ファイル間で変数を展開する必要がある場合は、dotenv-expandをさらに使用できます。

import * as dotenv from 'dotenv'
const dotenvExpand = require('dotenv-expand')

var envFile = path.resolve(join(__dirname, "myenv.env"))
var mySqlEnv = dotenv.config({path: envFile})
dotenvExpand.expand(mySqlEnv)

複数の .env ファイルを使用している場合は、実行している環境に応じて、プロジェクトのコードで環境ファイルを参照できます。

import { config } from 'dotenv'

const envFile = process.env.NODE_ENV === 'development' ? '.env.development' : '.env.production'
config({ path: envFile })

環境変数の手動設定

Prisma ORM は環境変数を探すときにシステムの環境から読み取るため、.env の使用を完全にスキップして、ローカルシステムで手動で作成することができます。

情報

次の例では、データベース接続 URL によく使用される DATABASE_URL 環境変数の設定を使用します。

Mac/Linux システムでの環境変数の手動設定

Unix マシン (Mac/Linux) のターミナルから、キーと値のペアとして変数をエクスポートします。

export DATABASE_URL=postgresql://test:test@localhost:5432/test?schema=public

次に、printenv を使用して正常に設定されたことを確認します。

printenv DATABASE_URL

表示CLI結果

postgresql://test:test@localhost:5432/test?schema=public

Windows システムでの環境変数の手動設定

次の例は、コマンドプロンプト (cmd.exe) と PowerShell の両方を使用して（現在のユーザーの）環境変数を設定する方法を示しています。どちらを使用するかはお好みで選択してください。

コマンドプロンプト

set DATABASE_URL="postgresql://test:test@localhost:5432/test?schema=public"

PowerShell

[Environment]::SetEnvironmentVariable("DATABASE_URL", "postgresql://test:test@localhost:5432/test?schema=public")

次に、正常に設定されたことを確認します。

コマンドプロンプト

set DATABASE_URL

PowerShell

Get-ChildItem Env:DATABASE_URL

複数の .env ファイルの使用

単一の .env ファイル内に各環境への異なる接続 URL を保存すると、本番データベースが削除されるリスクがあります。

1つの解決策は、それぞれ異なる環境を表す複数の .env ファイルを用意することです。実際には、環境ごとにファイルを作成することを意味します。

• .env.development
• .env.sample

次に、dotenv-cliのようなパッケージを使用すると、作業している環境に適切な接続 URL をロードできます。

情報

ここでは、アプリケーションの開発中に使用する専用の開発データベースがあることを前提としています。

1. .env ファイルの名前を .env.development に変更します。

.env.development

DATABASE_URL="postgresql://prisma:prisma@localhost:5433/dev"

2. 新しい .env.sample ファイルを作成し、データベース名を sample （または任意の名前）に変更します。

.env.sample

DATABASE_URL="postgresql://prisma:prisma@localhost:5433/sample"

3. dotenv-cliをインストールします。

Prisma ORM と Jest が使用する .env ファイルを認識できるようにするために、package.json スクリプトを変更して、dotenv パッケージを含めて呼び出し、実行しているコマンドと実行したい環境に応じて使用するファイルを指定します。

情報

テストと移行を実行する最上位スクリプトには、その前に dotenv コマンドが必要です。これにより、.env.sample からの環境変数が Jest を含むすべてのコマンドに確実に渡されます。

異なる環境での移行の実行

dotenv-cliパッケージを使用して、移行を実行するときに Prisma ORM が使用する環境ファイルを指定できます。

以下のスクリプトは、dotenv-cli を使用して、.env.sample 環境ファイル（DATABASE_URL 接続文字列を保持）を Prisma ORM 移行スクリプトに渡します。

移行スクリプト

package.json

  "scripts": {
    "migrate:postgres": "dotenv -e .env.sample -- npx prisma migrate deploy",
  },

異なる環境でのテストの実行

テストを実行するときは、Prisma Client をモックすることをお勧めします。そうすることで、Jest にテストを実行するときに使用する環境を指示する必要があります。

デフォルトでは、Prisma Client はプロジェクトのルートにあるデフォルトの .env ファイルで指定された環境を使用します。

テストデータベースを指定するために別の .env.sample ファイルを作成した場合、この環境を Jest に渡す必要があります。

以下のスクリプトは、dotenv-cli を使用して、.env.sample 環境ファイル（DATABASE_URL 接続文字列を保持）を Jest に渡します。

package.json

  "scripts": {
    "test": "dotenv -e .env.sample -- jest -i"
  },