123456789_123456789_123456789_123456789_123456789_

pg

* home

https://github.com/ged/ruby-pg

* docs

http://deveiate.org/code/pg/README_md.html (English) , https://deveiate.org/code/pg/README_ja_md.html (Japanese)

* clog

link:/CHANGELOG.md

Join the chat at https://gitter.im/ged/ruby-pg

Description

Pg is the Ruby interface to the PostgreSQL RDBMS. It works with PostgreSQL 10 and later.

A small example usage:

#!/usr/bin/env ruby

require 'pg'

# Output a table of current connections to the DB
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

See the ::PG::Connection class for query methods and the ::PG::Result class for information on working with the results of a query.

Build Status

!Build Status Github Actions !Binary gems !Build Status Appveyor

Requirements

How To Install

Install via RubyGems:

gem install pg

This installs the binary gem, specific to the running platform by default.

Binary gem

The binary gems don't depend on the libpq package on the running system. They have libpq builtin.

The gems for platform x86_64-linux and aarch64-linux run on Alpine Linux, but require the package gcompat, while the native gems for platform *-linux-musl work without that dependency.

There is one use case the binary gems don't support: Retrieval of connection options from LDAP. To support this libldap would be necessary, but it has a lot of dependencies. It doesn't seem to be a widely used feature and that it's worth to support it. If it's necessary, the source gem can be forced.

Source gem

The source gem can be forced by:

gem uninstall pg --all
gem install pg --platform ruby

You may need to specify the path to the 'pg_config' program installed with Postgres:

gem install pg -- --with-pg-config=<path to pg_config>

If you're installing via Bundler, you can provide compile hints like so:

bundle config build.pg --with-pg-config=<path to pg_config>

Bundler

To make sure, the necessary platforms and the source gem are fetched by bundler, they can be added like so

bundle lock --add-platform x86_64-linux
bundle lock --add-platform arm64-darwin
bundle lock --add-platform x64-mingw-ucrt
bundle lock --add-platform ruby
bundle package --all-platforms

A re-run of bundle package is also necessary after bundle update, in order to retrieve the new specific gems of all platforms.

If the binary gems don't work for some reason, it's easy to force the usage of the source gem in the Gemfile:

gem "pg", force_ruby_platform: true

More

See README-OS_X.rdoc for more information about installing under MacOS X, and README-Windows.rdoc for Windows build/installation instructions.

There's also a Google+ group and a mailing list if you get stuck, or just want to chat about something.

If you want to install as a signed gem, the public certs of the gem signers can be found in the certs directory of the repository.

Versioning

We tag and release gems according to the Semantic Versioning principle.

As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency 'pg', '~> 1.0'

Type Casts

Pg can optionally type cast result values and query parameters in Ruby or native C code. This can speed up data transfers to and from the database, because String allocations are reduced and conversions in (slower) Ruby code can be omitted.

Very basic type casting can be enabled by:

conn.type_map_for_results = PG::BasicTypeMapForResults.new conn
# ... this works for result value mapping:
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
# ... and this for param value mapping:
conn.exec_params("SELECT $1::text, $2::text, $3::text", [1, 1.23, [2,3]]).values
    # => [["1", "1.2300000000000000E+00", "{2,3}"]]

But Pg's type casting is highly customizable. That's why it's divided into 2 layers:

Encoders / Decoders (ext/pg_*coder.c, lib/pg/*coder.rb)

This is the lower layer, containing encoding classes that convert Ruby objects for transmission to the DBMS and decoding classes to convert received data back to Ruby objects. The classes are namespaced according to their format and direction in ::PG::TextEncoder, ::PG::TextDecoder, ::PG::BinaryEncoder and ::PG::BinaryDecoder.

It is possible to assign a type OID, format code (text or binary) and optionally a name to an encoder or decoder object. It's also possible to build composite types by assigning an element encoder/decoder. ::PG::Coder objects can be used to set up a ::PG::TypeMap or alternatively to convert single values to/from their string representation.

The following PostgreSQL column types are supported by ruby-pg (TE = Text Encoder, TD = Text Decoder, BE = Binary Encoder, BD = Binary Decoder):