Last Modified
  2016-09-30 19:32:14 +0000
Requires
  - delegate
  - json
  - adapters/utils/pg_types

## Description

The pg_json extension adds support for Sequel to handle PostgreSQL's json type. It is slightly more strict than the PostgreSQL json type in that the object returned must be an array or object (PostgreSQL's json type considers plain numbers and strings as valid). This is because Sequel relies completely on the ruby JSON library for parsing, and ruby's JSON library does not accept the values.

This extension integrates with Sequel's native postgres adapter, so that when json fields are retrieved, they are parsed and returned as instances of Sequel::Postgres::JSONArray or Sequel::Postgres::JSONHash. JSONArray and JSONHash are DelegateClasses of Array and Hash, so they mostly act the same, but not completely (json_array.is_a?(Array) is false). If you want the actual array for a JSONArray, call JSONArray#to_a. If you want the actual hash for a JSONHash, call JSONHash#to_hash. This is done so that Sequel does not treat JSONArray and JSONHash like Array and Hash by default, which would cause issues.

To turn an existing Array or Hash into a JSONArray or JSONHash, use Sequel.pg_json:

    Sequel.pg_json(array)
    Sequel.pg_json(hash)

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_json and Hash#pg_json:

    array.pg_json
    hash.pg_json

So if you want to insert an array or hash into an json database column:

    DB[:table].insert(:column=>Sequel.pg_json([1, 2, 3]))
    DB[:table].insert(:column=>Sequel.pg_json({'a'=>1, 'b'=>2}))

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

    DB.extension :pg_json

If you are not using the native postgres adapter and are using json types as model column values you probably should use the pg_typecast_on_load plugin if the column values are returned as a string.

See the schema modification guide for details on using json columns in CREATE/ALTER TABLE statements.

This extension integrates with the pg_array extension. If you plan to use the json[] type, load the pg_array extension before the pg_json extension:

    DB.extension :pg_array, :pg_json

This extension requires both the json and delegate libraries.