234 lines
10 KiB
Plaintext
234 lines
10 KiB
Plaintext
= pg
|
|
|
|
home :: https://github.com/ged/ruby-pg
|
|
docs :: http://deveiate.org/code/pg
|
|
clog :: link:/History.rdoc
|
|
|
|
{<img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/ged/ruby-pg">}[https://gitter.im/ged/ruby-pg?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge]
|
|
|
|
|
|
== Description
|
|
|
|
Pg is the Ruby interface to the {PostgreSQL RDBMS}[http://www.postgresql.org/].
|
|
|
|
It works with {PostgreSQL 9.3 and later}[http://www.postgresql.org/support/versioning/].
|
|
|
|
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
|
|
|
|
== Build Status
|
|
|
|
{<img src="https://github.com/ged/ruby-pg/actions/workflows/source-gem.yml/badge.svg?branch=master" alt="Build Status Github Actions" />}[https://github.com/ged/ruby-pg/actions/workflows/source-gem.yml]
|
|
{<img src="https://ci.appveyor.com/api/projects/status/gjx5axouf3b1wicp?svg=true" alt="Build Status Appveyor" />}[https://ci.appveyor.com/project/ged/ruby-pg-9j8l3]
|
|
{<img src="https://app.travis-ci.com/larskanis/ruby-pg.svg?branch=master" alt="Build Status" />}[https://app.travis-ci.com/larskanis/ruby-pg]
|
|
|
|
== Requirements
|
|
|
|
* Ruby 2.4 or newer
|
|
* PostgreSQL 9.3.x or later (with headers, -dev packages, etc).
|
|
|
|
It usually works 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}[http://semver.org/] principle.
|
|
|
|
As a result of this policy, you can (and should) specify a dependency on this gem using the {Pessimistic Version Constraint}[http://guides.rubygems.org/patterns/#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}[http://goo.gl/TFy1U] and a
|
|
{mailing list}[http://groups.google.com/group/ruby-pg] 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}[https://github.com/ged/ruby-pg/tree/master/certs]
|
|
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.
|
|
|
|
The following PostgreSQL column types are supported by ruby-pg (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] 💡 No links? Switch to {here}[https://deveiate.org/code/pg/README_rdoc.html#label-Type+Casts] 💡
|
|
* 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]
|
|
* 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: {local}[rdoc-ref:PG::TextEncoder::TimestampWithoutTimeZone], {UTC}[rdoc-ref:PG::TextEncoder::TimestampUtc], {with-TZ}[rdoc-ref:PG::TextEncoder::TimestampWithTimeZone]
|
|
* TD: {local}[rdoc-ref:PG::TextDecoder::TimestampLocal], {UTC}[rdoc-ref:PG::TextDecoder::TimestampUtc], {UTC-to-local}[rdoc-ref:PG::TextDecoder::TimestampUtcToLocal]
|
|
* BD: {local}[rdoc-ref:PG::BinaryDecoder::TimestampLocal], {UTC}[rdoc-ref:PG::BinaryDecoder::TimestampUtc], {UTC-to-local}[rdoc-ref:PG::BinaryDecoder::TimestampUtcToLocal]
|
|
* Date: {TE}[rdoc-ref:PG::TextEncoder::Date], {TD}[rdoc-ref:PG::TextDecoder::Date]
|
|
* JSON and 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]
|
|
* Composite Type (also called "Row" or "Record"): {TE}[rdoc-ref:PG::TextEncoder::Record], {TD}[rdoc-ref:PG::TextDecoder::Record]
|
|
|
|
The following text formats can also be encoded although they are not used as column type:
|
|
* COPY input and output data: {TE}[rdoc-ref:PG::TextEncoder::CopyRow], {TD}[rdoc-ref:PG::TextDecoder::CopyRow]
|
|
* Literal for insertion into SQL string: {TE}[rdoc-ref:PG::TextEncoder::QuotedLiteral]
|
|
* SQL-Identifier: {TE}[rdoc-ref:PG::TextEncoder::Identifier], {TD}[rdoc-ref:PG::TextDecoder::Identifier]
|
|
|
|
=== 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 .
|
|
|
|
The following base type maps are available:
|
|
* PG::TypeMapAllStrings - encodes and decodes all values to and from strings (default)
|
|
* PG::TypeMapByClass - selects encoder based on the class of the value to be sent
|
|
* PG::TypeMapByColumn - selects encoder and decoder by column order
|
|
* PG::TypeMapByOid - selects decoder by PostgreSQL type OID
|
|
* PG::TypeMapInRuby - define a custom type map in ruby
|
|
|
|
The following type maps are prefilled with type mappings from the PG::BasicTypeRegistry :
|
|
* PG::BasicTypeMapForResults - a PG::TypeMapByOid prefilled with decoders for common PostgreSQL column types
|
|
* PG::BasicTypeMapBasedOnResult - a PG::TypeMapByOid prefilled with encoders for common PostgreSQL column types
|
|
* PG::BasicTypeMapForQueries - a PG::TypeMapByClass prefilled with encoders for common Ruby value classes
|
|
|
|
|
|
== Contributing
|
|
|
|
To report bugs, suggest features, or check out the source with Git,
|
|
{check out the project page}[https://github.com/ged/ruby-pg].
|
|
|
|
After checking out the source, install all dependencies:
|
|
|
|
$ bundle install
|
|
|
|
Cleanup extension files, packaging files, test databases:
|
|
|
|
$ rake clean
|
|
|
|
Compile extension:
|
|
|
|
$ rake compile
|
|
|
|
Run tests/specs with PostgreSQL tools like `initdb` in the path:
|
|
|
|
$ PATH=$PATH:/usr/lib/postgresql/14/bin rake test
|
|
|
|
Or run a specific test with the line number:
|
|
|
|
$ PATH=$PATH:/usr/lib/postgresql/14/bin rspec -Ilib -fd spec/pg/connection_spec.rb:455
|
|
|
|
Generate the API documentation:
|
|
|
|
$ rake docs
|
|
|
|
Make sure, that all bugs and new features are verified by tests.
|
|
|
|
The current maintainers are Michael Granger <ged@FaerieMUD.org> and
|
|
Lars Kanis <lars@greiz-reinsdorf.de>.
|
|
|
|
|
|
== Copying
|
|
|
|
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.
|
|
|
|
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.
|