A git mirror of the 'pg' gem.
C Ruby
Clone or download
larskanis Move "git ls-files" before "hg manifest"
Although hg is the canonnical repository, git-ls-files fails much faster.
Therefore in a git repo this delayed rake operations unnecessary.
Latest commit 884eb9c Aug 5, 2018
Permalink
Failed to load latest commit information.
certs Replace old expired gem-signing key with my current one Jan 10, 2018
ext Rename pg_warning() to pg_deprecated() Aug 5, 2018
lib Set VERSION to 1.1.0.pre20180730171000 Jul 30, 2018
misc Consistency fixes for file headers/permissions. Jan 24, 2018
sample Consistency fixes for file headers/permissions. Jan 24, 2018
spec PG::Tuple: Better describe spec about cleared result. Jul 31, 2018
.gems Update dependencies to latest versions Mar 13, 2017
.gemtest Converted to Hoe Oct 7, 2011
.hgignore Bunp minor version, update history, fix manifest/ignore files Jun 12, 2017
.hgsigs Added signature for changeset fef434914848 Jan 10, 2018
.hgtags Added tag v1.0.0 for changeset 9a388d1023ec Jan 10, 2018
.hoerc Add a way to disable the deprecation warning. Jun 13, 2017
.irbrc Updated build system Jan 3, 2010
.pryrc Rearranging classes under the PG namespace to be a better Ruby citizen Jan 25, 2012
.tm_properties Eliminate use of deprecated PGError constant from specs Jun 12, 2017
.travis.yml Remove rbx-3 from travis-ci, because we don't aim to support it any l… Jan 4, 2018
BSDL Update copyright year, license files Aug 20, 2016
Contributors.rdoc Update Rafał Bigaj's email address in Contributors.rdoc at his request Oct 1, 2012
Gemfile Add gem cert, trying out gemspec-based setup. Jan 31, 2016
History.rdoc Add notice about PG_SKIP_DEPRECATION_WARNING to History.md Aug 5, 2018
LICENSE Updated/simplified authors/license sections of the README, API doc cl… Jan 25, 2012
Manifest.txt Replace Manifest.txt by a generated file list Jul 30, 2018
POSTGRES fix cross compilation of win32 binary gem, fix mixed case file naming Jan 27, 2012
README-OS_X.rdoc More case-corrections Jan 27, 2012
README-Windows.rdoc Update README-Windows in regards to rake-compiler-dock. Jun 11, 2015
README.ja.rdoc Update READMEs Feb 27, 2013
README.rdoc Add SemVer and PVC to README Apr 21, 2018
Rakefile Move "git ls-files" before "hg manifest" Aug 5, 2018
Rakefile.cross Enable parallel cross build of ruby-pg's C-files Jul 30, 2018
appveyor.yml Appveyor: Add ruby-head to test matrix Dec 24, 2017
pg.gemspec Replace Manifest.txt by a generated file list Jul 30, 2018

README.rdoc

pg

home

bitbucket.org/ged/ruby-pg

mirror

github.com/ged/ruby-pg

docs

deveiate.org/code/pg

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

Description

Pg is the Ruby interface to the PostgreSQL RDBMS.

It works with PostgreSQL 9.2 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

Build Status

Build Status
Travis-CI Build Status Appveyor

Requirements

  • Ruby 2.2 or newer

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

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

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'

How To Install

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.

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.

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.

PG::TypeMap and derivations (ext/pg_type_map*.c, lib/pg/type_map*.rb)

A TypeMap defines which value will be converted by which encoder/decoder. There are different type map strategies, implemented by several derivations of this class. They can be chosen and configured according to the particular needs for type casting. The default type map is PG::TypeMapAllStrings.

A type map can be assigned per connection or per query respectively per result set. Type maps can also be used for COPY in and out data streaming. See PG::Connection#copy_data .

Contributing

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>.

Copying

Copyright © 1997-2016 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/about/license.txt or the BSDL 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.

Acknowledgments

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.