型のマッピング Npgsql

Read mappings

以下は、値を読み取るとき、使用されるマッピングを示しています。

• NpgsqlCommand.ExecuteScalar()、NpgsqlDataReader.GetValue()と類似しているメソッドを使用するとき、既定の型が、返されます。
• NpgsqlDataReader.GetFieldValue<T>()を呼び出して、他の型として読み取ることができます。
• プロバイダ特定の型は、NpgsqlDataReader.GetProviderSpecificValue()によって返されます。

Default .NET type列は、NpgsqlDataReader.GetValue()が、返すデータ型を指定します。

特化されていない場合、NpgsqlDataReader.GetProviderSpecificValueは、プロバイダ固有の型の列で指定されたデータ型の値や既定の.NET型を返します。

最後に、3本目の列は、PostgreSQLのデータ型のためのNpgsqlをサポートする、他のCLR型を指定します。これらは、GetFieldValue<T>()を通じて、NpgsqlDataReader.GetBoolean()、GetByte()、GetDouble()などを呼び出すことによって、取り出すことができます。

Write mappings

パラメータに送信されるPostgreSQL型を判断する3つの規則があります。：

1. パラメータのNpgsqlDbTypeが設定されている場合は、それが使用されます。
2. パラメータのDataTypeが、設定されている場合、それが使用されます。
3. パラメータのDbTypeが、設定されている場合、それが使用されます。
4. 上記のいずれも設定されていない場合、バックエンド型は、CLR値型から推測されます。

DateTimeとNpgsqlDateTimeでは、注意して下さい。Kind属性は、timestampか、timestamptzを使うべきかどうか判断します。

子型を持つ、範囲と配列、ビットごとに、あるいは、NpgsqlDbType.RangeやNpgsqlDbType.Arrayを使用するとき、例えば、int4rangeのNpgsqlDbTypeを構築するために、NpgsqlDbType.Range | NpgsqlDbType.Integerを記述し、int[]のNpgsqlDbTypeを構築するために、NpgsqlDbType.Array| NpgsqlDbType.Integerを記述することに注意して下さい。

列挙型については、EnumsとCompositesのページを参照してください。

.NET types and PostgreSQL types

.NETとPostgreSQL型は、それらが提供する解像度と範囲が異なります;.NET型は、通常、PostgreSQL型に比べて、範囲が狭いですが、高い解像度を持っています。：

あなたの要求が、.NETネイティブ型によって満たされる場合、あなたが、Npgsqlで、直接、それらを使用するのが最適です。しかしながら、PostgreSQL型の拡張範囲が必要な場合、あなたは、PostgreSQLの型を正確に表している、Npgsqlのプロバイダ固有の型を使うことができます。

Timezones

.NET型とPostgreSQLの間で、タイムゾーンとタイムゾーン変換が、どのように処理されるかを正確に理解することが重要です。特に、.NETのDateTimeには、Npgsqlが、値を読み書きする方法に影響する、Kindプロパティがあります。

既定では、DateTimeは、タイムゾーンなしのタイムスタンプとして、PostgreSQLに送信されます。－いかなる種類のタイムゾーン変換も行われません。そして、あなたのDateTimeインスタンスは、そのまま、PostgreSQLに転送されます。これは、データベースで、タイムスタンプを格納するために、推奨されている方法です。あなたのNpgsqlParameter上で、NpgsqlDbType.TimestampTzを設定することによって、タイムゾーンの付いたタイムスタンプとして、DateTimeを送信する場合があることに注意ください。;この場合、Kindが、ローカルである場合、Npgsqlは、値をPostgreSQLに送信する前に、UTCに変換します。それ以外の場合には、それは、現状のまま送信されます。

timestamptzとして記述され、送信前に、UTCに変換される、DateTimeOffset値を送信することもできます。

タイムゾーンを持つPostgreSQL時間は、実際に、データベースにタイムゾーンを格納する、唯一の日付/時間型です。あなたは、1つのPostgreSQLに送信する、DateTimeOffsetを使用することができます。この場合、日付コンポーネントが、削除されます。そして、時間とタイムゾーンが、保持されます。DateTimeを送信することもできます。この場合、Kindは、データベースに送信されるタイムゾーンを決定します。

Detailed Behavior: Sending values to the database

Detailed Behavior: Reading values from the database

Further Reading

あなたが、上記のマッピングの決定のいくつかに、本当に興味を持っている場合、この問題を確認して下さい。

Mapping your CLR types

列挙型と複合型を扱うための推奨方法は、あなたのCLR型のマッピングを設定することです。それを行うことは、次の利点を提供します。：

