home

bitbucket.org/ged/ruby-pg

mirror

github.com/ged/ruby-pg

docs

deveiate.org/code/pg

Pg is the Ruby interface to the PostgreSQL RDBMS.

It works with PostgreSQL 8.4 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('procpid', 'usename', 'current_query')
  end
end

<img src=“https://travis-ci.org/ged/ruby-pg.png?branch=master” alt=“Build Status” />

• Ruby 1.9.3-p392, or 2.0.0-p0.

• PostgreSQL 8.4.x or later (with headers, -dev packages, etc).

It may work with earlier versions of Ruby/PostgreSQL as well, but those are not regularly tested.

Install via RubyGems:

gem install pg

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>

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.

Pg can optionally type cast result and query parameters in Ruby or native C code. This can speed up data transfers to and from the database by avoiding String allocations for each value.

Standard type casting can be enabled by:

conn.type_mapping = PG::BasicTypeMapping.new conn
# this works for result value mapping:
conn.exec("select 1, now(), '{2,3}'::int[]").values
    # => [[1, 2014-04-17 22:58:01 +0200, [2, 3]]]
# ... and for param value mapping:
conn.exec_params("SELECT $1::text, $2::text, $3::text", [1, Time.now, [2,3]]).values
    # => [["1", "2014-04-17 22:58:47.101513+02", "{2,3}"]]

Pg’s type casting is highly customizable. That’s why it’s divided into 4 layers:

This is the lowest layer, containing encoding functions that convert Ruby objects for transmission to the DBMS and decoding functions to convert received data back to Ruby objects. The C-functions are reachable from Ruby in namespaces PG::TextEncoder, PG::TextDecoder, PG::BinaryEncoder and PG::BinaryDecoder. They can be assigned to a PG::Type object.

A PG::Type object binds an encoding and a decoding function, a type OID, format code (text or binary) and optionally a name together. A PG::CompositeType in addition defines the PG::Type that should be used for en-/decoding of it’s elements. Type objects can be used to convert single values to/from their string representation and to build PG::ColumnMapping objects.

A ColumnMapping combines multiple types together, suitable to convert the input or result values of a given query. ColumnMappings are in particular useful in conjunction with prepared statements, since they can be cached alongside with the statement handle.

A type mapping defines the logic to select which Ruby type is converted to which text/binary representation and OID for query params and vice versa for result values. It builds a ColumnMapping out of a given set of query parameters or a given PG::Result object. PG itself defines BasicTypeMapping, that could be extended or replaced in order to define customized conversion rules.

With Connection#type_mapping= a connection wide default type mapping can be set. A type mapping can also be used as alternative for parameters accepting PG::ColumnMapping. In both cases the a ColumnMapping is built on the fly, which is obviously somewhat slower than using a prepared or cached PG::ColumnMapping.

To report bugs, suggest features, or check out the source with Mercurial, check out the project page. If you prefer Git, there’s also a Github mirror.

After checking out the source, run:

$ rake newb

This task will install any missing dependencies, run the tests/specs, and generate the API documentation.

The current maintainers are Michael Granger <ged@FaerieMUD.org> and Lars Kanis <lars@greiz-reinsdorf.de>.

Copyright © 1997-2013 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 www.ruby-lang.org/en/LICENSE.txt or the LICENSE file in the source for details.

Portions of the code are from the PostgreSQL project, and are distributed under the terms of the PostgreSQL license, included in the file POSTGRES.

Portions copyright LAIKA, Inc.

See Contributors.rdoc for the many additional fine people that have contributed to this library over the years.

We are thankful to the people at the ruby-list and ruby-dev mailing lists. And to the people who developed PostgreSQL.