The functions described in this section are used to control and monitor a <productname>PostgreSQL</productname> installation. 本節で説明する関数は、PostgreSQLインストレーションの制御と監視を行うために使用されます。
<xref linkend="functions-admin-set-table"/> shows the functions available to query and alter run-time configuration parameters. 表 9.89は、実行時設定パラメータの問い合わせや変更に使用できる関数を示しています。
表9.89 構成設定関数
Function 関数 Description 説明 Example(s) 例 |
|---|
Returns the current value of the
setting <parameter>setting_name</parameter>. If there is no such
setting, <function>current_setting</function> throws an error
unless <parameter>missing_ok</parameter> is supplied and
is <literal>true</literal> (in which case NULL is returned).
This function corresponds to
the <acronym>SQL</acronym> command <xref linkend="sql-show"/>.
現在の
|
Sets the parameter <parameter>setting_name</parameter>
to <parameter>new_value</parameter>, and returns that value.
If <parameter>is_local</parameter> is <literal>true</literal>, the new
value will only apply during the current transaction. If you want the
new value to apply for the rest of the current session,
use <literal>false</literal> instead. This function corresponds to
the SQL command <xref linkend="sql-set"/>.
|
The functions shown in <xref
linkend="functions-admin-signal-table"/> send control signals to
other server processes. Use of these functions is restricted to
superusers by default but access may be granted to others using
<command>GRANT</command>, with noted exceptions.
表 9.90に示す関数は、制御用シグナルを他のサーバプロセスに送信します。
これらの関数の使用は、デフォルトでスーパーユーザのみに制限されていますが、注記された例外を除き、GRANTを使用して他のユーザにアクセスを許可できます。
Each of these functions returns <literal>true</literal> if
the signal was successfully sent and <literal>false</literal>
if sending the signal failed.
これらのそれぞれの関数はシグナルの送付が成功の場合trueを返し、シグナルの送付に失敗したときにはfalseを返します。
表9.90 サーバシグナル送信関数
Function 関数 Description 説明 |
|---|
Cancels the current query of the session whose backend process has the
specified process ID. This is also allowed if the
calling role is a member of the role whose backend is being canceled or
the calling role has privileges of <literal>pg_signal_backend</literal>,
however only superusers can cancel superuser backends.
指定したプロセスIDを持つバックエンドプロセスの現在のセッションの問い合わせを取り消します。
呼び出し側のロールがキャンセルされるバックエンドのロールのメンバーであるか、 |
Requests to log the memory contexts of the backend with the
specified process ID. This function can send the request to
backends and auxiliary processes except logger. These memory contexts
will be logged at
<literal>LOG</literal> message level. They will appear in
the server log based on the log configuration set
(see <xref linkend="runtime-config-logging"/> for more information),
but will not be sent to the client regardless of
<xref linkend="guc-client-min-messages"/>.
指定プロセスIDのバックエンドのメモリコンテキストを記録することを要求します。
この関数はバックエンドとロガー以外の外部プロセスに要求を送ることができます。
メモリコンテキストは |
|
Causes all processes of the <productname>PostgreSQL</productname>
server to reload their configuration files. (This is initiated by
sending a <systemitem>SIGHUP</systemitem> signal to the postmaster
process, which in turn sends <systemitem>SIGHUP</systemitem> to each
of its children.) You can use the
<link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link>,
<link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link> and
<link linkend="view-pg-hba-file-rules"><structname>pg_ident_file_mappings</structname></link> views
to check the configuration files for possible errors, before reloading.
PostgreSQLのすべてのサーバプロセスに構成ファイルの再読み込みをさせます。
（これはSIGHUPシグナルをpostmasterプロセスに送ることによって始まり、postmasterは続いてSIGHUPを子に送ります。）
再ロードする前に、設定ファイルにエラーの可能性があるかどうかをチェックするために |
Signals the log-file manager to switch to a new output file immediately. This works only when the built-in log collector is running, since otherwise there is no log-file manager subprocess. ログファイルマネージャにシグナルを送って新しいファイルに直ちに切り替えさせます。 これは組み込みのログ収集機構が実行中のみ動作します。でないとログマネージャサブプロセスが存在しないからです。 |
Terminates the session whose backend process has the
specified process ID. This is also allowed if the calling role
is a member of the role whose backend is being terminated or the
calling role has privileges of <literal>pg_signal_backend</literal>,
however only superusers can terminate superuser backends.
バックエンドが指定したプロセスIDを持つセッションを終了させます。
呼び出し側のロールが終了されるバックエンドのロールのメンバーであるか、
If <parameter>timeout</parameter> is not specified or zero, this
function returns <literal>true</literal> whether the process actually
terminates or not, indicating only that the sending of the signal was
successful. If the <parameter>timeout</parameter> is specified (in
milliseconds) and greater than zero, the function waits until the
process is actually terminated or until the given time has passed. If
the process is terminated, the function
returns <literal>true</literal>. On timeout, a warning is emitted and
<literal>false</literal> is returned.
|
<function>pg_cancel_backend</function> and <function>pg_terminate_backend</function>
send signals (<systemitem>SIGINT</systemitem> or <systemitem>SIGTERM</systemitem>
respectively) to backend processes identified by process ID.
The process ID of an active backend can be found from
the <structfield>pid</structfield> column of the
<structname>pg_stat_activity</structname> view, or by listing the
<command>postgres</command> processes on the server (using
<application>ps</application> on Unix or the <application>Task
Manager</application> on <productname>Windows</productname>).
The role of an active backend can be found from the
<structfield>usename</structfield> column of the
<structname>pg_stat_activity</structname> view.
pg_cancel_backendとpg_terminate_backendは（それぞれ、SIGINTまたはSIGTERM）シグナルをプロセス識別子で特定されたバックエンドプロセスに送ります。
使用中のバックエンドのプロセス識別子はpg_stat_activityビューのpid列から、もしくは、（Unixではps、WindowsではTask Managerにより）サーバ上のpostgresプロセスをリストすることで見つけられます。
実行中のバックエンドのロールはpg_stat_activityのusename列から確認することができます。
<function>pg_log_backend_memory_contexts</function> can be used
to log the memory contexts of a backend process. For example:
バックエンドプロセスのメモリコンテキストのログを取るためにpg_log_backend_memory_contextsを利用できます。
例を示します。
postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid()); pg_log_backend_memory_contexts -------------------------------- t (1 row)
One message for each memory context will be logged. For example: 各々のメモリコンテキストについて一つのメッセージがログされます。例を示します。
LOG: logging memory contexts of PID 10377 STATEMENT: SELECT pg_log_backend_memory_contexts(pg_backend_pid()); LOG: level: 0; TopMemoryContext: 80800 total in 6 blocks; 14432 free (5 chunks); 66368 used LOG: level: 1; pgstat TabStatusArray lookup hash table: 8192 total in 1 blocks; 1408 free (0 chunks); 6784 used LOG: level: 1; TopTransactionContext: 8192 total in 1 blocks; 7720 free (1 chunks); 472 used LOG: level: 1; RowDescriptionContext: 8192 total in 1 blocks; 6880 free (0 chunks); 1312 used LOG: level: 1; MessageContext: 16384 total in 2 blocks; 5152 free (0 chunks); 11232 used LOG: level: 1; Operator class cache: 8192 total in 1 blocks; 512 free (0 chunks); 7680 used LOG: level: 1; smgr relation table: 16384 total in 2 blocks; 4544 free (3 chunks); 11840 used LOG: level: 1; TransactionAbortContext: 32768 total in 1 blocks; 32504 free (0 chunks); 264 used ... LOG: level: 1; ErrorContext: 8192 total in 1 blocks; 7928 free (3 chunks); 264 used LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 used
If there are more than 100 child contexts under the same parent, the first 100 child contexts are logged, along with a summary of the remaining contexts. Note that frequent calls to this function could incur significant overhead, because it may generate a large number of log messages. 同じ親に100よりも多い子コンテキストがあると、最初の100子コンテキストがログされ、残りのコンテキストについてはサマリが付加されます。 この関数を頻繁に呼び出すと、大きなオーバーヘッドを引き起こす可能性があることに注意してください。 大量のログメッセージが生成される可能性があるからです。
The functions shown in <xref
linkend="functions-admin-backup-table"/> assist in making on-line backups.
These functions cannot be executed during recovery (except
<function>pg_backup_start</function>,
<function>pg_backup_stop</function>,
and <function>pg_wal_lsn_diff</function>).
表 9.91に示されている関数はオンラインバックアップの作成を支援します。
これらの関数はリカバリ中には実行できません(pg_backup_start、pg_backup_stop、pg_wal_lsn_diffを除きます)。
For details about proper usage of these functions, see <xref linkend="continuous-archiving"/>. これらの関数の正しい使用方法については、26.3を参照してください。
表9.91 バックアップ制御関数
Function 関数 Description 説明 |
|---|
Creates a named marker record in the write-ahead log that can later be used as a recovery target, and returns the corresponding write-ahead log location. The given name can then be used with <xref linkend="guc-recovery-target-name"/> to specify the point up to which recovery will proceed. Avoid creating multiple restore points with the same name, since recovery will stop at the first one whose name matches the recovery target. 先行書き込みログ中に後でリカバリターゲットとして使用できる名前付けされたマーカーレコードを作成し、関連する先行書き込みログの位置を返します。 与えられた名前はリカバリをどこまで進めるかを指定するためにrecovery_target_nameとともに利用できます。 同じ名前で複数のリストアポイントを作成するのは避けてください。リカバリターゲットが一致した最初のところでリカバリが停止するからです。 This function is restricted to superusers by default, but other users can be granted EXECUTE to run the function. この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
Returns the current write-ahead log flush location (see notes below). 先行書き込みログの現在のフラッシュ位置を取得します。（下の注釈を参照してください。） |
Returns the current write-ahead log insert location (see notes below). 現在の先行書き込みログの挿入位置を取得します。（下の注釈を参照してください。） |
Returns the current write-ahead log write location (see notes below). 現在の先行書き込みログの書き込み位置を取得します。（下の注釈を参照してください。） |
Prepares the server to begin an on-line backup. The only required
parameter is an arbitrary user-defined label for the backup.
(Typically this would be the name under which the backup dump file
will be stored.)
If the optional second parameter is given as <literal>true</literal>,
it specifies executing <function>pg_backup_start</function> as quickly
as possible. This forces an immediate checkpoint which will cause a
spike in I/O operations, slowing any concurrently executing queries.
サーバがオンラインバックアップを開始するのを準備します。
必須パラメータはユーザが任意に定義したバックアップラベルだけです。
（通常、格納に使用するバックアップダンプファイルにちなんだ名前が付けられます。）
オプションの2番目のパラメータが This function is restricted to superusers by default, but other users can be granted EXECUTE to run the function. この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
Finishes performing an on-line backup. The desired contents of the backup label file and the tablespace map file are returned as part of the result of the function and must be written to files in the backup area. These files must not be written to the live data directory (doing so will cause PostgreSQL to fail to restart in the event of a crash). オンラインバックアップの実行を終了します。 バックアップラベルファイルとテーブル空間マップファイルの必要な内容は関数の結果の一部として返され、バックアップ領域内のファイルに書き込まれなければなりません。 これらのファイルはライブデータディレクトリに書き込まれてはなりません（ライブデータディレクトリに書き込まれるとクラッシュ時にPostgreSQLの再起動に失敗します）。
There is an optional parameter of type <type>boolean</type>.
If false, the function will return immediately after the backup is
completed, without waiting for WAL to be archived. This behavior is
only useful with backup software that independently monitors WAL
archiving. Otherwise, WAL required to make the backup consistent might
be missing and make the backup useless. By default or when this
parameter is true, <function>pg_backup_stop</function> will wait for
WAL to be archived when archiving is enabled. (On a standby, this
means that it will wait only when <varname>archive_mode</varname> =
<literal>always</literal>. If write activity on the primary is low,
it may be useful to run <function>pg_switch_wal</function> on the
primary in order to trigger an immediate segment switch.)
オプションで
When executed on a primary, this function also creates a backup
history file in the write-ahead log archive area. The history file
includes the label given to <function>pg_backup_start</function>, the
starting and ending write-ahead log locations for the backup, and the
starting and ending times of the backup. After recording the ending
location, the current write-ahead log insertion point is automatically
advanced to the next write-ahead log file, so that the ending
write-ahead log file can be archived immediately to complete the
backup.
プライマリで実行された場合、この関数はまた、先行書き込みログの格納領域にバックアップ履歴ファイルを作成します。
履歴ファイルには
The result of the function is a single record.
The <parameter>lsn</parameter> column holds the backup's ending
write-ahead log location (which again can be ignored). The second
column returns the contents of the backup label file, and the third
column returns the contents of the tablespace map file. These must be
stored as part of the backup and are required as part of the restore
process.
この関数の結果は単一レコードです。
This function is restricted to superusers by default, but other users can be granted EXECUTE to run the function. この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
|
Forces the server to switch to a new write-ahead log file, which
allows the current file to be archived (assuming you are using
continuous archiving). The result is the ending write-ahead log
location plus 1 within the just-completed write-ahead log file. If
there has been no write-ahead log activity since the last write-ahead
log switch, <function>pg_switch_wal</function> does nothing and
returns the start location of the write-ahead log file currently in
use.
サーバに対して新しい先行書き込みログファイルへ強制スイッチを行い、それによってその現在のファイルがアーカイブされるようにします。
（継続的アーカイブを利用中だと仮定します。）
結果は今ちょうど終了した先行書き込みログファイル内の終了先行書き込みログファイルの場所プラス1です。
最後の先行書き込みログファイルのスイッチ以降先行書き込みログファイル活動がなければ、 This function is restricted to superusers by default, but other users can be granted EXECUTE to run the function. この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
Converts a write-ahead log location to the name of the WAL file holding that location. 先行書き込みログファイルの位置を、その位置を保持しているWALファイルの名前に変換します。 |
Converts a write-ahead log location to a WAL file name and byte offset within that file. 先行書き込みログファイルの位置を、そのファイルの名前とそのファイル内のバイトオフセットに変換します。 |
Extracts the sequence number and timeline ID from a WAL file name. WALファイル名からシーケンス番号とタイムラインIDを抽出します。 |
Calculates the difference in bytes (<parameter>lsn1</parameter> - <parameter>lsn2</parameter>) between two write-ahead log
locations. This can be used
with <structname>pg_stat_replication</structname> or some of the
functions shown in <xref linkend="functions-admin-backup-table"/> to
get the replication lag.
2つの先行書き込みログの位置のバイト単位の差分( |
<function>pg_current_wal_lsn</function> displays the current write-ahead
log write location in the same format used by the above functions.
Similarly, <function>pg_current_wal_insert_lsn</function> displays the
current write-ahead log insertion location
and <function>pg_current_wal_flush_lsn</function> displays the current
write-ahead log flush location. The insertion location is
the <quote>logical</quote> end of the write-ahead log at any instant,
while the write location is the end of what has actually been written out
from the server's internal buffers, and the flush location is the last
location known to be written to durable storage. The write location is the
end of what can be examined from outside the server, and is usually what
you want if you are interested in archiving partially-complete write-ahead
log files. The insertion and flush locations are made available primarily
for server debugging purposes. These are all read-only operations and do
not require superuser permissions.
pg_current_wal_lsnは、上記の関数で使用されるのと同じ書式で現在の先行書き込みログの書き込み位置を表示します。
同様にpg_current_wal_insert_lsnは、現在の先行書き込みログの挿入位置を表示し、pg_current_wal_flush_lsnはトランザクションログの現在のフラッシュ位置を表示します。
挿入位置は 「論理的」な任意の時点の先行書き込みログの終了位置です。
一方、書き込み位置は、サーバの内部バッファから書き出された実際の終了位置、またフラッシュ位置は永続的ストレージへの書き込みが保証される位置です。
書き込み位置はサーバ外部から検証可能なものの終端です。通常は、部分的に完了した先行書き込みログファイルのアーカイブ処理を行いたい場合に必要とされるものです。
挿入およびフラッシュ位置はサーバをデバッグする際に主に使用されます。
これらはどちらも読み取りのみの操作であり、スーパーユーザ権限を必要としません。
You can use <function>pg_walfile_name_offset</function> to extract the
corresponding write-ahead log file name and byte offset from
a <type>pg_lsn</type> value. For example:
pg_walfile_name_offsetを使用して、pg_lsn値から、対応する先行書き込みログファイル名とバイトオフセットを取り出すことができます。
以下に例を示します。
postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
(1 row)
Similarly, <function>pg_walfile_name</function> extracts just the write-ahead log file name.
When the given write-ahead log location is exactly at a write-ahead log file boundary, both
these functions return the name of the preceding write-ahead log file.
This is usually the desired behavior for managing write-ahead log archiving
behavior, since the preceding file is the last one that currently
needs to be archived.
同様に、pg_walfile_nameは、先行書き込みログファイル名のみを取り出します。
指定した先行書き込みログの位置が正確に先行書き込みログファイルの境界であった場合、これらの両関数は前の先行書き込みログファイルの名前を返します。
通常これは、先行書き込みログファイルのアーカイブ動作では好まれる動作です。
前のファイルが現在のアーカイブで必要とする最後のファイルであるからです。
<function>pg_split_walfile_name</function> is useful to compute a
<acronym>LSN</acronym> from a file offset and WAL file name, for example:
pg_split_walfile_nameは、ファイルオフセットとWALファイル名からLSNを計算するのに有用です。例を示します。
postgres=# \set file_name '000000010000000100C000AB'
postgres=# \set offset 256
postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset AS lsn
FROM pg_split_walfile_name(:'file_name') pd,
pg_show_all_settings() ps
WHERE ps.name = 'wal_segment_size';
lsn
---------------
C001/AB000100
(1 row)
The functions shown in <xref linkend="functions-recovery-info-table"/> provide information about the current status of a standby server. These functions may be executed both during recovery and in normal running. 表 9.92に示される関数は、スタンバイサーバの現在のステータス情報を提供します。 これらの関数はリカバリ中、および通常稼働時に実行することができるでしょう。
表9.92 リカバリ情報関数
The functions shown in <xref linkend="functions-recovery-control-table"/> control the progress of recovery. These functions may be executed only during recovery. 表 9.93に示す関数は、リカバリの進行を制御する関数です。 これらの関数はリカバリ中のみ実行することが可能です。
表9.93 リカバリ制御関数
<function>pg_wal_replay_pause</function> and
<function>pg_wal_replay_resume</function> cannot be executed while
a promotion is ongoing. If a promotion is triggered while recovery
is paused, the paused state ends and promotion continues.
pg_wal_replay_pauseとpg_wal_replay_resumeは昇格が進行中は実行できません。
リカバリ中断中に昇格が引き起こされると中断状態は終了し、昇格が継続します。
If streaming replication is disabled, the paused state may continue indefinitely without a problem. If streaming replication is in progress then WAL records will continue to be received, which will eventually fill available disk space, depending upon the duration of the pause, the rate of WAL generation and available disk space. ストリーミングレプリケーションが無効の場合、停止状態は特に問題なく永久に継続します。 ストリーミングレプリケーションの進行中は、WALレコードの受信が継続され、停止時間、WALの生成速度、ディスクの残存容量によりますが、ディスク溢れが発生する可能性があります。
<productname>PostgreSQL</productname> allows database sessions to synchronize their
snapshots. A <firstterm>snapshot</firstterm> determines which data is visible to the
transaction that is using the snapshot. Synchronized snapshots are
necessary when two or more sessions need to see identical content in the
database. If two sessions just start their transactions independently,
there is always a possibility that some third transaction commits
between the executions of the two <command>START TRANSACTION</command> commands,
so that one session sees the effects of that transaction and the other
does not.
PostgreSQLはデータベースのセッションに対して、それらのスナップショットを同期させることが可能です。
スナップショットは、そのスナップショットを使用しているトランザクションにどのデータが可視かを決定します。
同期スナップショットは、2つ以上のセッションにおいて、全く同じデータベース内容を見たい場合に必要となります。
単に2つのセッションが独立してそれぞれのトランザクションを開始するだけでは、第3のトランザクションのコミットが、2つのトランザクションのSTART TRANSACTIONの狭間で実行され、そのため一方のトランザクションではそのコミット結果が見え、他方では見えないという可能性が常にあります。
To solve this problem, <productname>PostgreSQL</productname> allows a transaction to <firstterm>export</firstterm> the snapshot it is using. As long as the exporting transaction remains open, other transactions can <firstterm>import</firstterm> its snapshot, and thereby be guaranteed that they see exactly the same view of the database that the first transaction sees. But note that any database changes made by any one of these transactions remain invisible to the other transactions, as is usual for changes made by uncommitted transactions. So the transactions are synchronized with respect to pre-existing data, but act normally for changes they make themselves. このような問題を解決するため、PostgreSQLではトランザクションが使用しているスナップショットをエクスポートできるようになっています。エクスポートしたトランザクションが開かれ続けている限り、他のトランザクションがそれをインポートすることができ、 そしてこれにより最初のトランザクションと正確に同じとなるデータベースの可視性を保証されます。ただし、これらの(スナップショットを共有している)トランザクションによって発生したデータベースへの変更は、コミットされていないトランザクションによる変更と同様に、(スナップショットを共有している)他のトランザクションには見えないままです。 つまり、既存データに対しては同期されますが、それら自身による変更については通常の振る舞いをします。
Snapshots are exported with the <function>pg_export_snapshot</function> function,
shown in <xref linkend="functions-snapshot-synchronization-table"/>, and
imported with the <xref linkend="sql-set-transaction"/> command.
スナップショットは、表 9.94に示すpg_export_snapshot関数を用いてエクスポートされ、SET TRANSACTIONコマンドを用いてインポートされます。
表9.94 スナップショット同期関数
Function 関数 Description 説明 |
|---|
|
Saves the transaction's current snapshot and returns
a <type>text</type> string identifying the snapshot. This string must
be passed (outside the database) to clients that want to import the
snapshot. The snapshot is available for import only until the end of
the transaction that exported it.
現在のトランザクションのスナップショットを保存し、それを識別する
A transaction can export more than one snapshot, if needed. Note that
doing so is only useful in <literal>READ COMMITTED</literal>
transactions, since in <literal>REPEATABLE READ</literal> and higher
isolation levels, transactions use the same snapshot throughout their
lifetime. Once a transaction has exported any snapshots, it cannot be
prepared with <xref linkend="sql-prepare-transaction"/>.
必要ならばトランザクションは複数のスナップショットをエクスポートできます。
これは |
Take a snapshot of running transactions and write it to WAL, without having to wait for bgwriter or checkpointer to log one. This is useful for logical decoding on standby, as logical slot creation has to wait until such a record is replayed on the standby. bgwriterやcheckpointerがログするのを待たずに、実行中のトランザクションのスナップショットを取得し、それをWALに書き込みます。 これは、ロジカルデコーディングのスタンバイに対して便利です。ロジカルのスロットの作成は、このようなレコードがスタンバイで再生されるまで待たなければならないからです。 |
The functions shown
in <xref linkend="functions-replication-table"/> are for
controlling and interacting with replication features.
See <xref linkend="streaming-replication"/>,
<xref linkend="streaming-replication-slots"/>, and
<xref linkend="replication-origins"/>
for information about the underlying features.
Use of functions for replication origin is only allowed to the
superuser by default, but may be allowed to other users by using the
<literal>GRANT</literal> command.
Use of functions for replication slots is restricted to superusers
and users having <literal>REPLICATION</literal> privilege.
表 9.95に示す関数はレプリケーション機能を制御したり、情報を取得したりするためのものです。
基盤となっている機能の情報に関しては27.2.5、27.2.6、第50章を参照してください。
これらの関数のレプリケーションオリジンでの使用はデフォルトでスーパーユーザにのみ許可されていますが、GRANTコマンドを使って他のユーザに許可することもできます。
これらの関数のレプリケーションスロットでの使用はスーパーユーザとREPLICATION権限を持つユーザに限定されています。
Many of these functions have equivalent commands in the replication protocol; see <xref linkend="protocol-replication"/>. これらの関数の多くには、レプリケーションプロトコルに等価なコマンドがあります。 55.4を参照してください。
The functions described in <xref linkend="functions-admin-backup"/>, <xref linkend="functions-recovery-control"/>, and <xref linkend="functions-snapshot-synchronization"/> are also relevant for replication. 9.27.3、9.27.4、9.27.5に書かれている関数もレプリケーションに関係するものです。
表9.95 レプリケーション管理関数
Function 関数 Description 説明 |
|---|
Creates a new physical replication slot named
<parameter>slot_name</parameter>. The optional second parameter,
when <literal>true</literal>, specifies that the <acronym>LSN</acronym> for this
replication slot be reserved immediately; otherwise
the <acronym>LSN</acronym> is reserved on first connection from a streaming
replication client. Streaming changes from a physical slot is only
possible with the streaming-replication protocol —
see <xref linkend="protocol-replication"/>. The optional third
parameter, <parameter>temporary</parameter>, when set to true, specifies that
the slot should not be permanently stored to disk and is only meant
for use by the current session. Temporary slots are also
released upon any error. This function corresponds
to the replication protocol command <literal>CREATE_REPLICATION_SLOT
... PHYSICAL</literal>.
|
Drops the physical or logical replication slot
named <parameter>slot_name</parameter>. Same as replication protocol
command <literal>DROP_REPLICATION_SLOT</literal>. For logical slots, this must
be called while connected to the same database the slot was created on.
|
Creates a new logical (decoding) replication slot named
<parameter>slot_name</parameter> using the output plugin
<parameter>plugin</parameter>. The optional third
parameter, <parameter>temporary</parameter>, when set to true, specifies that
the slot should not be permanently stored to disk and is only meant
for use by the current session. Temporary slots are also
released upon any error. The optional fourth parameter,
<parameter>twophase</parameter>, when set to true, specifies
that the decoding of prepared transactions is enabled for this
slot. A call to this function has the same effect as the replication
protocol command <literal>CREATE_REPLICATION_SLOT ... LOGICAL</literal>.
出力プラグイン |
Copies an existing physical replication slot named <parameter>src_slot_name</parameter>
to a physical replication slot named <parameter>dst_slot_name</parameter>.
The copied physical slot starts to reserve WAL from the same <acronym>LSN</acronym> as the
source slot.
<parameter>temporary</parameter> is optional. If <parameter>temporary</parameter>
is omitted, the same value as the source slot is used.
|
Copies an existing logical replication slot
named <parameter>src_slot_name</parameter> to a logical replication
slot named <parameter>dst_slot_name</parameter>, optionally changing
the output plugin and persistence. The copied logical slot starts
from the same <acronym>LSN</acronym> as the source logical slot. Both
<parameter>temporary</parameter> and <parameter>plugin</parameter> are
optional; if they are omitted, the values of the source slot are used.
|
Returns changes in the slot <parameter>slot_name</parameter>, starting
from the point from which changes have been consumed last. If
<parameter>upto_lsn</parameter>
and <parameter>upto_nchanges</parameter> are NULL,
logical decoding will continue until end of WAL. If
<parameter>upto_lsn</parameter> is non-NULL, decoding will include only
those transactions which commit prior to the specified LSN. If
<parameter>upto_nchanges</parameter> is non-NULL, decoding will
stop when the number of rows produced by decoding exceeds
the specified value. Note, however, that the actual number of
rows returned may be larger, since this limit is only checked after
adding the rows produced when decoding each new transaction commit.
変更が最後に消費された時点から開始して、スロット |
Behaves just like
the <function>pg_logical_slot_get_changes()</function> function,
except that changes are not consumed; that is, they will be returned
again on future calls.
変更が消費されないということを除いて、 |
Behaves just like
the <function>pg_logical_slot_get_changes()</function> function,
except that changes are returned as <type>bytea</type>.
変更は |
Behaves just like
the <function>pg_logical_slot_peek_changes()</function> function,
except that changes are returned as <type>bytea</type>.
変更は |
Advances the current confirmed position of a replication slot named
<parameter>slot_name</parameter>. The slot will not be moved backwards,
and it will not be moved beyond the current insert location. Returns
the name of the slot and the actual position that it was advanced to.
The updated slot position information is written out at the next
checkpoint if any advancing is done. So in the event of a crash, the
slot may return to an earlier position.
|
Creates a replication origin with the given external name, and returns the internal ID assigned to it. 指定した外部名でレプリケーション起点を作成し、割り当てられた内部IDを返します。 |
Deletes a previously-created replication origin, including any associated replay progress. 以前に作成されたレプリケーション起点を、それに関連するすべての再生の進捗も含めて削除します。 |
Looks up a replication origin by name and returns the internal ID. If
no such replication origin is found, <literal>NULL</literal> is
returned.
レプリケーション起点を名前で検索し、内部IDを返します。
相当するレプリケーション起点が見つからない場合は |
Marks the current session as replaying from the given
origin, allowing replay progress to be tracked.
Can only be used if no origin is currently selected.
Use <function>pg_replication_origin_session_reset</function> to undo.
現在のセッションに、指定の起点から再生中であると印を付け、再生の進捗が追跡できるようにします。
起点が選択されていない場合にのみ使うことができます。
元に戻すには |
Cancels the effects
of <function>pg_replication_origin_session_setup()</function>.
|
Returns true if a replication origin has been selected in the current session. 現在のセッションでレプリケーション起点が選択されていれば真を返します。 |
Returns the replay location for the replication origin selected in
the current session. The parameter <parameter>flush</parameter>
determines whether the corresponding local transaction will be
guaranteed to have been flushed to disk or not.
現在のセッションで設定されたレプリケーション起点の再生位置を返します。
パラメータ |
Marks the current transaction as replaying a transaction that has
committed at the given <acronym>LSN</acronym> and timestamp. Can
only be called when a replication origin has been selected
using <function>pg_replication_origin_session_setup</function>.
現在のトランザクションに、指定のLSNおよびタイムスタンプでコミットしたトランザクションを再生中であると印をつけます。
事前にレプリケーション起点が |
Cancels the effects of
<function>pg_replication_origin_xact_setup()</function>.
|
Sets replication progress for the given node to the given location. This is primarily useful for setting up the initial location, or setting a new location after configuration changes and similar. Be aware that careless use of this function can lead to inconsistently replicated data. 指定したノードのレプリケーションの進捗を、指定の位置に設定します。 これは主に設定変更の後で初期位置や新しい位置を設定するときなどに役立ちます。 この関数を不注意に使うと、レプリケーションデータが一貫性を失うかもしれないことに注意して下さい。 |
Returns the replay location for the given replication origin. The
parameter <parameter>flush</parameter> determines whether the
corresponding local transaction will be guaranteed to have been
flushed to disk or not.
指定したレプリケーション起点の再生位置を返します。
パラメータ |
Emits a logical decoding message. This can be used to pass generic
messages to logical decoding plugins through
WAL. The <parameter>transactional</parameter> parameter specifies if
the message should be part of the current transaction, or if it should
be written immediately and decoded as soon as the logical decoder
reads the record. The <parameter>prefix</parameter> parameter is a
textual prefix that can be used by logical decoding plugins to easily
recognize messages that are interesting for them.
The <parameter>content</parameter> parameter is the content of the
message, given either in text or binary form.
論理デコードのメッセージを送出します
これは汎用的なメッセージをWALを通して論理デコードのプラグインに渡すのに使うことができます。
パラメータ |
The functions shown in <xref linkend="functions-admin-dbsize"/> calculate
the disk space usage of database objects, or assist in presentation
or understanding of usage results. <literal>bigint</literal> results
are measured in bytes. If an OID that does
not represent an existing object is passed to one of these
functions, <literal>NULL</literal> is returned.
表 9.96で示された関数はデータベースオブジェクトのディスク領域の使用状況を計算したり、使用結果の表示あるいは理解を補助します。
bigintの結果はバイト単位の大きさです。
関数に存在するオブジェクト以外のOIDが渡されるとNULLが返ります。
表9.96 データベースオブジェクトサイズ関数
Function 関数 Description 説明 |
|---|
Shows the number of bytes used to store any individual data value. If applied directly to a table column value, this reflects any compression that was done. 個々のデータ値を格納するのに使用されるバイト数を表示します。 テーブルの列の値に直接適用すると、圧縮が行われていればそれを反映します。 |
Shows the compression algorithm that was used to compress
an individual variable-length value. Returns <literal>NULL</literal>
if the value is not compressed.
個々の可変長値で使われた圧縮アルゴリズムを表示します。
値が圧縮されていなければ、 |
Computes the total disk space used by the database with the specified
name or OID. To use this function, you must
have <literal>CONNECT</literal> privilege on the specified database
(which is granted by default) or have privileges of
the <literal>pg_read_all_stats</literal> role.
名前あるいはOIDで指定したデータベースによって使われている全ディスクスペースを計算します。
この関数を使うには、指定したデータベースに |
Computes the total disk space used by indexes attached to the specified table. 指定したテーブルに付与されたインデックスで使用されている全ディスクスペースを計算します。 |
Computes the disk space used by one <quote>fork</quote> of the
specified relation. (Note that for most purposes it is more
convenient to use the higher-level
functions <function>pg_total_relation_size</function>
or <function>pg_table_size</function>, which sum the sizes of all
forks.) With one argument, this returns the size of the main data
fork of the relation. The second argument can be provided to specify
which fork to examine:
指定したリレーションの一つの「fork」で使用されているディスクスペースを計算します。
（大抵の目的には、すべてのフォークのサイズを合計する高レベルの
|
Converts a size in human-readable format (as returned
by <function>pg_size_pretty</function>) into bytes. Valid units are
<literal>bytes</literal>, <literal>B</literal>, <literal>kB</literal>,
<literal>MB</literal>, <literal>GB</literal>, <literal>TB</literal>,
and <literal>PB</literal>.
（ |
Converts a size in bytes into a more easily human-readable format with size units (bytes, kB, MB, GB, TB, or PB as appropriate). Note that the units are powers of 2 rather than powers of 10, so 1kB is 1024 bytes, 1MB is 1024<superscript>2</superscript> = 1048576 bytes, and so on. バイトサイズを、サイズ単位(バイト、kB、MB、GB、TB、PBのうちの適切なもの)を使った、より人間が読みやすい形式に変換します。 単位は10のべき乗ではなく、2のべき乗であることに注意してください。ですから1kBは1024バイトで、1MBは10242 = 1048576バイト、などとなります。 |
Computes the disk space used by the specified table, excluding indexes (but including its TOAST table if any, free space map, and visibility map). 指定テーブルが使用している、インデックスを含まないディスクスペースを計算します。（ただしあればTOASTテーブル、空き領域マップ、可視性マップを含みます。） |
Computes the total disk space used in the tablespace with the
specified name or OID. To use this function, you must
have <literal>CREATE</literal> privilege on the specified tablespace
or have privileges of the <literal>pg_read_all_stats</literal> role,
unless it is the default tablespace for the current database.
名前あるいはOIDで指定されたテーブル空間で使用されているディスクスペースを計算します。
現在のデータベースのデフォルトテーブル空間でない限り、この関数を使うには、指定したテーブル空間に |
Computes the total disk space used by the specified table, including
all indexes and <acronym>TOAST</acronym> data. The result is
equivalent to <function>pg_table_size</function>
<literal>+</literal> <function>pg_indexes_size</function>.
指定テーブルが使用している、インデックスとTOASTデータを含む全ディスクスペースを計算します。
結果は |
The functions above that operate on tables or indexes accept a
<type>regclass</type> argument, which is simply the OID of the table or index
in the <structname>pg_class</structname> system catalog. You do not have to look up
the OID by hand, however, since the <type>regclass</type> data type's input
converter will do the work for you. See <xref linkend="datatype-oid"/>
for details.
上記の関数において、テーブルやインデックスをregclass引数として受け取って処理するものがありますが、この引数は単にpg_classシステムカタログにあるテーブルやインデックスのOIDです。
ただし、regclassデータ型が自動で入力変換を行うため、ユーザが手動で該当するOIDを調べる必要はありません。
詳細は8.19を参照ください。
The functions shown in <xref linkend="functions-admin-dblocation"/> assist in identifying the specific disk files associated with database objects. 表 9.97 に示される関数は、データベースオブジェクトに関連する特定のディスクファイルを確認する際の手助けとなります。
表9.97 データベースオブジェクト位置関数
Function 関数 Description 説明 |
|---|
Returns the <quote>filenode</quote> number currently assigned to the
specified relation. The filenode is the base component of the file
name(s) used for the relation (see
<xref linkend="storage-file-layout"/> for more information).
For most relations the result is the same as
<structname>pg_class</structname>.<structfield>relfilenode</structfield>,
but for certain system catalogs <structfield>relfilenode</structfield>
is zero and this function must be used to get the correct value. The
function returns NULL if passed a relation that does not have storage,
such as a view.
指定されたリレーションに現在割り当てられている「ファイルノード」番号を返します。
ファイルノードは、リレーションに使用しているファイル名の基本要素です。(詳しくは73.1を参照して下さい。)
ほとんどのリレーションについては、結果は |
Returns the entire file path name (relative to the database cluster's
data directory, <varname>PGDATA</varname>) of the relation.
リレーションのファイルパス名全体（データベースクラスタのデータディレクトリ、 |
Returns a relation's OID given the tablespace OID and filenode it is
stored under. This is essentially the inverse mapping of
<function>pg_relation_filepath</function>. For a relation in the
database's default tablespace, the tablespace can be specified as zero.
Returns <literal>NULL</literal> if no relation in the current database
is associated with the given values.
与えられたテーブル空間OIDとファイルノードに格納されているリレーションのOIDを返します。
これは本質的に |
<xref linkend="functions-admin-collation"/> lists functions used to manage collations. 表 9.98に照合順序の管理に使用される関数の一覧を示します。
表9.98 照合順序管理関数
Function 関数 Description 説明 |
|---|
Returns the actual version of the collation object as it is currently
installed in the operating system. If this is different from the
value in
<structname>pg_collation</structname>.<structfield>collversion</structfield>,
then objects depending on the collation might need to be rebuilt. See
also <xref linkend="sql-altercollation"/>.
オペレーティングシステムに現在インストールされている照合順序オブジェクトの実際のバージョンを返します。
これが |
Returns the actual version of the database's collation as it is currently
installed in the operating system. If this is different from the
value in
<structname>pg_database</structname>.<structfield>datcollversion</structfield>,
then objects depending on the collation might need to be rebuilt. See
also <xref linkend="sql-alterdatabase"/>.
オペレーティングシステムに現在インストールされている照合順序オブジェクトの実際のバージョンを返します。
これが |
Adds collations to the system
catalog <structname>pg_collation</structname> based on all the locales
it finds in the operating system. This is
what <command>initdb</command> uses; see
<xref linkend="collation-managing"/> for more details. If additional
locales are installed into the operating system later on, this
function can be run again to add collations for the new locales.
Locales that match existing entries
in <structname>pg_collation</structname> will be skipped. (But
collation objects based on locales that are no longer present in the
operating system are not removed by this function.)
The <parameter>schema</parameter> parameter would typically
be <literal>pg_catalog</literal>, but that is not a requirement; the
collations could be installed into some other schema as well. The
function returns the number of new collation objects it created.
Use of this function is restricted to superusers.
オペレーティングシステム上にあるすべてのロケールに基づき、システムカタログ |
<xref linkend="functions-info-partition"/> lists functions that provide information about the structure of partitioned tables. 表 9.99にパーティション化テーブルの構造に関する情報を提供する関数を示します。
表9.99 パーティション情報関数
For example, to check the total size of the data contained in a
partitioned table <structname>measurement</structname>, one could use the
following query:
たとえばパーティション化テーブルmeasurementに含まれるデータの全体サイズを確認するには、次の問い合わせが利用できます。
SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
FROM pg_partition_tree('measurement');
<xref linkend="functions-admin-index-table"/> shows the functions available for index maintenance tasks. (Note that these maintenance tasks are normally done automatically by autovacuum; use of these functions is only required in special cases.) These functions cannot be executed during recovery. Use of these functions is restricted to superusers and the owner of the given index. 表 9.100にインデックスの保守タスクに使用可能な関数を示します。 （これらの保守業務は通常自動バキュームが自動的に行うことに注意してください。これらの関数は特別な場合にのみ必要になります。） これらの関数はリカバリ中は実行できません。 これらの関数の使用はスーパーユーザと対象のインデックスの所有者に限定されます。
表9.100 インデックス保守関数
Function 関数 Description 説明 |
|---|
Scans the specified BRIN index to find page ranges in the base table that are not currently summarized by the index; for any such range it creates a new summary index tuple by scanning those table pages. Returns the number of new page range summaries that were inserted into the index. 指定されたBRINインデックスを検査してベーステーブル内のインデックスによって現在要約されていないページ範囲を探します。 そのような範囲があれば、テーブルのページをスキャンして新しい要約インデックスタプルを作成します。 インデックスに挿入された新しいページ範囲要約の数を返します。 |
Summarizes the page range covering the given block, if not already
summarized. This is
like <function>brin_summarize_new_values</function> except that it
only processes the page range that covers the given table block number.
指定のブロックを含むページ範囲が、まだ要約されていなければ、要約します。
これは |
Removes the BRIN index tuple that summarizes the page range covering the given table block, if there is one. 指定のブロックを含むページ範囲が要約されていれば、それを含むページ範囲を要約するBRINインデックスタプルを削除します。 |
Cleans up the <quote>pending</quote> list of the specified GIN index
by moving entries in it, in bulk, to the main GIN data structure.
Returns the number of pages removed from the pending list.
If the argument is a GIN index built with
the <literal>fastupdate</literal> option disabled, no cleanup happens
and the result is zero, because the index doesn't have a pending list.
See <xref linkend="gin-fast-update"/> and <xref linkend="gin-tips"/>
for details about the pending list and <literal>fastupdate</literal>
option.
指定GINインデックスの「処理待ち」リストのエントリをメインのインデックスデータ構造に一括で移動します。
処理待ちリストから削除されたページ数を返します。
|
The functions shown in <xref
linkend="functions-admin-genfile-table"/> provide native access to
files on the machine hosting the server. Only files within the
database cluster directory and the <varname>log_directory</varname> can be
accessed, unless the user is a superuser or is granted the role
<literal>pg_read_server_files</literal>. Use a relative path for files in
the cluster directory, and a path matching the <varname>log_directory</varname>
configuration setting for log files.
表 9.101で示されている関数はサーバをホスティングしているマシン上のファイルに対し、ネイティブのアクセスを提供します。
ユーザがpg_read_server_filesロールを与えられていない限り、データベースクラスタディレクトリとlog_directoryに存在するファイルのみがアクセス可能です。
クラスタディレクトリ内のファイルに対して相対パスを、そしてログファイルに対してはlog_directory構成設定に一致するパスを使用してください。
Note that granting users the EXECUTE privilege on
<function>pg_read_file()</function>, or related functions, allows them the
ability to read any file on the server that the database server process can
read; these functions bypass all in-database privilege checks. This means
that, for example, a user with such access is able to read the contents of
the <structname>pg_authid</structname> table where authentication
information is stored, as well as read any table data in the database.
Therefore, granting access to these functions should be carefully
considered.
ユーザに対してEXECUTE権限をpg_read_file()あるいは関連する関数に与えることは、サーバの上データベースサーバプロセスが読めるすべてのファイルを読めるようにすることになることに注意してください。これらの関数はデータベース内のすべての権限チェックをすり抜けます。
このことは、たとえばそのようなアクセス権を持つユーザは、認証情報が格納されたpg_authidテーブルの中身を読むことができますし、同様にデータベース内のすべてのテーブルデータを読むことができるということを意味します。
ですからこれらの関数にアクセス権限を与えるのは慎重に考慮したほうが良いでしょう。
When granting privilege on these functions, note that the table entries
showing optional parameters are mostly implemented as several physical
functions with different parameter lists. Privilege must be granted
separately on each such function, if it is to be
used. <application>psql</application>'s <command>\df</command> command
can be useful to check what the actual function signatures are.
これらの関数に権限を付与する場合、オプションパラメータを示すテーブルエントリは、ほとんどの場合、異なるパラメータリストを持つ複数の物理的な関数として実装されることに注意してください。
使用する場合は、各関数に対して個別に権限を付与する必要があります。
psqlの\dfコマンドは、実際の関数シグネチャが何であるかをチェックするのに役立ちます。
Some of these functions take an optional <parameter>missing_ok</parameter>
parameter, which specifies the behavior when the file or directory does
not exist. If <literal>true</literal>, the function
returns <literal>NULL</literal> or an empty result set, as appropriate.
If <literal>false</literal>, an error is raised. (Failure conditions
other than <quote>file not found</quote> are reported as errors in any
case.) The default is <literal>false</literal>.
これらの関数の一部はオプションでmissing_okパラメータをとり、ファイルまたはディレクトリが存在しない場合の動作を指定できます。
trueの場合、関数はNULLを返すか、適切な場合には空の結果集合を返します。
falseの場合はエラーが発生します。
デフォルトはfalseです。
（「ファイルが見つかりません」以外の失敗条件は、どのケースでもエラーとして報告されます。）
デフォルトはfalseです。
表9.101 汎用ファイルアクセス関数
The functions shown in <xref linkend="functions-advisory-locks-table"/> manage advisory locks. For details about proper use of these functions, see <xref linkend="advisory-locks"/>. 表 9.102に示す関数は勧告的ロックを管理します。 これらの関数の適切な使用方法についての詳細は、13.3.5を参照してください。
All these functions are intended to be used to lock application-defined
resources, which can be identified either by a single 64-bit key value or
two 32-bit key values (note that these two key spaces do not overlap).
If another session already holds a conflicting lock on the same resource
identifier, the functions will either wait until the resource becomes
available, or return a <literal>false</literal> result, as appropriate for
the function.
Locks can be either shared or exclusive: a shared lock does not conflict
with other shared locks on the same resource, only with exclusive locks.
Locks can be taken at session level (so that they are held until released
or the session ends) or at transaction level (so that they are held until
the current transaction ends; there is no provision for manual release).
Multiple session-level lock requests stack, so that if the same resource
identifier is locked three times there must then be three unlock requests
to release the resource in advance of session end.
これらの関数はすべて単一の64ビットキー値か2つの32ビットキー値（これらのキー空間は重なり合わないことに注意してください）で識別されるアプリケーション定義のリソースをロックするために使うことを意図しています。
他のセッションがすでに同じリソース識別子とコンフリクトするロックを保持していたら、関数はリソースが利用可能になるまで待つか、その関数にとって適切ならばfalseを結果として返します。
ロックは共有はあるいは排他のどちらも可能です。共有ロックは同じリソースに対して他の共有ロックとコンフリクトしません。排他ロックとだけコンフリクトします。
ロックはセッションレベル（ロックは解放されるまで保持するかセッションの終了まで保持します）あるいはトランザクションレベル（ロックは現在のトランザクションが終了するまで保持します。手動で解放する方法はありません）で取得できます。
複数のセッションレベルロック要求は積み重ねられます。これにより、同じリソース識別子が3回ロックされると、セッション終了前にそのリソースを解放するアンロック要求が3回発行されなければならなくなります。
表9.102 勧告的ロック用関数