すべての接続に適用される、グローバル・マッピングを設定するために、最初の接続が、開かれる前に、このコードを配置します。：

NpgsqlConnection.GlobalTypeMapper.MapEnum<SomeEnum>("some_enum_type");
NpgsqlConnection.GlobalTypeMapper.MapComposite<SomeType>("some_composite_type");

これは、PostgreSQL型のsome_enum_typeとsome_composite_typeに、あなたのCLR型のSomeEnumとSomeTypeの間で、マッピングを設定します。

あなたが、すべての接続のためのマッピングを設定したくない場合、あなたは、1つだけ接続を設定できます。：

var conn = new NpgsqlConnection(...);
conn.TypeMapper.MapEnum<SomeEnum>("some_enum_type");
conn.TypeMapper.MapComposite<SomeType>("some_composite_type");

マッピングの後、あなたは、いつものように、あなたのCLR型を読み書きすることができます。：

// Writing
using (var cmd = new NpgsqlCommand("INSERT INTO some_table (some_enum_column, some_composite_column) VALUES (@p1, @p2)", conn))
{
    cmd.Parameters.Add(new NpgsqlParameter
    {
        ParameterName = "p1",
        Value = SomeEnum.Good
    });
    cmd.Parameters.Add(new NpgsqlParameter
    {
        ParameterName = "p2",
        Value = new SomeType { ... }
    });
    cmd.ExecuteNonQuery();
}

// Reading
using (var cmd = new NpgsqlCommand("SELECT some_enum_column, some_composite_column FROM some_table", conn))
using (var reader = cmd.ExecuteReader()) {
    reader.Read();
    var enumValue = reader.GetFieldValue<SomeEnum>(0);
    var compositeValue = reader.GetFieldValue<SomeType>(1);
}

あなたのPostgreSQLの列挙型と複合型（上のサンプルのsome_enum_typeとsome_composite_type）に、最初の接続が作成される前に、あなたのデータベースで、定義する必要があることに注意してください（CREATE TYPEを参照）。あなたのプログラムで、PostgreSQL型を作成している場合、Npgsqlが、それらを正しく認識するようにするには、NpgsqlConnection.ReloadTypes()を呼び出します。

Name Translation

CLR型とフィールド名は、通常、（例えば、SomeType）camel caseです。一方、PostgreSQLでは、（例えば、some_type）snake caseです。列挙型と複合型のマッピングを継ぎ目がないようにするために、プラグイン可能な名前変換プログラムは、すべての名前を変換するために使用されます。SomeTypeのような、名前をsome_typeにマッピングする、省略時設定の変換スキームはNpgsqlSnakeCaseNameTranslatorになりますが、あなたは、othersを指定することができます。既定の名前トランスレータは、NpgsqlConnection.GlobalTypeMapper.DefaultNameTranslator、あるいは、NpgsqlConnection.TypeMapper.DefaultNameTranslatorのための特定の接続を通して、あなたのすべての接続のために設定することができます。マッピングを設定するとき、あなたは、名前トランスレータを指定することもできます。：

NpgsqlConnection.GlobalTypeMapper.MapComposite<SomeType>("some_type", new NpgsqlNullNameTranslator());

最後に、あなたは、[PgName]属性を使用して、フィールドごとにマッピングを制御できます。これは、名前トランスレータを上書きするでしょう。

using NpgsqlTypes;

enum SomeEnum {
   [PgName("happy")]
   Good,
   [PgName("sad")]
   Bad
}

Reading and Writing Dynamically (without CLR types)

いくつかの場合では、既存のCLR型なしで、PostgreSQLの列挙型と複合型と対話することが、望ましい場合があります。－これは、主に役に立ちます。あなたのプログラムが、前もって、データベースのスキーマと型を知らない場合、そして、どんな列挙型/複合型とも対話する必要があります。CLR型を使用する方が、安全で速いことに注意してください。（複合型のための）、そして、可能であれば優先すべきです。

列挙型は、単純な文字列として、読み書きすることができます。：

// Writing enum as string
using (var cmd = new NpgsqlCommand("INSERT INTO some_table (some_enum_column) VALUES (@p1)", conn))
{
    cmd.Parameters.Add(new NpgsqlParameter
    {
        ParameterName = "p1",
        Value = "Good"
        DataTypeName = "some_enum_type"
    });
    cmd.ExecuteNonQuery();
}

// Reading enum as string
using (var cmd = new NpgsqlCommand("SELECT some_enum_column FROM some_table", conn))
using (var reader = cmd.ExecuteReader()) {
    reader.Read();
    var enumValue = reader.GetFieldValue<string>(0);
}

