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

PostgreSQL拡張機能

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

warning

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

PostgreSQL拡張機能とは？​

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

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

info

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-osspPostgreSQL拡張機能の名前は、ハイフンが含まれているため、有効な識別子ではありません。次の例では、拡張機能は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：Universally Unique Identifier（UUID v4）を生成するためのgen_random_uuid()などの暗号化機能を提供します
  • uuid-ossp：Universally Unique Identifier（UUID v4）を生成するためのuuid_generate_v4()などの機能を提供します
  • postgis：GIS（地理情報システム）のサポートを追加します

注：PostgreSQL v13以降、Universally Unique Identifier（UUID v4）を生成するために拡張機能なしでgen_random_uuid()を使用できます。

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

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

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

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

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

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

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