Skip to main content
Version: v5 (beta)

Command Line Interface

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

To try without installing, run the pgl command via the npx command that comes bundled with Node.js:

npx pgl -P pgl/amber -e -c postgres:///mydb
info

You should replace postgres:///mydb with a PostgreSQL connection string pointing at your database, and if you use a non-standard PostgreSQL schema you should indicate the schema name via -s my_schema_name_here.

For a more permanent installation we suggest you create yourself a new directory for your project, we'll refer to this as ~/postgraphile. Open a terminal in this directory and install PostGraphile:

cd ~/postgraphile
npm install postgraphile@rc

You can then run PostGraphile equivalent to above via:

npx postgraphile -P postgraphile/presets/amber -e -c postgres:///mydb
warning

The -e option should only be used in development.

CLI flags​

The CLI accepts a small number of configuration options to get you started. It also reads options from a graphile.config.js file from the current working directory (if it exists); by specifying all options in this file you can run PostGraphile with no (or minimal) CLI flags.

  • --version
    output the version number
  • --help
    output usage information
  • --preset <string> (alias: -P) { extends: [...] } can be used to specify a comma-separated list of presets to add to the configuration
  • --allow-explain (alias: -e) { grafast: { explain: true } } enables "explain" mode, you won't want this in production but it's very helpful in development to know what's going on
  • --connection <string> (alias: -c) { pgServices: [makePgService({ connectionString: '...' })] } the PostgreSQL connection string. If omitted, inferred from

    environmental variables

     .
    Examples: db, postgres:///db, postgres://user:password@domain:port/db?ssl=true
  • --superuser-connection <string> (alias: -S) { pgServices: [makePgService({ superuserConnectionString:'...' })] } the PostgreSQL superuser connection string to use for installing watch fixtures (if --watch is enabled). If omitted, the regular connection string will be used.
  • --schema <string> (alias: -s) { pgServices: [makePgService({ schemas: ['...'] })] } a comma-separated list of PostgreSQL schemas to be introspected.
  • --watch (alias: -w) { grafserv: { watch: true } } automatically updates your GraphQL schema when your database schema changes (NOTE: requires DB superuser to install postgraphile_watch schema)
  • --host <string> (alias: -n) { grafserv: { host: 'localhost' } } the hostname to be used. Defaults to localhost
  • --port <number> (alias: -p) { grafserv: { port: 5678 } } the port to be used. Defaults to 5678

pgl vs postgraphile​

New to V5 if PostGraphile is the pgl command. This is almost identical to the postgraphile command (it actually defers to postgraphile under the hood), with the following differences:

  • pgl has no peerDependencies - as soon as you start installing plugins that need peerDependencies you should consider moving to postgraphile
  • pgl exposes postgraphile/presets/amber as pgl/amber (and similar for pgl/v4 and pgl/relay), so it's more concise
tip

pgl is most suitable for running from npx without the need to permanently install anything. If you want to start using PostGraphile in your project you should install postgraphile instead.