9.17. シーケンス操作関数

PostgreSQL 17.6文書
		第9章関数と演算子
前へ	上へ	9.17. シーケンス操作関数	次へ

9.17. シーケンス操作関数 #

本節ではシーケンスオブジェクトに対し演算を行う関数について説明します。シーケンスオブジェクトは、シーケンスジェネレータ、あるいは単にシーケンスとも呼ばれます。シーケンスオブジェクトは特殊な一行だけのテーブルで、CREATE SEQUENCEで作成されます。シーケンスオブジェクトは一般的にテーブルの行に一意の識別子を生成するために使用されます。表 9.53に列挙されているシーケンス関数は、シーケンスオブジェクトから連続したシーケンス値を取得するための、簡易でマルチユーザに対応した関数です。

表9.53 シーケンス関数

関数説明
`nextval` ( `regclass` ) → `bigint` シーケンスを次の値に進めてその値を返します。これは原子的に行われます。複数のセッションが`nextval`を同時に実行しても、各々のシーケンスは異なったシーケンス値を安全に返します。シーケンスオブジェクトがデフォルト値を伴って作成されると、後続の`nextval`呼び出しは1から始まる次の値を返します。それ以外の動作は適切なパラメータをCREATE SEQUENCEコマンドで使うことによって得られます。この関数はシーケンスオブジェクトの`USAGE`あるいは`UPDATE`権限が必要です。
`setval` ( `regclass`, `bigint` [, `boolean` ] ) → `bigint` シーケンスオブジェクトの現在の値をセットします。オプションで`is_called`をセットします。 2つのパラメータを持つ形式では、シーケンスの`last_value`フィールドを指定した値にセットし、`is_called`フィールドを`true`に設定します。これは次の`nextval`が値を返す前にシーケンスを増分することを意味します。 `currval`で報告される値も指定した値に設定されます。 3つのパラメータを持つ形式では、`is_called`は`true`あるいは`false`に設定されます。 `true`は2つのパラメータを持つ形式と同じ効果を持ちます。 `false`に設定されていると、次の`nextval`はまさに指定した値を返し、後続の`nextval`がシーケンスの増加を開始します。更に、この場合は`currval`が報告する値は変化しません。たとえば次ようになります。 SELECT setval('myseq', 42); 次の`nextval`は43を返す SELECT setval('myseq', 42, true); 同上 SELECT setval('myseq', 42, false); 次の`nextval`は42を返す `setval`が返した値はその2番目の引数と単に同じです。この関数はシーケンスの`UPDATE`権限が必要です。
`currval` ( `regclass` ) → `bigint` 現在のセッションでこのシーケンスに対して直近の`nextval`によって得られた値を返します。（このセッションで`nextval`が呼ばれていなければエラーが報告されます。）これはセッションローカルな値を返すので、他のセッションが`nextval`を呼び出したかどうかに関わらず予測可能な値を返します。この関数はシーケンスの`USAGE`あるいは`SELECT`権限が必要です。
`lastval` () → `bigint` 現在のセッションでこのシーケンスに対して直近の`nextval`によって得られた値を返します。この関数は、現在のセッションで`nextval`が直近に適用されたシーケンス名を参照する引数を取ることを除き、`currval`と同じです。このセッションで`nextval`が呼ばれていないのに`lastval`を呼び出すのはエラーです。この関数はシーケンスの`USAGE`あるいは`SELECT`権限が必要です。

関数

説明

nextval ( regclass ) → bigint

シーケンスを次の値に進めてその値を返します。これは原子的に行われます。複数のセッションがnextvalを同時に実行しても、各々のシーケンスは異なったシーケンス値を安全に返します。シーケンスオブジェクトがデフォルト値を伴って作成されると、後続のnextval呼び出しは1から始まる次の値を返します。それ以外の動作は適切なパラメータをCREATE SEQUENCEコマンドで使うことによって得られます。

