pg 0.18.1 → 1.5.6

data/Manifest.txt

@@ -1,6 +1,5 @@
 .gemtest
 BSDL
-ChangeLog
 Contributors.rdoc
 History.rdoc
 LICENSE
@@ -26,9 +25,11 @@ ext/pg_coder.c
 ext/pg_connection.c
 ext/pg_copy_coder.c
 ext/pg_errors.c
+ext/pg_record_coder.c
 ext/pg_result.c
 ext/pg_text_decoder.c
 ext/pg_text_encoder.c
+ext/pg_tuple.c
 ext/pg_type_map.c
 ext/pg_type_map_all_strings.c
 ext/pg_type_map_by_class.c
@@ -36,13 +37,14 @@ ext/pg_type_map_by_column.c
 ext/pg_type_map_by_mri_type.c
 ext/pg_type_map_by_oid.c
 ext/pg_type_map_in_ruby.c
-ext/util.c
-ext/util.h
+ext/pg_util.c
+ext/pg_util.h
 ext/vc/pg.sln
 ext/vc/pg_18/pg.vcproj
 ext/vc/pg_19/pg_19.vcproj
 lib/pg.rb
 lib/pg/basic_type_mapping.rb
+lib/pg/binary_decoder.rb
 lib/pg/coder.rb
 lib/pg/connection.rb
 lib/pg/constants.rb
@@ -50,31 +52,16 @@ lib/pg/exceptions.rb
 lib/pg/result.rb
 lib/pg/text_decoder.rb
 lib/pg/text_encoder.rb
+lib/pg/tuple.rb
 lib/pg/type_map_by_column.rb
-sample/array_insert.rb
-sample/async_api.rb
-sample/async_copyto.rb
-sample/async_mixed.rb
-sample/check_conn.rb
-sample/copyfrom.rb
-sample/copyto.rb
-sample/cursor.rb
-sample/disk_usage_report.rb
-sample/issue-119.rb
-sample/losample.rb
-sample/minimal-testcase.rb
-sample/notify_wait.rb
-sample/pg_statistics.rb
-sample/replication_monitor.rb
-sample/test_binary_values.rb
-sample/wal_shipper.rb
-sample/warehouse_partitions.rb
 spec/data/expected_trace.out
 spec/data/random_binary_data
 spec/helpers.rb
 spec/pg/basic_type_mapping_spec.rb
 spec/pg/connection_spec.rb
+spec/pg/connection_sync_spec.rb
 spec/pg/result_spec.rb
+spec/pg/tuple_spec.rb
 spec/pg/type_map_by_class_spec.rb
 spec/pg/type_map_by_column_spec.rb
 spec/pg/type_map_by_mri_type_spec.rb

data/README-Windows.rdoc

@@ -2,9 +2,9 @@
 
 In order to build this extension on MS Windows you will need a couple things.
 
-First, a compiler. For the one click installer this means you should either
-use VC++ 6.0 or the compiler that comes with cygwin or mingw if you're
-building on that platform.
+First, a compiler. For the one click installer this means you should use
+the DevKit or the compiler that comes with cygwin if you're building on that
+platform.
 
 If you've built Ruby yourself, you should use the same compiler to build
 this library that you used to build Ruby.
@@ -29,39 +29,28 @@ Adjust your path accordingly. BE SURE TO USE THE SHORT PATH NAMES! If you
 try to use a path with spaces in it, the nmake.exe program will choke.
 
 
-== Cross compiling for mswin32
+== Building binary 'pg' gems for MS Windows
 
-Using rake-compiler a cross compiled pg gem can be build on a Linux or MacOS X
-host for the win32 platform. The generated gem is statically linked against
-libpq and libssl. OpenSSL and PostgreSQL are downloaded and compiled from the
-sources. There are no runtime dependencies to any but the standard Windows
-DLLs.
+Binary gems for windows can be built on Linux, OS-X and even on Windows
+with the help of docker. This is how regular windows gems are built for
+rubygems.org .
 
