initdb — PostgreSQLのデータベースクラスタを新しく作成する
initdb
[option
...] [ --pgdata
| -D
] directory
initdb
はPostgreSQLのデータベースクラスタを新しく作成します。
データベースクラスタとは、1つのサーバインスタンスで管理されるデータベースの集合です。
データベースクラスタの作成には、データベースのデータを保存するディレクトリの作成、共有カタログテーブル(特定のデータベースではなく、クラスタ全体に所属するテーブル)の生成、そしてtemplate1
データベースとpostgres
データベースの作成といった作業が含まれます。
後から新しいデータベースを作成する際は、template1
データベースの全ての内容がコピーされます。
(つまり、template1
にインストールしたものすべてが、後に生成した各データベースに自動的にコピーされます。)
postgres
データベースは、ユーザ、ユーティリティ、サードパーティ製アプリケーションのデフォルトデータベースとしての使用を意図したものです。
initdb
は指定されたデータディレクトリを作成しようと試みますが、そのデータディレクトリの親ディレクトリの所有者がrootであるなど、権限がないことがあります。
このような場合、まず、空のデータディレクトリをrootで作成し、chown
を使ってそのディレクトリの所有権限をデータベースのユーザに変えてください。
次にsu
を使ってデータベースユーザとなり、initdb
を実行します。
initdb
は、サーバプロセスの所有者となるユーザによって実行されなければなりません。
initdb
によって作成されるファイルやディレクトリにサーバがアクセスできる必要があるからです。
サーバをrootとして実行することはできませんので、rootでinitdb
を実行してはいけません
(実際には、実行しようとしても拒否されます)。
セキュリティ上の理由から、デフォルトではinitdb
により作られた新しいクラスタはクラスタの所有者だけがアクセスできます。
--allow-group-access
により、クラスタの所有者と同じグループのユーザがクラスタ内のファイルを読めるようになります。
これは非特権ユーザとしてバックアップを実行するのに有用です。
initdb
は、データベースクラスタのデフォルトのロケールと文字セット符号化方式を初期化します。
文字セット符号化方式、照合順(LC_COLLATE
)および文字セットクラス(LC_CTYPE
、例えば、大文字、小文字、数字)は、データベース作成時、別々に設定することができます。
initdb
はtemplate1
データベース用のこれらの値を決定します。
この値が他のすべてのデータベースのデフォルトとして提供されます。
デフォルトの照合順や文字セットクラスを変更するためには、--lc-collate
および--lc-ctype
オプションを使用してください。
C
やPOSIX
以外の照合順には性能の劣化が伴います。
これらの理由によりinitdb
実行時にロケールを正しく選択することが重要です。
残りのロケール関連のものはサーバ起動時に変更することができます。
--locale
を使用して、照合順や文字セットクラスを含む、すべてのロケール関連のもののデフォルトを設定することも可能です。
SHOW ALL
を使用して、すべてのサーバのロケール値(lc_*
)を表示することができます。
詳細は23.1に記載しています。
デフォルトの符号化方式を変更するには、--encoding
オプションを使用します。
詳細は23.3に記載しています。
-A authmethod
--auth=authmethod
このオプションは、pg_hba.conf
にてローカルユーザ用に使用されるデフォルトの認証方法(host
行とlocal
行)を指定します。
initdb
は、非レプリケーションおよびレプリケーションの接続について、指定の認証方式を使うエントリをpg_hba.conf
に作成します。
システムのすべてのローカルユーザが信頼できるわけではない場合は、trust
を使用しないでください。
インストールを簡単にするためにtrust
がデフォルトになっています。
--auth-host=authmethod
このオプションはpg_hba.conf
にてTCP/IP接続経由のローカルユーザ用に使用される認証方法(host
行)を指定します。
--auth-local=authmethod
このオプションはpg_hba.conf
にてUnixドメインソケット接続経由のローカルユーザ用に使用される認証方法(local
行)を指定します。
-D directory
--pgdata=directory
このオプションは、データベースクラスタを格納すべきディレクトリを指定します。
initdb
が必要とする情報はこれだけですが、環境変数PGDATA
を設定しておけば、このオプションの指定を省略できます。
この方法は、後に同じ変数を使用してデータベースサーバ(postgres
)がデータベースディレクトリを参照できるので、便利です。
-E encoding
--encoding=encoding
テンプレートデータベースの符号化方式を選択します。
これが今後作成される全てのデータベースについてのデフォルト符号化方式となりますが、作成時に上書きすることもできます。
デフォルトは、ロケールから取得しますが、取得できなければSQL_ASCII
になります。
PostgreSQLサーバによってサポートされる文字セットについては23.3.1で説明します。
-g
--allow-group-access
クラスタの所有者と同じグループのユーザが、initdb
により作られたクラスタファイルすべてを読むことを許可します。
WindowsではPOSIX形式のグループパーミッションをサポートしませんので、このオプションは無視されます。
-k
--data-checksums
I/Oシステムによる破損検知を補助するために、データページにおいてチェックサムを使用します。 これがないと警告もされません。 チェックサムを有効にすると、認知できる程度の性能低下が発生する可能性があります。 設定した場合、すべてのデータベースにおいて、すべてのオブジェクトに対してチェックサムが計算されます。 チェックサムの失敗はすべてpg_stat_databaseビューで報告されます。
--locale=locale
データベースクラスタ用のデフォルトのロケールを設定します。
このオプションを指定しない場合は、initdb
を実行している環境のロケールが継承されます。
ロケールサポートについては23.1で説明します。
--lc-collate=locale
--lc-ctype=locale
--lc-messages=locale
--lc-monetary=locale
--lc-numeric=locale
--lc-time=locale
--locale
と似ていますが、指定したカテゴリのロケールのみを設定します。
--no-locale
--locale=C
と同じです。
-N
--no-sync
デフォルトではinitdb
はすべてのファイルが安全にディスクに書き出されるまで待機します。
このオプションを使うとinitdb
は待機せずに返るようになり、より高速になりますが、後でオペレーティングシステムがクラッシュした場合にデータディレクトリが破損状態になってしまう可能性があります。
通常、このオプションは試験用では有用ですが、実用のインストレーションを作成する際に使用すべきではありません。
--pwfile=filename
initdb
はデータベーススーパーユーザのパスワードをこのファイルから読み取ります。
このファイルの最初の行がパスワードとして解釈されます。
-S
--sync-only
すべてのデータベースファイルを安全にディスクに書き出し、終了します。 これは通常のinitdbの操作をまったく行いません。
-T config
--text-search-config=config
デフォルトの全文検索設定を設定します。 詳細についてはdefault_text_search_configを参照してください。
-U username
--username=username
データベースのスーパーユーザのユーザ名を選択します。
initdb
を実行している実効ユーザの名前がデフォルトです。
スーパーユーザの名前はあまり重要ではありませんが、慣習的に使われているpostgresを(オペレーティングシステムのユーザ名と異なっていても)使っても良いでしょう。
-W
--pwprompt
initdb
にデータベースのスーパーユーザ権限を与えるためのパスワード入力のプロンプトを表示させます。
パスワード認証を行うつもりがない場合は必要ありません。
このオプションを指定しても、パスワードの設定を行わない限りパスワード認証は行われません。
-X directory
--waldir=directory
このオプションは先行書き込みログの格納ディレクトリを指定します。
--wal-segsize=size
WALセグメントサイズをメガバイト単位で設定します。 これはWALログの個々のファイルの大きさです。 デフォルトの大きさは16メガバイトです。 値は1から1024の間の2の冪でなければなりません。 このオプションは初期化の際にのみ設定することができ、後で変更することはできません。
WALログのシッピングやアーカイブの粒度を制御するために、この大きさを調整することは有用でしょう。 また、大量のWALのあるデータベースでは、ディレクトリ当たりのWALファイルの数だけでパフォーマンスや管理の問題となり得ます。 WALファイルの大きさを増やせば、WALファイルの数は減るでしょう。
この他にも、使用頻度は下がりますが、下記のオプションが使用可能です。
-d
--debug
ブートストラップバックエンドからのデバッグ情報と、一般の利用者にはおそらく不要なその他の情報を出力します。
ブートストラップバックエンドとはinitdb
がカタログテーブルを作成する際に使用するプログラムです。
このオプションはうんざりするようなログを大量に出力します。
-L directory
データベースクラスタを初期化する際に、initdb
が参照すべき入力ファイルを指定します。
これは通常必要ありません。
明示的に指定する必要がある場合は、その時に指定するよう要求されます。
-n
--no-clean
デフォルトでは、initdb
を実行中にエラーが発生し、データベースクラスタを完成できなかった場合に、そのエラーが発生する前に作成された全てのファイルを削除します。
このオプションを指定すると、これらのファイルが削除しないで残されるので、デバッグの際にはとても便利です。
その他のオプションを以下に示します。
-V
--version
initdbのバージョンを表示し、終了します。
-?
--help
initdbのコマンドライン引数の使用方法を表示し、終了します。
PGDATA
データベースクラスタを保存するディレクトリを指定します。
-D
オプションを使用して上書きすることができます。
PG_COLOR
診断メッセージで色を使うかどうかを指定します。
可能な値はalways
、auto
、never
です。
TZ
作成されるデータベースクラスタのデフォルトの時間帯を指定します。 値は完全な時間帯の名前で指定することが望ましいです(8.5.3参照)。
また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(33.14を参照してください)。
initdb
はpg_ctl initdb
経由でも呼び出すことができます。