Adds a powerful suite of filtering capabilities to a PostGraphile schema.
Warning: Use of this plugin 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 below for details.
Requires PostGraphile v4.5.0 or higher.
Install with:
yarn add postgraphile postgraphile-plugin-connection-filter
CLI usage via --append-plugins:
postgraphile --append-plugins postgraphile-plugin-connection-filter -c postgres://localhost/my_db ...
Library usage via appendPlugins:
import ConnectionFilterPlugin from "postgraphile-plugin-connection-filter";
// or: const ConnectionFilterPlugin = require("postgraphile-plugin-connection-filter");
const middleware = postgraphile(DATABASE_URL, SCHEMAS, {
appendPlugins: [ConnectionFilterPlugin],
});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
connectionFilterAllowedFieldTypesandconnectionFilterAllowedOperatorsoptions to limit the filterable fields and operators exposed through GraphQL. - Set
connectionFilterComputedColumns: falseto prevent filtering on computed columns. - Set
connectionFilterSetofFunctions: falseto prevent filtering on functions that returnsetof. - Set
connectionFilterArrays: falseto prevent filtering on List fields (Postgres arrays).
Also see the Production Considerations page of the official PostGraphile docs, which discusses query whitelisting.
This plugin supports filtering on almost all PostgreSQL types, including complex types such as domains, ranges, arrays, and composite types. For details on the specific operators supported for each type, see docs/operators.md.
See also:
- @graphile/pg-aggregates - integrates with this plugin to enable powerful aggregate filtering
- postgraphile-plugin-connection-filter-postgis - adds PostGIS functions and operators for filtering on
geography/geometrycolumns - postgraphile-plugin-fulltext-filter - adds a full text search operator for filtering on
tsvectorcolumns - postgraphile-plugin-unaccented-text-search-filter - adds unaccent text search operators
By default, this plugin will throw an error when null literals or empty objects ({}) are included in filter input objects. This prevents queries with ambiguous semantics such as filter: { field: null } and filter: { field: { equalTo: null } } from returning unexpected results. For background on this decision, see #58.
To allow null and {} in inputs, use the connectionFilterAllowNullInput and connectionFilterAllowEmptyObjectInput options documented under Plugin Options. Please note that even with connectionFilterAllowNullInput enabled, null is never interpreted as a SQL NULL; fields with null values are simply ignored when resolving the query.
When using PostGraphile as a library, the following plugin options can be passed via graphileBuildOptions:
Restrict filtering to specific operators:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterAllowedOperators: [
"isNull",
"equalTo",
"notEqualTo",
"distinctFrom",
"notDistinctFrom",
"lessThan",
"lessThanOrEqualTo",
"greaterThan",
"greaterThanOrEqualTo",
"in",
"notIn",
],
},
});Restrict filtering to specific field types:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterAllowedFieldTypes: ["String", "Int"],
},
});The available field types will depend on your database schema.
Enable/disable filtering on PostgreSQL arrays:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterArrays: false, // default: true
},
});Enable/disable filtering by computed columns:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterComputedColumns: false, // default: true
},
});Consider setting this to false and using @filterable smart comments to selectively enable filtering:
create function app_public.foo_computed(foo app_public.foo)
returns ... as $$ ... $$ language sql stable;
comment on function app_public.foo_computed(foo app_public.foo) is E'@filterable';Use alternative names (e.g. eq, ne) for operators:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterOperatorNames: {
equalTo: "eq",
notEqualTo: "ne",
},
},
});Enable/disable filtering on related fields:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterRelations: true, // default: false
},
});Enable/disable filtering on functions that return setof:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterSetofFunctions: false, // default: true
},
});Consider setting this to false and using @filterable smart comments to selectively enable filtering:
create function app_public.some_foos()
returns setof ... as $$ ... $$ language sql stable;
comment on function app_public.some_foos() is E'@filterable';Enable/disable filtering with logical operators (and/or/not):
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterLogicalOperators: false, // default: true
},
});Allow/forbid null literals in input:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterAllowNullInput: true, // default: false
},
});When false, passing null as a field value will throw an error.
When true, passing null as a field value is equivalent to omitting the field.
Allow/forbid empty objects ({}) in input:
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterAllowEmptyObjectInput: true, // default: false
},
});When false, passing {} as a field value will throw an error.
When true, passing {} as a field value is equivalent to omitting the field.
When building the "many" relationship filters, if this option is set true
then we will use the "list" field names rather than the "connection" field
names when naming the fields in the filter input. This would be desired if you
have simpleCollection set to "only" or "both" and you've simplified your
inflection to omit the -list suffix, e.g. using
@graphile-contrib/pg-simplify-inflector's pgOmitListSuffix option. Use this
if you see Connection added to your filter field names.
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
connectionFilterUseListInflectors: true, // default: false
},
});query {
allPosts(filter: {
createdAt: { greaterThan: "2021-01-01" }
}) {
...
}
}For an extensive set of examples, see docs/examples.md.
To establish a test environment, create an empty PostgreSQL database with C collation (required for consistent ordering of strings) and set a TEST_DATABASE_URL environment variable with your database connection string.
createdb graphile_test_c --template template0 --lc-collate C
export TEST_DATABASE_URL=postgres://localhost:5432/graphile_test_c
yarn
yarn test
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent