postgraphile-plugin-connection-filter

This plugin adds a filter argument to Connection types in PostGraphile v4.

Note: This plugin targets the beta release of PostGraphile v4. See the Compatibility table below for details.

Warning: Use of this plugin (particularly with the default options) may make it astoundingly trivial for a malicious actor (or a well-intentioned application that generates complex GraphQL queries) to overwhelm your database with expensive queries. See the Performance and Security section for details.

Breaking change in beta.9

The deprecated is and null operators were removed. Use the isNull operator instead.

Breaking change in beta.7

The v1.0.0-beta.7 release of this plugin uses the pluggable inflector and smart comments functionality introduced in PostGraphile v4.0.0-beta.8. As a result, the PostGraphile peer dependency was bumped to v4.0.0-beta.8 or later.

Breaking change in beta.4

The contains string comparison operator was renamed to includes to make room for JSONB operators contains and containedBy. To maintain the old names, you can specify the following in graphileBuildOptions:

connectionFilterOperatorNames: {
  includes: "contains",
  includesInsensitive: "containsInsensitive",
  notIncludes: "notContains",
  notIncludesInsensitive: "notContainsInsensitive",
  contains: "jsonbContains",
  containedBy: "jsonbContainedBy"
}

Compatibility

Performance and Security

By default, this plugin:

• Exposes a large number of filter operators, including some that can perform expensive pattern matching.
• Allows filtering on computed columns, which can result in expensive operations.
• Allows filtering on functions that return setof, which can result in expensive operations.
• Allows filtering on List fields (Postgres arrays), which can result in expensive operations.

To protect your server, you can:

• Use the connectionFilterAllowedFieldTypes and connectionFilterAllowedOperators options to limit the filterable fields and operators exposed through GraphQL.
• Set connectionFilterComputedColumns: false to prevent filtering on computed columns.
• Set connectionFilterSetofFunctions: false to prevent filtering on functions that return setof.
• Set connectionFilterLists: false to prevent filtering on List fields (Postgres arrays).

Getting Started

CLI

postgraphile --append-plugins `pwd`/path/to/this/plugin/index.js

Library

const express = require("express");
const { postgraphile } = require("postgraphile");
const PostGraphileConnectionFilterPlugin = require("postgraphile-plugin-connection-filter");

const app = express();

app.use(
  postgraphile(pgConfig, schema, {
    graphiql: true,
    appendPlugins: [PostGraphileConnectionFilterPlugin],
  })
);

app.listen(5000);

Operators

The following filter operators are exposed by default:

Logical Operators

Comparison Operators

List Comparison Operators

Examples

query {
  allPosts(filter: {
    body: { isNull: true }
  }) {
    ...
  }
}

query {
  allPosts(filter: {
    body: { isNull: false }
  }) {
    ...
  }
}

query {
  allPosts(filter: {
    createdAt: { greaterThan: "2016-01-01" }
  }) {
    ...
  }
}

query {
  allPosts(filter: {
    authorId: { in: [1, 2] }
  }) {
    ...
  }
}

query {
  allPosts(filter: {
    body: { isNull: false },
    createdAt: { greaterThan: "2016-01-01" }
  }) {
    ...
  }
}

query {
  allPosts(filter: {
    or: [
      { authorId: { equalTo: 6 } },
      { createdAt: { greaterThan: "2016-01-01" } }
    ]
  }) {
    ...
  }
}

query {
  allPosts(filter: {
    not: {
      or: [
        { authorId: { equalTo: 6 } },
        { createdAt: { greaterThan: "2016-01-01" } }
      ]
    }
  }) {
    ...
  }
}

query {
  allPeople(filter: {
    firstName: { startsWith:"John" }
  }) {
    nodes {
      firstName
      lastName
      postsByAuthorId(filter: {
        createdAt: { greaterThan: "2016-01-01" }
      }) {
        nodes {
          ...
        }
      }
    }
  }
}

For additional examples, see the tests.

Plugin Options

When using PostGraphile as a library, the following plugin options can be passed via graphileBuildOptions:

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterAllowedOperators: [
      "isNull",
      "equalTo",
      "notEqualTo",
      "distinctFrom",
      "notDistinctFrom",
      "lessThan",
      "lessThanOrEqualTo",
      "greaterThan",
      "greaterThanOrEqualTo",
      "in",
      "notIn",
    ],
  },
})

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterAllowedFieldTypes: ["String", "Int"],
  },
})

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterComputedColumns: false, // default: true
  },
})

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterLists: false, // default: true
  },
})

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterOperatorNames: {
      equalTo: "eq",
      notEqualTo: "ne",
    },
  },
})

postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    connectionFilterSetofFunctions: false, // default: true
  },
})

Development

To establish a test environment, create an empty Postgres database (e.g. graphile_build_test) and set a TEST_DATABASE_URL environment variable with your connection string (e.g. postgres://localhost:5432/graphile_build_test). Ensure that psql is installed locally and then run:

npm install
npm test