-Install mingw32 using the instructions in rake-compiler's README.
-For Debian/Ubuntu it is <tt>apt-get install gcc-mingw32</tt> .
-Use ruby-1.8.7 for the following commands.
+To do this, install boot2docker {on Windows}[https://github.com/boot2docker/windows-installer/releases]
+or {on OS X}[https://github.com/boot2docker/osx-installer/releases] and make
+sure it is started. A native Docker installation is best on Linux.
 
-Download and cross compile ruby 1.8 and 1.9 for win32 with:
+Then run:
 
-	rake-compiler cross-ruby VERSION=1.8.7-p352
-	rake-compiler cross-ruby VERSION=1.9.2-p290
+	rake gem:windows
 
-Download and cross compile pg for win32:
-
-	rake cross native gem
-
-or with custom versions:
-
-	rake cross native gem RUBY_CC_VERSION=1.8.7:1.9.2 \
-	    OPENSSL_VERSION=1.0.0e POSTGRESQL_VERSION=9.1.1
-
-If everything works, there should be pg-VERSION-x86-mingw32.gem in the pkg
-directory.
+This will download a docker image suited for building windows gems, and it
+will download and build OpenSSL and PostgreSQL. Finally the gem is built
+containing binaries for all supported ruby versions.
 
 
 == Reporting Problems
 
-If you have any problems you can submit them via
-[the project's issue-tracker][bitbucket]. And submit questions, problems, or
+If you have any problems you can submit them via {the project's
+issue-tracker}[https://github.com/ged/ruby-pg/issues]. And submit questions, problems, or
 solutions, so that it can be improved.
 

data/README.ja.md

@@ -0,0 +1,300 @@
+# pg
+
+* ホーム :: https://github.com/ged/ruby-pg
+* ドキュメント :: http://deveiate.org/code/pg （英語）、 https://deveiate.org/code/pg/README_ja_md.html （日本語）
+* 変更履歴 :: link:/History.md
+
+[![https://gitter.im/ged/ruby-pg
+でチャットに参加](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/ged/ruby-pg?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+
+## 説明
+
+Pgは[PostgreSQL
+RDBMS](http://www.postgresql.org/)へのRubyのインターフェースです。[PostgreSQL
+9.3以降](http://www.postgresql.org/support/versioning/)で動作します。
+
+簡単な使用例は次の通りです。
+```ruby
+  #!/usr/bin/env ruby
+
+  require 'pg'
+
+  # データベースへの現在の接続を表に出力します
+  conn = PG.connect( dbname: 'sales' )
+  conn.exec( "SELECT * FROM pg_stat_activity" ) do |result|
+    puts "     PID | User             | Query"
+    result.each do |row|
+      puts " %7d | %-16s | %s " %
+        row.values_at('pid', 'usename', 'query')
+    end
+  end
+```
+
+## ビルド状況
+
+[![Github
+Actionsのビルド状況](https://github.com/ged/ruby-pg/actions/workflows/source-gem.yml/badge.svg?branch=master)](https://github.com/ged/ruby-pg/actions/workflows/source-gem.yml)
+[![バイナリgem](https://github.com/ged/ruby-pg/actions/workflows/binary-gems.yml/badge.svg?branch=master)](https://github.com/ged/ruby-pg/actions/workflows/binary-gems.yml)
+[![Appveyorのビルド状況](https://ci.appveyor.com/api/projects/status/gjx5axouf3b1wicp?svg=true)](https://ci.appveyor.com/project/ged/ruby-pg-9j8l3)
+
+
+## 要件
+
+* Ruby 2.5かそれより新しいバージョン
+* PostgreSQL 9.3.xかそれ以降のバージョン（ヘッダー付属のもの、例えば-devの名前のパッケージ）。
+
+それより前のバージョンのRubyやPostgreSQLでも通常は同様に動作しますが、定期的なテストはされていません。
+
+
+## バージョン管理
+
+[セマンティックバージョニング](http://semver.org/)の原則にしたがってgemをタグ付けしてリリースしています。
+
+この方針の結果として、2つの数字を指定する[悲観的バージョン制約](http://guides.rubygems.org/patterns/#pessimistic-version-constraint)を使ってこのgemへの依存関係を指定することができます（またそうすべきです）。
+
+例えば次の通りです。
+
+```ruby
+  spec.add_dependency 'pg', '~> 1.0'
+```
+
+## インストール方法
+
+RubyGemsを経由してインストールするには以下とします。
+
+    gem install pg
+
+Postgresと一緒にインストールされた'pg_config'プログラムへのパスを指定する必要があるかもしれません。
+
+    gem install pg -- --with-pg-config=<path to pg_config>
+
+Bundlerを介してインストールした場合は次のようにコンパイルのためのヒントを与えられます。
+
+    bundle config build.pg --with-pg-config=<path to pg_config>
+
+MacOS Xへインストールする詳しい情報については README-OS_X.rdoc を、Windows用のビルドやインストールの説明については
+README-Windows.rdoc を参照してください。
+
+詰まったときやただ何か喋りたいときのために[Google+グループ](http://goo.gl/TFy1U)と[メーリングリスト](http://groups.google.com/group/ruby-pg)もあります。
+
+署名されたgemとしてインストールしたい場合は、リポジトリの[`certs`ディレクトリ](https://github.com/ged/ruby-pg/tree/master/certs)にgemの署名をする公開証明書があります。
+
+
+## 型変換
+
+Pgでは任意でRubyと素のCコードにある結果の値やクエリ引数の型変換ができます。
+こうすることでデータベースとのデータの往来を加速させられます。
+なぜなら文字列のアロケーションが減り、（比較的遅い）Rubyのコードでの変換部分が省かれるからです。
+
+とても基本的な型変換は次のようにできます。
+```ruby
+    conn.type_map_for_results = PG::BasicTypeMapForResults.new conn
+    # ……これは結果の値の対応付けに作用します。
+    conn.exec("select 1, now(), '{2,3}'::int[]").values
+        # => [[1, 2014-09-21 20:51:56 +0200, [2, 3]]]
+
+    conn.type_map_for_queries = PG::BasicTypeMapForQueries.new conn
+    # ……そしてこれは引数値の対応付けのためのものです。
+    conn.exec_params("SELECT $1::text, $2::text, $3::text", [1, 1.23, [2,3]]).values
+        # => [["1", "1.2300000000000000E+00", "{2,3}"]]
+```
+
+しかしPgの型変換はかなり調整が効きます。2層に分かれているのがその理由です。
+
+### エンコーダーとデコーダー (ext/pg_*coder.c, lib/pg/*coder.rb)
+
+こちらはより低層で、DBMSへ転送するためにRubyのオブジェクトを変換するエンコーディングクラスと、取得してきたデータをRubyのオブジェクトに変換し戻すデコーディングクラスが含まれています。
+クラスはそれぞれの形式によって名前空間 PG::TextEncoder, PG::TextDecoder, PG::BinaryEncoder, そして
+PG::BinaryDecoder に分かれています。
+
+エンコーダーないしデコーダーオブジェクトにOIDデータ型や形式コード（テキストないしバイナリ）や任意で名前を割り当てることができます。
+要素のエンコーダーないしデコーダーを割り当てることによって複合型を構築することもできます。
+PG::Coder オブジェクトは PG::TypeMap をセットアップしたり、その代わりに単一の値と文字列表現とを相互に変換したりするのに使えます。
+
+ruby-pgでは以下のPostgreSQLカラム型に対応しています（TE = Text Encoder、TD = Text Decoder、BE =
+Binary Encoder、BD = Binary Decoder）。
+
+* Integer:
+  [TE](rdoc-ref:PG::TextEncoder::Integer)、[TD](rdoc-ref:PG::TextDecoder::Integer)、[BD](rdoc-ref:PG::BinaryDecoder::Integer)
+  💡
+  リンクがないでしょうか。[こちら](https://deveiate.org/code/pg/README_ja_md.html#label-E5-9E-8B-E5-A4-89-E6-8F-9B)を代わりに見てください
+  💡
+    * BE:
+      [Int2](rdoc-ref:PG::BinaryEncoder::Int2)、[Int4](rdoc-ref:PG::BinaryEncoder::Int4)、[Int8](rdoc-ref:PG::BinaryEncoder::Int8)
+* Float:
+  [TE](rdoc-ref:PG::TextEncoder::Float)、[TD](rdoc-ref:PG::TextDecoder::Float)、[BD](rdoc-ref:PG::BinaryDecoder::Float)
+    * BE: [Float4](rdoc-ref:PG::BinaryEncoder::Float4),
+      [Float8](rdoc-ref:PG::BinaryEncoder::Float8)
+* Numeric:
+  [TE](rdoc-ref:PG::TextEncoder::Numeric)、[TD](rdoc-ref:PG::TextDecoder::Numeric)
+* Boolean:
+  [TE](rdoc-ref:PG::TextEncoder::Boolean)、[TD](rdoc-ref:PG::TextDecoder::Boolean)、[BE](rdoc-ref:PG::BinaryEncoder::Boolean)、[BD](rdoc-ref:PG::BinaryDecoder::Boolean)
+* String:
+  [TE](rdoc-ref:PG::TextEncoder::String)、[TD](rdoc-ref:PG::TextDecoder::String)、[BE](rdoc-ref:PG::BinaryEncoder::String)、[BD](rdoc-ref:PG::BinaryDecoder::String)
+* Bytea:
+  [TE](rdoc-ref:PG::TextEncoder::Bytea)、[TD](rdoc-ref:PG::TextDecoder::Bytea)、[BE](rdoc-ref:PG::BinaryEncoder::Bytea)、[BD](rdoc-ref:PG::BinaryDecoder::Bytea)
+* Base64:
+  [TE](rdoc-ref:PG::TextEncoder::ToBase64)、[TD](rdoc-ref:PG::TextDecoder::FromBase64)、[BE](rdoc-ref:PG::BinaryEncoder::FromBase64)、[BD](rdoc-ref:PG::BinaryDecoder::ToBase64)
+* Timestamp:
+    * TE:
+      [現地時間](rdoc-ref:PG::TextEncoder::TimestampWithoutTimeZone)、[UTC](rdoc-ref:PG::TextEncoder::TimestampUtc)、[タイムゾーン付き](rdoc-ref:PG::TextEncoder::TimestampWithTimeZone)
+    * TD:
+      [現地時間](rdoc-ref:PG::TextDecoder::TimestampLocal)、[UTC](rdoc-ref:PG::TextDecoder::TimestampUtc)、[UTCから現地時間へ](rdoc-ref:PG::TextDecoder::TimestampUtcToLocal)
+    * BE:
+      [現地時間](rdoc-ref:PG::BinaryEncoder::TimestampLocal)、[UTC](rdoc-ref:PG::BinaryEncoder::TimestampUtc)
+    * BD:
+      [現地時間](rdoc-ref:PG::BinaryDecoder::TimestampLocal)、[UTC](rdoc-ref:PG::BinaryDecoder::TimestampUtc)、[UTCから現地時間へ](rdoc-ref:PG::BinaryDecoder::TimestampUtcToLocal)
+* 日付：[TE](rdoc-ref:PG::TextEncoder::Date)、[TD](rdoc-ref:PG::TextDecoder::Date)、[BE](rdoc-ref:PG::BinaryEncoder::Date)、[BD](rdoc-ref:PG::BinaryDecoder::Date)
+* JSONとJSONB:
+  [TE](rdoc-ref:PG::TextEncoder::JSON)、[TD](rdoc-ref:PG::TextDecoder::JSON)
+* Inet:
+  [TE](rdoc-ref:PG::TextEncoder::Inet)、[TD](rdoc-ref:PG::TextDecoder::Inet)
+* Array:
+  [TE](rdoc-ref:PG::TextEncoder::Array)、[TD](rdoc-ref:PG::TextDecoder::Array)
+* 複合型（「行」や「レコード」などとも言います）：[TE](rdoc-ref:PG::TextEncoder::Record)、[TD](rdoc-ref:PG::TextDecoder::Record)
+
+カラム型として使われていませんが、以下のテキスト形式とバイナリ形式もエンコードできます。
+
+* COPYの入出力データ：[TE](rdoc-ref:PG::TextEncoder::CopyRow)、[TD](rdoc-ref:PG::TextDecoder::CopyRow),
+  [BE](rdoc-ref:PG::BinaryEncoder::CopyRow),
+  [BD](rdoc-ref:PG::BinaryDecoder::CopyRow)
+* SQL文字列に挿入するリテラル：[TE](rdoc-ref:PG::TextEncoder::QuotedLiteral)
+* SQLの識別子:
+  [TE](rdoc-ref:PG::TextEncoder::Identifier)、[TD](rdoc-ref:PG::TextDecoder::Identifier)
+
+### PG::TypeMap とその派生 (ext/pg_type_map*.c, lib/pg/type_map*.rb)
+
+TypeMapはエンコーダーまたはデコーダーのどちらによってどの値を変換するかを定義します。
+様々な型の対応付け戦略があるので、このクラスにはいくつかの派生が実装されています。
+型変換の特有の需要に合わせてそれらの派生から選んで調整を加えることができます。
+既定の型の対応付けは PG::TypeMapAllStrings です。
+
+型の対応付けは、結果の集合それぞれに対し、接続毎ないしクエリ毎に割り当てることができます。
+型の対応付けはCOPYの入出力データストリーミングでも使うことができます。
+PG::Connection#copy_data を参照してください。
+
+以下の基底となる型の対応付けが使えます。
+
+* PG::TypeMapAllStrings - 全ての値と文字列について相互にエンコードとデコードを行います（既定）
+* PG::TypeMapByClass - 送信する値のクラスに基づいてエンコーダーを選択します
+* PG::TypeMapByColumn - カラムの順番によってエンコーダーとデコーダーを選択します
+* PG::TypeMapByOid - PostgreSQLのOIDデータ型によってデコーダーを選択します
+* PG::TypeMapInRuby - Rubyで独自の型の対応付けを定義します
+
+以下の型の対応付けは PG::BasicTypeRegistry 由来の型の対応付けが入った状態になっています。
+
+* PG::BasicTypeMapForResults - PG::TypeMapByOid
+  によくあるPostgreSQLカラム型用にデコーダーが入った状態になっています
+* PG::BasicTypeMapBasedOnResult - PG::TypeMapByOid
+  によくあるPostgreSQLカラム型用のエンコーダーが入った状態になっています
+* PG::BasicTypeMapForQueries - PG::TypeMapByClass
+  によくあるRubyの値クラス用にエンコーダーが入った状態になっています
+
+
+## スレッド対応
+
+PGには個々のスレッドが別々の PG::Connection オブジェクトを同時に使えるという点でスレッド安全性があります。
+しかし1つ以上のスレッドから同時にPgのオブジェクトにアクセスすると安全ではありません。
+そのため必ず、毎回新しいスレッドを作るときに新しいデータベースサーバー接続を開くか、スレッド安全性のある方法で接続を管理するActiveRecordのようなラッパーライブラリを使うようにしてください。
+
+以下のようなメッセージが標準エラー出力に表示された場合、恐らく複数のスレッドが1つの接続を使っています。
+
+    message type 0x31 arrived from server while idle
+    message type 0x32 arrived from server while idle
+    message type 0x54 arrived from server while idle
+    message type 0x43 arrived from server while idle
+    message type 0x5a arrived from server while idle
+
+
+## Fiber IOスケジューラー対応
+
+pg-1.3.0以降で、PgはRuby-3.0で導入された`Fiber.scheduler`に完全に対応しています。
+Windowsでは、`Fiber.scheduler`対応はRuby-3.1以降で使えます。
+`Fiber.scheduler`が走らせているスレッドに登録されている場合、起こりうる全てのブロッキングIO操作はそのスケジューラーを経由します。
+同期的であったりブロックしたりするメソッド呼び出しについてもpgが内部的に非同期のlibpqインターフェースを使っているのはそれが理由です。
+またlibpqの組み込み関数に代えてRubyのDNS解決を使っています。
+
+内部的にPgは常にlibpqのノンブロッキング接続モードを使います。
+それからブロッキングモードで走っているように振舞いますが、もし`Fiber.scheduler`が登録されていれば全てのブロッキングIOはそのスケジューラーを通じてRubyで制御されます。
+`PG::Connection.setnonblocking(true)`が呼ばれたらノンブロッキング状態が有効になったままになりますが、それ以降のブロッキング状態の制御が無効になるので、呼び出しているプログラムはブロッキング状態を自力で制御しなければなりません。
+
+この規則の1つの例外には、`PG::Connection#lo_create`や外部ライブラリを使う認証メソッド（GSSAPI認証など）のような、大きめのオブジェクト用のメソッドがあります。これらは`Fiber.scheduler`と互換性がないため、ブロッキング状態は登録されたIOスケジューラに渡されません。つまり操作は適切に実行されますが、IO待ち状態に別のIOを扱うFiberから使用を切り替えてくることができなくなります。
+
+
+## Ractor対応
+
+pg-1.5.0以降で、PgはRuby-3.0で導入されたRactorと完全な互換性があります。
+型エンコーダーないしデコーダー、及び型の対応付けが`Ractor.make_shareable`により凍結されている場合、これらをractor間で共有できます。
+また凍結された PG::Result と PG::Tuple オブジェクトも共有できます。
+少なくとも全ての凍結されたオブジェクト（ただし PG::Connection
+を除く）はPostgreSQLサーバーとのやり取りをしたり取得されたデータを読むのに使えます。
+
+PG::Connection は共有できません。個々の接続を確立するために、それぞれのRactor内で作られなければなりません。
+
+
+## 貢献
+
+バグを報告したり機能を提案したりGitでソースをチェックアウトしたりするには[プロジェクトページをご確認ください](https://github.com/ged/ruby-pg)。
+
+ソースをチェックアウトしたあとは全ての依存関係をインストールします。
+
+    $ bundle install
+
+拡張ファイル、パッケージファイル、テストデータベースを一掃するには、このコマンドを走らせてください。PostgreSQLのバージョンも切り替わります。
+
+    $ rake clean
+
+拡張をコンパイルするには次のようにします。
+
+    $ rake compile
+
+`pg_config --bindir`が指すPostgreSQLのバージョンでテストやスペックを走らせるには次のようにします。
+
+    $ rake test
+
+あるいは特定のPostgreSQLのバージョンで、ファイル中の行番号を使って特定のテストを走らせるには次のようにします。
+
+    $ PATH=/usr/lib/postgresql/14/bin:$PATH rspec -Ilib -fd spec/pg/connection_spec.rb:455
+
+APIドキュメントを生成するには次のようにします。
+
+    $ rake docs
+
+必ず全てのバグと新機能についてテストを使って検証してください。
+
+現在のメンテナはMichael Granger <ged@FaerieMUD.org>とLars Kanis
+<lars@greiz-reinsdorf.de>です。
+
+
+## 著作権
+
+Copyright (c) 1997-2022 by the authors.
+
+* Jeff Davis <ruby-pg@j-davis.com>
+* Guy Decoux (ts) <decoux@moulon.inra.fr>
+* Michael Granger <ged@FaerieMUD.org>
+* Lars Kanis <lars@greiz-reinsdorf.de>
+* Dave Lee
+* Eiji Matsumoto <usagi@ruby.club.or.jp>
+* Yukihiro Matsumoto <matz@ruby-lang.org>
+* Noboru Saitou <noborus@netlab.jp>
+
+You may redistribute this software under the same terms as Ruby itself; see
+https://www.ruby-lang.org/en/about/license.txt or the BSDL file in the
+source for details.
+（参考訳：このソフトウェアはRuby自体と同じ条件の元で再配布することができます。詳細については
+https://www.ruby-lang.org/en/about/license.txt やソース中のBSDLファイルを参照してください）
+
+Portions of the code are from the PostgreSQL project, and are distributed "
+"under the terms of the PostgreSQL license, included in the file POSTGRES.
+（参考訳：コードの一部はPostgreSQLプロジェクトから来ており、PostgreSQLの使用許諾の条件の元で配布されます。ファイルPOSTGRESに含まれています）
+
+Portions copyright LAIKA, Inc.
+
+
+## 謝辞
+
+長年にわたって貢献してくださった方々については Contributors.rdoc を参照してください。
+
+ruby-listとruby-devメーリングリストの方々に感謝します。またPostgreSQLを開発された方々へも謝意を表します。