この関数はシーケンスオブジェクトのUSAGEあるいはUPDATE権限が必要です。

setval ( regclass, bigint [, boolean ] ) → bigint

シーケンスオブジェクトの現在の値をセットします。オプションでis_calledをセットします。 2つのパラメータを持つ形式では、シーケンスのlast_valueフィールドを指定した値にセットし、is_calledフィールドをtrueに設定します。これは次のnextvalが値を返す前にシーケンスを増分することを意味します。 currvalで報告される値も指定した値に設定されます。 3つのパラメータを持つ形式では、is_calledはtrueあるいはfalseに設定されます。 trueは2つのパラメータを持つ形式と同じ効果を持ちます。 falseに設定されていると、次のnextvalはまさに指定した値を返し、後続のnextvalがシーケンスの増加を開始します。更に、この場合はcurrvalが報告する値は変化しません。たとえば次ようになります。

SELECT setval('myseq', 42);           次のnextvalは43を返す
SELECT setval('myseq', 42, true);     同上
SELECT setval('myseq', 42, false);    次のnextvalは42を返す

setvalが返した値はその2番目の引数と単に同じです。

この関数はシーケンスのUPDATE権限が必要です。

currval ( regclass ) → bigint

現在のセッションでこのシーケンスに対して直近のnextvalによって得られた値を返します。（このセッションでnextvalが呼ばれていなければエラーが報告されます。）これはセッションローカルな値を返すので、他のセッションがnextvalを呼び出したかどうかに関わらず予測可能な値を返します。

この関数はシーケンスのUSAGEあるいはSELECT権限が必要です。

lastval () → bigint

現在のセッションでこのシーケンスに対して直近のnextvalによって得られた値を返します。この関数は、現在のセッションでnextvalが直近に適用されたシーケンス名を参照する引数を取ることを除き、currvalと同じです。このセッションでnextvalが呼ばれていないのにlastvalを呼び出すのはエラーです。

この関数はシーケンスのUSAGEあるいはSELECT権限が必要です。

注意

同一のシーケンスから数値を取得する同時実行トランザクション同士のブロックを防止するため、nextvalで得られる値は、呼び出しているトランザクションが後でアボートした際に再利用目的での回収は行われません。これは、トランザクションのアボートあるいはデータベースのクラッシュによって、割り当てられるシーケンスの値に欠番ができることがある、ということを意味します。これはトランザクションのアボートがなくても起こります。例えばON CONFLICT句のあるINSERTでは、挿入される予定のタプルについて、必要となるすべてのnextvalの呼び出しも含めて計算し、その後でON CONFLICTのルールを代わりに使用することになる競合について検知します。従って、PostgreSQLのシーケンスオブジェクトは「欠番のない」シーケンスを得るために使うことはできません。

同様に、setvalが行ったシーケンス状態の変更は直ちに他のトランザクションから可視になり、トランザクションがロールバックしても元には戻りません。

nextvalやsetvalの呼び出しを含むトランザクションがコミットする前にデータベースクラスタがクラッシュすると、そのシーケンスの状態は永続的な記憶装置に格納されないかもしれず、クラスタが再起動した後にそのシーケンスが元の状態のままなのか、更新された状態になっているのかは定かではありません。コミットされていないトランザクションは可視ではないので、これはデータベース内のシーケンスの利用に関して言えば無害です。しかし、シーケンス値をデータベースの外での永続的な利用を目的として使う場合は、nextvalの呼び出しが確実にコミットされてから利用してください。

シーケンス関数により操作されるシーケンスはregclass引数で指定されますが、それはpg_classシステムカタログ内にある、そのシーケンスの単なるOIDです。しかしながら、手作業でOIDを検索する必要はなく、regclassデータ型の入力変換器が代わってその作業を行ってくれます。詳細は8.19を見てください。

前へ	上へ	次へ
9.16. JSON関数と演算子	ホーム	9.18. 条件式