hunk.code_window: import { HttpLink } from 'apollo-link-http'
   const config = {
     link: new HttpLink({
       uri: 'https://hasura-graphql-2.herokuapp.com/v1/graphql', // <- Configure GraphQL Server URL (must be absolute)
     })
   }
   export default withData(config)
hunk.labels: keep keep keep keep replace keep keep keep keep
hunk.after_edit:     uri: 'http://localhost:8080/v1/graphql', // <- Configure GraphQL Server URL (must be absolute)
  
hunk.file_path: community/sample-apps/nextjs-postgres-graphql/config.js
hunk.type: replace
file: Enum type fields
  ================
  
  .. contents:: Table of contents
    :backlinks: none
    :depth: 2
    :local:
  
  Enum type fields are restricted to a fixed set of allowed values.
  
  Enums in a database
  -------------------
  
  In a relational database such as Postgres, an enum type field in a table can be defined in two ways:
  
  .. _native_pg_enum:
  
  Using `native Postgres enum types <https://www.postgresql.org/docs/current/datatype-enum.html>`__
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  
  While the most obvious solution, native enum types have significant drawbacks: they are not easily mutable.
  New values cannot be added to an enum inside a transaction (that is, ``ALTER TYPE ... ADD VALUE`` is not
  supported by transactional DDL), and values cannot be removed from an enum at all without completely dropping
  and recreating it (which cannot be done if the enum is in use by *any* tables, views, or functions). Therefore,
  native enum types should only be used for enums that are guaranteed to *never* change, such as days of the
  week.
  
  .. _reference_table_enum:
  
  Using `foreign-key references <https://www.postgresql.org/docs/current/tutorial-fk.html>`__ to a single-column table
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  
  This approach represents an enum using ordinary relational database concepts. The enum type is represented by a
  table, and the values of the enum are rows in the table. Columns in other tables that use the enum are ordinary
  foreign-key references to the enum table.
  
  For enums with values that are dynamic and may require updates, such as a list of tags or user roles, this
  approach is strongly recommended. Modifying an enum defined this way is easy: simply insert, update, or delete
  rows in the enum table (and updates or deletes can even be cascaded to references, and they may be done within
  a transaction).
  
  Enums in the Hasura GraphQL engine
  ----------------------------------
  
  Given the limitations of native Postgres enum types (as described :ref:`above <native_pg_enum>`), Hasura
  currently only generates GraphQL enum types for enums defined using the
  :ref:`referenced tables <reference_table_enum>` approach.
  
  You may use native Postgres enum types in your database schema, but they will essentially be treated like text
  fields in the generated GraphQL schema. Therefore, this guide focuses primarily on modeling an enum using a
  reference table, but you may still use native Postgres enum types to help maintain data consistency in your
  database. You can always choose to create a table with the values of a Postgres enum as shown in the
  :ref:`section below <create_enum_table_from_pg_enum>`.
  
  **Example:** Let’s say we have a database that tracks user information, and users may only have one of three specific
  roles: user, moderator, or administrator. To represent that, we might have a ``users`` table with the following schema:
  
  .. code-block:: sql
  
    CREATE TABLE users (
      id serial PRIMARY KEY,
      name text NOT NULL,
      role text NOT NULL
    );
  
  Now we can insert some users into our database:
  
  .. code-block:: sql
  
    INSERT INTO users (name, role) VALUES
      ('Alyssa', 'administrator'),
      ('Ben', 'moderator'),
      ('Gerald', 'user');
  
  This works alright, but it doesn’t prevent us from inserting nonsensical values for ``role``, such as
  
  .. code-block:: sql
  
    INSERT INTO users (name, role) VALUES
      ('Hal', 'spaghetti');
  
  which we certainly don’t want. Hence we should create an enum to restrict the allowed values.
  
  .. _create_enum_table:
  
  Creating an enum compatible table
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  
  To represent an enum, we’re going to create an _`enum table`, which for Hasura’s purposes is any table that meets
  the following restrictions:
  
  1. The table must have a single-column primary key of type ``text``. The values of this column are the legal values
     of the enum, and they must all be `valid GraphQL enum value names
     <https://graphql.github.io/graphql-spec/June2018/#EnumValue>`__.
  2. Optionally, the table may have a second column, also of type ``text``, which will be used as a description of each
     value in the generated GraphQL schema.
  3. The table may not contain any other columns.
  4. The table must contain at least 1 row.
  
  **For example**, to create an enum that represents our user roles, we would create the following table:
  
  .. code-block:: sql
  
    CREATE TABLE user_role (
      value text PRIMARY KEY,
      comment text
    );
  
    INSERT INTO user_role (value, comment) VALUES
      ('user', 'Ordinary users'),
      ('moderator', 'Users with the privilege to ban users'),
      ('administrator', 'Users with the privilege to set users’ roles');
  
  .. _create_enum_table_from_pg_enum:
  
  .. admonition:: Creating an enum table from a native PG enum
  
    You can create a table containing the values of a PG enum by executing the following SQL:
  
    .. code-block:: sql
  
      CREATE TABLE "<my_enum_table>" (value TEXT PRIMARY KEY);
      INSERT INTO "<my_enum_table>" (value) (SELECT unnest(enum_range(NULL::"<my_enum>")))::text);
  
  Next, we need to tell Hasura that this table represents an enum.
  
  Setting a table as an enum table
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  
  Once we have a table which satisfies the conditions for an enum table as described :ref:`above <create_enum_table>`,
  we need to tell Hasura that this table represents an enum.
  
  .. rst-class:: api_tabs
  .. tabs::
  
    .. tab:: Console
  
      Head to the ``Modify`` tab of the table and toggle the switch in the
      ``Set table as enum`` section:
  
      .. thumbnail:: ../../../img/graphql/manual/schema/enum-set.png
  
    .. tab:: API
  
      A table can be set as an enum via the following 2 methods:
  
      - passing ``true`` for the ``is_enum`` option of the :ref:`track_table` API while tracking a table
      - using the :ref:`set_table_is_enum` API to change whether or not an already-tracked table should be used as
        an enum
  
  Using an enum table
  ^^^^^^^^^^^^^^^^^^^
  
  To set a field of a table as an enum in the GraphQL schema, we need to set a reference from it to the enum table
  via a foreign key.
  
  **For example**, to update our ``users`` table to reference the ``user_role`` enum table:
  
  .. code-block:: sql
  
    ALTER TABLE users ADD CONSTRAINT
      users_role_fkey FOREIGN KEY (role) REFERENCES user_role;
  
  Making queries using enum values
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  
  Once a table has been tracked as an enum, the GraphQL schema will be updated to expose the values of the
  table as GraphQL enum values i.e. only the exposed values will be permitted for all fields referencing to it.
  
  **For example**, the ``role`` column of the ``users`` table only permits the values in the ``user_role`` table:
  
  .. code-block:: graphql
  
    type users {
      id: Int!
      name: String!
      role: user_role_enum!
    }
  
    enum user_role_enum {
      "Users with the privilege to set users’ roles"
      administrator
  
      "Users with the privilege to ban users"
      moderator
  
      "Ordinary users"
      user
    }
  
  When making queries that filter on the ``role`` column, use the name of the enum value directly rather than providing
  a string:
  
  .. graphiql::
    :view_only:
    :query:
      {
        users(
          where: {
            role: {_eq: administrator}
          }
        ) {
          id
          name
        }
      }
    :response:
      {
        "data": {
          "users": [
            {
              "id": 1,
              "name": "Alyssa"
            }
          ]
        }
      }
  
  Enums and migrations
  ^^^^^^^^^^^^^^^^^^^^
  
  As enum tables have a requirement to contain at least 1 row, it is necessary to have a migration which inserts
  values into an enum table. Otherwise while applying migrations an error would be thrown while trying to set the
  table as an enum.
  
  The migration which inserts values into an enum table needs to be between the migration creating the table
  and the migration setting it as an enum.
  
  This can be achieved via the console by performing the following steps while setting up an enum table:
  
  1. Create the enum table
  2. Use the ``RawSQL`` tab of the console to insert the enum values into the table and mark the insert as a migration
  3. Set the table as an enum
  
  You can also :doc:`manually create migration files <../migrations/advanced/writing-migrations-manually>` to achieve
  this.
  
  Current limitations
  ^^^^^^^^^^^^^^^^^^^
  
  Currently, Hasura does not automatically detect changes to the contents of enum tables, so the GraphQL schema will
  only be updated after manually reloading metadata after inserting, updating, or deleting rows from an enum table.
  