# pg_array.rb

Path: | lib/sequel/extensions/pg_array.rb
Last Update: | Sun May 19 07:59:58 +0000 2013

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), 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]))

If you would like to use PostgreSQL arrays in your model objects, you probably want to modify the schema parsing/typecasting so that it recognizes and correctly handles the arrays, which you can do by:

      DB.extension :pg_array

If you are not using the native postgres adapter, you probably also want to use the 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.register with the appropriate arguments to automatically set up a handler for the array type.

For example, if you add support for a scalar custom type named foo which uses OID 1234, and you want to add support for the foo[] type, which uses type OID 4321, you need to do:

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

Sequel::Postgres::PGArray.register has many additional options and should be able to handle most PostgreSQL array types.

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.

### Required files

delegate json adapters/utils/pg_types

[Validate]