The easiest way to get up and running with PostGraphile is to use the Command Line Interface.

Install PostGraphile globally via npm:

npm install -g postgraphile

This will make the postgraphile command available. You can then run:

postgraphile -c postgres:///mydb -s public -a -j

where -c is the connection string (defaults to postgres:///), -s is the schema name (defaults to "public"), -a enables Relay support and -j enables dynamic JSON.

macOS users: you should also use the --port option to bind to a different port, the default port 5000 now conflicts with macOS Monterey's new AirPlay service.

PostGraphile also reads options from a .postgraphilerc.js file from the current working directory.

Recommended options

As PostGraphile evolves, we add more features; however we can't always enable these features by default as they may be breaking changes. There are also options that may have security repercussions. For this reason, many features are behind flags. We understand this page is very long, so we've included some default option sets you might like to use:

We recommend you install the @graphile-contrib/pg-simplify-inflector plugin.

For Development

postgraphile \
  --subscriptions \
  --watch \
  --dynamic-json \
  --no-setof-functions-contain-nulls \
  --no-ignore-rbac \
  --show-error-stack=json \
  --extended-errors hint,detail,errcode \
  --append-plugins @graphile-contrib/pg-simplify-inflector \
  --export-schema-graphql schema.graphql \
  --graphiql "/" \
  --enhance-graphiql \
  --allow-explain \
  --enable-query-batching \
  --legacy-relations omit \
  --connection $DATABASE_URL \
  --schema app_public

For Production

postgraphile \
  --subscriptions \
  --retry-on-init-fail \
  --dynamic-json \
  --no-setof-functions-contain-nulls \
  --no-ignore-rbac \
  --extended-errors errcode \
  --append-plugins @graphile-contrib/pg-simplify-inflector \
  --disable-graphiql \
  --enable-query-batching \
  --disable-query-log \ # our default logging has performance issues, but do make sure you have a logging system in place!
  --legacy-relations omit \
  --connection $DATABASE_URL \
  --schema app_public

CLI options

There are more CLI options available to customise the GraphQL server (these are from postgraphile@4.12.3):

• -V, --version
  output the version number
• --plugins <string>
  a list of PostGraphile server plugins (not Graphile Engine schema plugins) to load; if present, must be the first option
• -c, --connection <string>
  the PostgreSQL database name or connection string. If omitted, inferred from environmental variables (see https://www.postgresql.org/docs/current/static/libpq-envars.html). Examples: 'db', 'postgres:///db', 'postgres://user:password@domain:port/db?ssl=true'
• -C, --owner-connection <string>
  as --connection, but for a privileged user (e.g. for setting up watch fixtures, logical decoding, etc); defaults to the value from --connection
• -s, --schema <string>
  a Postgres schema to be introspected. Use commas to define multiple schemas
• -S, --subscriptions
  Enable GraphQL support for subscriptions (you still need a subscriptions plugin currently)
• --websockets <string>
  Choose which websocket transport libraries to use. Use commas to define multiple. Defaults to 'v0,v1' if --subscriptions or --live were passed, '[]' otherwise
• --websocket-operations <operations>
  Toggle which GraphQL websocket transport operations are supported: 'subscriptions' or 'all'. Defaults to 'subscriptions'
• -L, --live
  [EXPERIMENTAL] Enables live-query support via GraphQL subscriptions (sends updated payload any time nested collections/records change). Implies --subscriptions
• -w, --watch
  automatically updates your GraphQL schema when your database schema changes (NOTE: requires DB superuser to install postgraphile_watch schema)
• -n, --host <string>
  the hostname to be used. Defaults to localhost
• -p, --port <number>
  the port to be used. Defaults to 5000
• -m, --max-pool-size <number>
  the maximum number of clients to keep in the Postgres pool. defaults to 10
• -r, --default-role <string>
  the default Postgres role to use when a request is made. supercedes the role used to connect to the database
• --retry-on-init-fail
  if an error occurs building the initial schema, this flag will cause PostGraphile to keep trying to build the schema with exponential backoff rather than exiting
• -j, --dynamic-json
  [RECOMMENDED] enable dynamic JSON in GraphQL inputs and outputs. PostGraphile uses stringified JSON by default
• -N, --no-setof-functions-contain-nulls
  [RECOMMENDED] if none of your RETURNS SETOF compound_type functions mix NULLs with the results then you may enable this to reduce the nullables in the GraphQL schema
• -a, --classic-ids
  use classic global id field name. required to support Relay 1
• -M, --disable-default-mutations
  disable default mutations, mutation will only be possible through Postgres functions
• --simple-collections <omit|both|only>
  "omit" (default) - relay connections only, "only" - simple collections only (no Relay connections), "both" - both
• --no-ignore-rbac
  [RECOMMENDED] set this to exclude fields, queries and mutations that are not available to any possible user (determined from the user in connection string and any role they can become); this will be enabled by default in v5
• --no-ignore-indexes
  set this to exclude filters, orderBy, and relations that would be expensive to access due to missing indexes
• --include-extension-resources
  by default, tables and functions that come from extensions are excluded; use this flag to include them (not recommended)
• --show-error-stack [json|string]
  show JavaScript error stacks in the GraphQL result errors (recommended in development)
• --extended-errors <string>
  a comma separated list of extended Postgres error fields to display in the GraphQL result. Recommended in development: 'hint,detail,errcode'. Default: none
• --append-plugins <string>
  a comma-separated list of plugins to append to the list of Graphile Engine schema plugins
• --prepend-plugins <string>
  a comma-separated list of plugins to prepend to the list of Graphile Engine schema plugins
• --skip-plugins <string>
  a comma-separated list of Graphile Engine schema plugins to skip
• --read-cache <path>
  [experimental] reads cached values from local cache file to improve startup time (you may want to do this in production)
• --write-cache <path>
  [experimental] writes computed values to local cache file so startup can be faster (do this during the build phase)
• --export-schema-json <path>
  enables exporting the detected schema, in JSON format, to the given location. The directories must exist already, if the file exists it will be overwritten.
• --export-schema-graphql <path>
  enables exporting the detected schema, in GraphQL schema format, to the given location. The directories must exist already, if the file exists it will be overwritten.
• --sort-export
  lexicographically (alphabetically) sort exported schema for more stable diffing.
• -X, --no-server
  [experimental] for when you just want to use --write-cache or --export-schema-* and not actually run a server (e.g. CI)
• -q, --graphql <path>
  the route to mount the GraphQL server on. defaults to /graphql
• -i, --graphiql <path>
  the route to mount the GraphiQL interface on. defaults to /graphiql
• --enhance-graphiql
  [DEVELOPMENT] opt in to additional GraphiQL functionality (this may change over time - only intended for use in development; automatically enables with subscriptions and live)
• -b, --disable-graphiql
  disables the GraphiQL interface. overrides the GraphiQL route option
• -o, --cors
  enable generous CORS settings; disabled by default, if possible use a proxy instead
• -l, --body-size-limit <string>
  set the maximum size of the HTTP request body that can be parsed (default 100kB). The size can be given as a human-readable string, such as '200kB' or '5MB' (case insensitive).
• --timeout <number>
  set the timeout value in milliseconds for sockets
• --cluster-workers <count>
  [experimental] spawn workers to increase throughput
• --enable-query-batching
  [experimental] enable the server to process multiple GraphQL queries in one request
• --disable-query-log
  disable logging queries to console (recommended in production)
• --allow-explain
  [EXPERIMENTAL] allows users to use the Explain button in GraphiQL to view the plan for the SQL that is executed (DO NOT USE IN PRODUCTION)
• -e, --jwt-secret <string>
  the secret to be used when creating and verifying JWTs. if none is provided auth will be disabled
• --jwt-verify-algorithms <string>
  a comma separated list of the names of the allowed jwt token algorithms
• -A, --jwt-verify-audience <string>
  a comma separated list of JWT audiences that will be accepted; defaults to 'postgraphile'. To disable audience verification, set to ''.
• --jwt-verify-clock-tolerance <number>
  number of seconds to tolerate when checking the nbf and exp claims, to deal with small clock differences among different servers
• --jwt-verify-id <string>
  the name of the allowed jwt token id
• --jwt-verify-ignore-expiration
  if true do not validate the expiration of the token defaults to false
• --jwt-verify-ignore-not-before
  if true do not validate the notBefore of the token defaults to false
• --jwt-verify-issuer <string>
  a comma separated list of the names of the allowed jwt token issuer
• --jwt-verify-subject <string>
  the name of the allowed jwt token subject
• --jwt-role <string>
  a comma seperated list of strings that create a path in the jwt from which to extract the postgres role. if none is provided it will use the key role on the root of the jwt.
• -t, --jwt-token-identifier <identifier>
  the Postgres identifier for a composite type that will be used to create JWT tokens
• --token <identifier>
  [DEPRECATED] Use --jwt-token-identifier instead. This option will be removed in v5.
• --secret <string>
  [DEPRECATED] Use --jwt-secret instead. This option will be removed in v5.
• --jwt-audiences <string>
  [DEPRECATED] Use --jwt-verify-audience instead. This option will be removed in v5.
• --legacy-functions-only
  [DEPRECATED] PostGraphile 4.1.0 introduced support for PostgreSQL functions than declare parameters with IN/OUT/INOUT or declare RETURNS TABLE(...); enable this flag to ignore these types of functions. This option will be removed in v5.
• --legacy-relations <omit|deprecated|only>
  some one-to-one relations were previously detected as one-to-many - should we export 'only' the old relation shapes, both new and old but mark the old ones as 'deprecated', or 'omit' the old relation shapes entirely
• --legacy-json-uuid
  ONLY use this option if you require the v3 typenames 'Json' and 'Uuid' over 'JSON' and 'UUID'
• -h, --help
  output usage information

The following options are not part of PostGraphile core, but are available from the @graphile/pg-pubsub subscriptions plugin (formerly the paid "supporter" plugin, but now fully free and open source - please consider sponsoring us!):

• -S, --simple-subscriptions add simple subscription support
• --subscription-authorization-function [fn] PG function to call to check user is allowed to subscribe

The following features and not part of PostGraphile core, but are available from the Pro plugin - see Go Pro! for more information.

• --read-only-connection <string> pro spon ⚡️[experimental] a PostgreSQL connection string to use for read-only queries (i.e. not mutations)
• --default-pagination-cap [int] pro spon ⚡️[experimental] Ensures all connections have first/last specified and are no large than this value (default: 50), set to -1 to disable; override via smart comment @paginationCap 50
• --graphql-depth-limit [int] pro spon ⚡️[experimental] Validates GraphQL queries cannot be deeper than the specified int (default: 16), set to -1 to disable
• --graphql-cost-limit [int] pro spon ⚡️[experimental] Only allows queries with a computed cost below the specified int (default: 1000), set to -1 to disable

RC file options

The CLI options can also be specified in a .postgraphilerc.js file in the current working directory. Any command line comma separated options (eg. schema) must be entered as Javascript arrays.

module.exports = {
  options: {
    connection: "postgres://api_user:api_password@localhost/api_development",
    schema: ["myApp", "myAppPrivate"],
    jwtSecret: "myJwtSecret",
    defaultRole: "myapp_anonymous",
    jwtTokenIdentifier: "myApp.jwt_token",
    watch: true,
  },
};

Here is the list of keys and their default values, or types, supported in the options object returned by .postgraphilerc.js.

  appendPlugins: <string>
  bodySizeLimit: <string>
  classicIds = false
  clusterWorkers: <integer>
  connection: <string>
  cors= false
  defaultRole: <string>
  disableDefaultMutations = false
  disableGraphiql = false
  disableQueryLog: true/false
  dynamicJson = false
  enableQueryBatching: true/false
  exportSchemaGraphql: <path string>
  exportSchemaJson: <path string>
  extendedErrors = []
  graphiql = '/graphiql'
  graphql = '/graphql'
  host = 'localhost'
  includeExtensionResources = false
  jwtAudiences: <string>
  jwtRole = ['role']
  jwtSecret: <string>
  jwtSignOptions: {}
  jwtTokenIdentifier
  jwtVerifyAlgorithms: <string>
  jwtVerifyAudience: <string>
  jwtVerifyClockTolerance: <number>
  jwtVerifyId: <string>
  jwtVerifyIgnoreExpiration: true/false
  jwtVerifyIgnoreNotBefore: true/false
  jwtVerifyIssuer: <string>
  jwtVerifySubject: <string>
  legacyJsonUuid: true/false
  maxPoolSize: <number>
  plugins: <string>
  port = 5000
  prependPlugins: <string>
  readCache: <path string>
  schema: <string>
  secret: <string>
  showErrorStack: true/false
  simpleCollections: [omit|both|only]
  skipPlugins: <string>
  timeout: <number>
  token: : <string>
  watch: true/false
  writeCache: <path string>

Please note that this interface is deprecated and will be removed in v5 (but its replacement hasn't been built yet...). You're encouraged to use PostGraphile as a library rather than using a .postgraphilerc.js.