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

PostgreSQL拡張機能

このページでは、PostgreSQL拡張機能について説明し、Prismaスキーマで拡張機能を表現する方法、データベース内の既存の拡張機能をイントロスペクトする方法、Prisma Migrateを使用してデータベースに拡張機能の変更を適用する方法について説明します。

注意

スキーマ内でのPostgreSQL拡張機能の宣言のサポートは、Prismaバージョン4.5.0以降のPostgreSQLコネクタでのみプレビューで利用可能です。

PostgreSQL拡張機能とは？​

PostgreSQLでは、拡張機能として知られるパッケージをインストールおよびアクティブ化することで、データベース機能を拡張できます。たとえば、citext拡張機能は、大文字と小文字を区別しない文字列データ型を追加します。citextのような一部の拡張機能はPostgreSQLから直接提供されますが、その他の拡張機能は外部で開発されています。拡張機能の詳細については、PostgreSQLドキュメントを参照してください。

拡張機能を使用するには、まずデータベースサーバーのローカルファイルシステムにインストールする必要があります。次に、拡張機能をアクティブ化し、新しい機能を追加するスクリプトファイルを実行する必要があります。

情報

PostgreSQLのドキュメントでは、「インストール」という用語を、ここでいう拡張機能のアクティブ化を指すために使用していることに注意してください。これらが2つの異なるステップであることを明確にするために、ここでは異なる用語を使用しています。

PrismaのpostgresqlExtensionsプレビュー機能を使用すると、PostgreSQL拡張機能をPrismaスキーマで表現できます。特定の拡張機能が現在Prismaでサポートされていない機能を追加する可能性があることに注意してください。たとえば、拡張機能がPrismaでサポートされていない型やインデックスを追加する場合があります。この機能はケースバイケースで実装する必要があり、このプレビュー機能では提供されません。

postgresqlExtensionsプレビュー機能を有効にする方法​

PrismaスキーマでPostgreSQL拡張機能を表現することは、現在プレビュー機能です。postgresqlExtensionsプレビュー機能を有効にするには、PrismaスキーマのgeneratorブロックのpreviewFeaturesフィールドにpostgresqlExtensions機能フラグを追加する必要があります。

schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["postgresqlExtensions"]
}

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

PrismaスキーマでPostgreSQL拡張機能を表現する方法​

PrismaスキーマでPostgreSQL拡張機能を表現するには、schema.prismaファイルのdatasourceブロックにextensionsフィールドを、必要な拡張機能の配列とともに追加します。たとえば、以下のスキーマは、hstore、pg_trgm、およびpostgis拡張機能をリストしています。

schema.prisma
datasource db {
  provider   = "postgresql"
  url        = env("DATABASE_URL")
  extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
}

Prismaスキーマ内の各拡張機能名には、以下のオプション引数を指定できます。

  • schema: 拡張機能のオブジェクトをアクティブ化するスキーマの名前。この引数が指定されていない場合、現在のデフォルトのオブジェクト作成スキーマが使用されます。
  • version: アクティブ化する拡張機能のバージョン。この引数が指定されていない場合、拡張機能の制御ファイルに指定された値が使用されます。
  • map: 拡張機能のデータベース名。この引数が指定されていない場合、Prismaスキーマ内の拡張機能の名前はデータベース名と一致する必要があります。

上記の例では、hstore拡張機能はmyHstoreSchemaスキーマを使用し、postgis拡張機能はバージョン2.1でアクティブ化されています。

map引数は、アクティブ化したいPostgreSQL拡張機能の名前がPrismaスキーマで有効な識別子でない場合に役立ちます。たとえば、uuid-ossp PostgreSQL拡張機能の名前は、ハイフンが含まれているため無効な識別子です。以下の例では、この拡張機能はPrismaスキーマで有効な名前uuidOsspにマッピングされています。

schema.prisma
datasource db {
  provider   = "postgresql"
  url        = env("DATABASE_URL")
  extensions = [uuidOssp(map: "uuid-ossp")]
}

PostgreSQL拡張機能をイントロスペクトする方法​

データベースで現在アクティブ化されているPostgreSQL拡張機能をイントロスペクトし、関連する拡張機能をPrismaスキーマに追加するには、npx prisma db pullを実行します。

多くのPostgreSQL拡張機能はPrismaスキーマに関連しません。たとえば、一部の拡張機能はスキーマを変更しないデータベース管理タスクを目的としています。これらの拡張機能がすべて含まれると、拡張機能のリストは非常に長くなります。これを避けるため、Prismaは既知の関連する拡張機能の許可リストを維持しています。現在の許可リストは以下のとおりです。

  • citext: 大文字と小文字を区別しない文字列型citextを提供します。
  • pgcrypto: 普遍的に一意な識別子（UUID v4）を生成するgen_random_uuid()のような暗号化関数を提供します。
  • uuid-ossp: 普遍的に一意な識別子（UUID v4）を生成するuuid_generate_v4()のような関数を提供します。
  • postgis: GIS（地理情報システム）サポートを追加します。

注: PostgreSQL v13以降、gen_random_uuid()は拡張機能なしで普遍的に一意な識別子（UUIDs v4）を生成するために使用できます。

拡張機能は以下のようにイントロスペクトされます。

  • 初回イントロスペクト時、許可リストにあるすべてのデータベース拡張機能がPrismaスキーマに追加されます。
  • 再イントロスペクト時、挙動は拡張機能が許可リストにあるかどうかによって異なります。
    • 許可リストにある拡張機能
      • データベースには存在するがPrismaスキーマにはない場合、Prismaスキーマに追加されます。
      • Prismaスキーマにもデータベースにも存在する場合、Prismaスキーマに維持されます。
      • Prismaスキーマには存在するがデータベースにはない場合、Prismaスキーマから削除されます。
    • 許可リストにない拡張機能
      • Prismaスキーマにもデータベースにも存在する場合、Prismaスキーマに維持されます。
      • Prismaスキーマには存在するがデータベースにはない場合、Prismaスキーマから削除されます。

イントロスペクト時にversion引数はPrismaスキーマに追加されません。

PostgreSQL拡張機能を移行する方法​

Prismaスキーマ内のPostgreSQL拡張機能のリストを更新し、変更をPrisma Migrateでデータベースに適用できます。

これは、モデルやフィールドなど、Prismaスキーマの他の要素の移行と同様に機能します。ただし、以下の違いがあります。

  • スキーマから拡張機能を削除しても、データベースでまだアクティブ化されている場合、Prisma Migrateはデータベースからそれを非アクティブ化しません。
  • 新しい拡張機能をスキーマに追加した場合、それがデータベースにすでに存在しない場合にのみアクティブ化されます。これは、拡張機能が手動で作成されている可能性があるためです。
  • 拡張機能の定義からversionまたはschema引数を削除しても、以降のマイグレーションでデータベース内の拡張機能に影響はありません。
© . All rights reserved.