複合型は、C#の動的なExpandoObjectsとして、読み書きすることができます。：

// Writing composite as ExpandoObject
using (var cmd = new NpgsqlCommand("INSERT INTO some_table (some_composite_column) VALUES (@p1)", Conn))
{
    var someComposite = new ExpandoObject();
    some_composite.Foo = 8;
    some_composite.Bar = "hello";
    cmd.Parameters.Add(new NpgsqlParameter
    {
        ParameterName = "p1",
        Value = someComposite,
        DataTypeName = "some_composite_type"
    });
    cmd.ExecuteNonQuery();
}

// Reading composite as ExpandoObject
using (var cmd = new NpgsqlCommand("SELECT some_composite_column FROM some_table", conn))
using (var reader = cmd.ExecuteReader()) {
    reader.Read();
    var compositeValue = (dynamic)reader.GetValue(0);
    Console.WriteLine(compositeValue.Foo);
    Console.WriteLine(compositeValue.Bar);
}

あなたのCLR型のSomeEnumとSomeTypeが、フィールド/プロパティが含まれている限り、読み書きされるPostgreSQL型に対応し、すべてが、期待通りに動作します。既定の名前トランスレータが、使用されることに注意してください。（名前変換についての項目を参照して下さい）。

What is NodaTime?

既定では、PostgreSQLの日付/時刻型は、組み込み.NET型（DateTime、TimeSpan）にマッピングされています。残念ながら、これらの組込み型は、多くの欠点があります。NodaTimeライブラリは、これらの多くの問題を解決するために作成されました。そして、あなたのアプリケーションが、最も基本的な方法以外の何かで、日付と時刻を処理する場合、あなたは、それを使用することを考える必要があります。詳しくは、Jon Skeetによるこのブログ記事を読んでください。

NodaTimeの一般的な利点を越えて、NodaTime for PostgreSQLの日付/時刻マッピングには、次のような特別な利点があります。：

• NodaTimeは、LocalDate、LocalTimeとOffsetTimeのような、BCLから欠落して、いくつかの型を定義します。これらは、PostgreSQLのdate、time、およびtimetzに完全に一致しています。
• 期間は、TimeSpanよりも、PostgreSQLの間隔のマッピングに適しています。
• NodaTime型は、PostgreSQLのマイクロ秒精度を完全に表すことができます。そして、BCLの日付制限（1AD-9999AD）の範囲外の日付を表すことができます。

Setup

NodaTimeプラグインを使用するために、単純に、Npgsql.NodaTimeへの依存関係を追加して設定するだけです。：

using Npgsql;

// Place this at the beginning of your program to use NodaTime everywhere
 (recommended)
// NodaTime everywhere（推奨）を使うために、あなたのプログラムの始めに、これを置いてください。
NpgsqlConnection.GlobalTypeMapper.UseNodaTime();

// Or to temporarily use NodaTime on a single connection only:
// あるいは、単一の接続でのみで、NodaTimeを一時的に使用するには：
conn.TypeMapper.UseNodaTime();

Reading and Writing Values

一旦、プラグインが設定されると、あなたは、NodaTimeオブジェクトを透過的に読み書きできます。:

// Write NodaTime Instant to PostgreSQL "timestamp without time zone"
// NodaTime InstantをPostgreSQLに、"timestamp without time zone"を書き込みます。
using (var cmd = new NpgsqlCommand(@"INSERT INTO mytable (my_timestamp) VALUES (@p)", conn))
{
    cmd.Parameters.Add(new NpgsqlParameter("p", Instant.FromUtc(2011, 1, 1, 10, 30)));
    cmd.ExecuteNonQuery();
}

// Read timestamp back from the database as an Instant
// Instantとして、データベースからタイムスタンプを読み戻します。
using (var cmd = new NpgsqlCommand(@"SELECT my_timestamp FROM mytable", conn))
using (var reader = cmd.ExecuteReader())
{
    reader.Read();
    var instant = reader.GetFieldValue(0);
}

Mapping Table

Additional Notes

• プラグインは、自動的に、あなたのPostgreSQLセッションの設定されたタイムゾーンとの間で、タイムゾーン付きのタイムスタンプを変換します。;これは、代わりに、あなたのマシンのローカル・タイムゾーンを使用する、Npgsqlの既定のマッピングと異なります。timestamptz値と対話するとき、NodaTimeプラグイン動作は、標準のPostgreSQL動作と一致します。
• タイムスタンプや日付の無限値を読み書きするために、Convert Infinity DateTime接続文字列パラメーターをtrueに設定し、MaxValue / MinValueを読み書きします。