Heroku Postgres データベースのインポートとエクスポート
最終更新日 2024年05月21日(火)
表面上、PGBackups は、Heroku Postgres データベースの定期バックアップを取得するための方法を提供します。ただし、その汎用アーキテクチャおよび標準の PostgreSQL ユーティリティの使用のため、これは外部の PostgreSQL データベースとの間のエクスポートやインポートを実行できる有効なツールにもなっています。
ローカルマシン上に Postgres インスタンスがある場合にインポート/エクスポートのダンプおよび復元方法を使用する代替法として、pg:push と pg:pull の CLI コマンドを使用したプロセスの自動化があります。
エクスポート
PGBackups では、ネイティブな pg_dump PostgreSQL ツールを使用してバックアップファイルを作成するため、他の PostgreSQL インストールへのエクスポートがきわめて簡単になります。結果のバックアップファイルでは pg_dump のカスタム形式オプションが使用されます。プレーンテキスト形式と比較して、カスタム形式オプションでは、はるかに小さいバックアップファイルが生成されます。
一般に、PGBackups は、適度な負荷がかかった最大 20 GB までのデータベースを対象にしています。より大規模なデータベースをバックアップするために必要な I/O、メモリ、CPU の競合は適度な負荷でもきわめて激しくなり、実行時間が長くなると、バックアップの取得を早い段階で終了させるエラーが発生する可能性が高くなります。20 GB より大きいデータベースについては、「Capturing Logical Backups on Larger Databases」(大規模データベースでの論理バックアップの取得) を参照してください。
PGBackups によるバックアップの取得とダウンロード
Heroku Postgres データベースからデータをエクスポートするには、バックアップを作成してダウンロードします。
$ heroku pg:backups:capture --app example-app
$ heroku pg:backups:download --app example-app
pg_dump による手動ダンプ
Heroku Postgres データベースの部分的なバックアップまたは非カスタム形式のバックアップが必要な場合、pg_dump を使用してバックアップを作成できます。
たとえば、Heroku Postgres データベースからプレーンテキストのダンプを作成するには、次のようにします。
$ pg_dump -Fp --no-acl --no-owner <DATABASE_CONNECTION_STRING > mydb.dump
必要に応じてサポートされる pg_dump オプション (--schema や --table など) を使用して、データベースの特定のスキーマまたはテーブルのダンプを作成します。サポートされるオプションについて詳しくは、PostgreSQL のドキュメントを参照してください。
ローカルデータベースへの復元
pg_restore ツールを使用して、ローカルデータベースにダンプをロードします。データベースのローカルコピーにすでにオブジェクトが存在する場合は、pg_restore を実行すると不整合が発生する可能性があります。
このプロセスにより通常、Heroku データベースとローカルデータベースの違いが原因で警告が表示されますが、これらは一般に無視しても問題ありません。
heroku_ext スキーマに関するエラーが表示された場合は、CREATE SCHEMA heroku_ext; を実行して、バックアップをリストアする前に、このスキーマをローカルで作成できます。
$ pg_restore --verbose --clean --no-acl --no-owner -h localhost -U myuser -d mydb latest.dump
古いバージョンの pg_restore を使用している場合は、pg_restore を実行しようとすると、pg_restore: [archiver] unsupported version (1.13) in file header などのエラーが表示されることがあります。使用している pg_restore のバージョンが最新であり、エクスポートされたデータベースのバージョンと互換性があることを確認してください。pg_restoreのバージョンは、pg_restore --version を実行することによって確認できます。
pg_restore でオプションで --jobs <number of jobs> フラグを使用すると、ダンプの復元を並列化できます。このオプションでは、カスタムおよびディレクトリアーカイブ形式のみがサポートされています。このオプションについての詳細は、Postgres のドキュメントを参照してください。
インポート
PGBackups は、他のソースから Heroku Postgres データベースにデータベースダンプをインポートするための便利なツールとして使用できます。
新しいアプリケーションの初期化の一部としてデータをインポートする場合は、インポートを実行する前に、まず Heroku でアプリを作成して設定する必要があります。
ダンプファイルの作成
オープンソースの pg_dump ツールを使用して、ローカルデータベースを圧縮された custom 形式でダンプします。
# set the password in an environment variable
export PGPASSWORD=mypassword # linux/mac
set PGPASSWORD=mypassword # windows
# create the database dump
$ pg_dump -Fc --no-acl --no-owner -h localhost -U myuser -d mydb -f mydb.dump
Heroku Postgres へのインポート
PG バックアップでダンプファイルにアクセスしてインポートするには、それを HTTP でアクセス可能な URL の場所にアップロードする必要があります。
pg:backups restore コマンドでは、テーブルやその他のデータベースオブジェクトのすべてが再作成の前に削除されます。
pg:backups:restore コマンドでは、指定されたバックアップにおいて圧縮された custom 形式が使用されることが想定されています。その他のバックアップ形式では復元エラーとなります。
Heroku PGBackups では、URL から直接アクセス可能なあらゆるバックアップファイルをダウンロードできますが、署名済みの URL で Amazon S3 を使用することをお勧めします。AWS コンソールを使用して、署名済みの URL を生成します。
$ aws s3 presign s3://your-bucket-address/your-object
pg:backups restore コマンドで、生ファイルの URL を使用します。
$ heroku pg:backups:restore '<SIGNED URL>' DATABASE_URL --app example-app
DATABASE_URL は、復元先のデータベースの HEROKU_POSTGRESQL_COLOR_URL を表します。データベースを復元するためのデータベース環境設定を指定する必要があります。
UNIX 系のオペレーティングシステムを使用している場合は、シェルを混乱させるアンパサンドなどの文字が含まれている可能性があるため、一時的な S3 URL の前後に一重引用符を使用するようにしてください。Windows を実行している場合は、二重引用符を使用する必要があります。
インポートプロセスが完了したら、ダンプファイルをその保存場所から削除します (不要な場合)。