Last Modified
  2013-08-05 18:02:53 +0000
Requires
  - delegate
  - json
  - adapters/utils/pg_types

## Description

The pg_array extension adds support for Sequel to handle PostgreSQL's array types.

This extension integrates with Sequel's native postgres adapter, so that when array fields are retrieved, they are parsed and returned as instances of Sequel::Postgres::PGArray. PGArray is a DelegateClass of Array, so it mostly acts like an array, but not completely (is_a?(Array) is false). If you want the actual array, you can call PGArray#to_a. This is done so that Sequel does not treat a PGArray like an Array by default, which would cause issues.

In addition to the parsers, this extension comes with literalizers for PGArray using the standard Sequel literalization callbacks, so they work with on all adapters.

To turn an existing Array into a PGArray:

    Sequel.pg_array(array)

If you have loaded the core_extensions extension, or you have loaded the core_refinements extension and have activated refinements for the file, you can also use Array#pg_array:

    array.pg_array

You can also provide a type, though it many cases it isn't necessary:

    Sequel.pg_array(array, :varchar) # or :integer, :"double precision", etc.
    array.pg_array(:varchar) # or :integer, :"double precision", etc.

So if you want to insert an array into an integer[] database column:

    DB[:table].insert(:column=>Sequel.pg_array([1, 2, 3]))

To use this extension, first load it into your Sequel::Database instance:

    DB.extension :pg_array

If you are not using the native postgres adapter and are using array types as model column values you probably should use the pg_typecast_on_load plugin in the model, and set it to typecast the array column(s) on load.

This extension by default includes handlers for array types for all scalar types that the native postgres adapter handles. It also makes it easy to add support for other array types. In general, you just need to make sure that the scalar type is handled and has the appropriate converter installed in Sequel::Postgres::PG_TYPES under the appropriate type OID. Then you can call Sequel::Postgres::PGArray::DatabaseMethods#register_array_type to automatically set up a handler for the array type. So if you want to support the foo[] type (assuming the foo type is already supported):

    DB.register_array_type('foo')

You can also register array types on a global basis using Sequel::Postgres::PGArray.register. In this case, you'll have to specify the type oids:

    Sequel::Postgres::PGArray.register('foo', :oid=>4321, :scalar_oid=>1234)

Both Sequel::Postgres::PGArray::DatabaseMethods#register_array_type and Sequel::Postgres::PGArray.register support many options to customize the array type handling. See the Sequel::Postgres::PGArray.register method documentation.

If you want an easy way to call PostgreSQL array functions and operators, look into the pg_array_ops extension.

This extension requires both the json and delegate libraries.

## Additional License

PGArray::Parser code was translated from Javascript code in the node-postgres project and has the following additional license:

Copyright (c) 2010 Brian Carlson (brian.m.carlson@gmail.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.