"graphile" CLI

[benjie]

We have a bit of a naming issue at Graphile in that we seem to put "Graphile" in the name of all our projects (because I'm not particularly good at coming up with names for things...) and yet quite a lot of people call "PostGraphile" simply "Graphile."

Despite this communication issue, I would like to create a "graphile" CLI which is independent(ish) from the "postgraphile" CLI. I see them like this:

• postgraphile - runs an HTTP server running a PostGraphile GraphQL schema and (optionally) GraphiQL - mostly to make npx postgraphile -c my_db --watch an easy to run command
• graphile - a way of interacting with all of the Graphile suite - a very powerful CLI suite

To this end, I've spent a bit of time brainstorming all the different things a graphile CLI might want to do. We don't need all these things for the first version, but thinking about as much as we can should help us to reserve space for all the commands we're likely to need.

Here's some of the commands I'm currently anticipating:

graphile worker

• Effectively delegates to graphile-worker

graphile migrate

• Effectively delegates to graphile-migrate

graphile export-sources

• Exports the generated data sources as JavaScript

graphile export-schema [--mode=typeDefs] [--sources=sources.js]

• Exports the generated GraphQL schema as JavaScript (maybe pulling sources from a JS file)

graphile sdl [--schema=schema.js:schema] [--endpoint=http://…]

• Outputs the GraphQL SDL for the schema (pulling from schema or endpoint, or building it from the config)

graphile server [--watch]

• build a schema and then run a webserver for it (similar to V4's postgraphile command)

graphile server --schema=schema.js

• as above, but reading the schema from a JS file rather than building it

graphile graphiql --endpoint=http://localhost:5000/graphql

• run our enhanced GraphiQL against the given GraphQL schema

graphile plan svg [myquery.plan]

• render an svg for the given DataPlanner plan

graphile plan interactive [myquery.plan]

• render a web page for the given DataPlanner plan (and run a server for it?) - e.g. using mermaid.js

graphile query [--schema=schema.js] [query.graphql]

• runs the given GraphQL query against the given schema (or builds the schema if necessary)

graphile pg check [--connection=...]

• Checks the connection to the given PostgreSQL database; useful for debugging

graphile pg repl [--connection=...]

• Gives a simple REPL for interacting with the database, like a really really cut down and crappy psql alternative ;)

graphile pg install-watch-fixtures [--connection=...]

• Installs the event triggers required for schema watch mode

graphile config check

• ensures that the graphile.config.js is valid
• goes through each namespace and validates
• mentions namespaces that are present that could not be validated?

graphile config print

• prints out the full final config read from the graphile.config.js file having resolved all presets
• would be great if this could show which preset each option came from!

graphile config init

• helps you initialize a graphile.config.js file

graphile docs search [query]

• I dunno… like searches the docs or something. Maybe should be scoped to the relevant project? Maybe searches all the projects? Maybe gives you hits on the command line and you pick one? Maybe it respects the local software versions?

graphile chat

• loads discord

graphile info

• spits out debugging info about the current environment: OS, Node version, versions of Graphile software/pg/graphql/etc, the config [with things like DB URL censored], etc

graphile debug

• opens the chrome devtools ready to connect to a node –inspect?

graphile fund / sponsor / etc

• takes you to the sponsors page

graphile thanks

• details of our supporters and the projects that we use

graphile plan analyze

• alias for graphile analyze plan

graphile analyze pg [--connection=...]

• submit the database schema at the given connection string to pgRITA and output the result

graphile analyze plan [myquery.plan]

• output some kind of analysis for this plan… [TODO]

Other CLI ideas:

• persisted queries
• browse presets
• mehserve
• watch mode
• bundle command for webpack/rollup/etc-style bundling of the schema file/etc?

---

If you can think of other commands we might need, or think that you have a better structure (or just better names) - please let me know!

Incidentally, I don't plan for the CLI to bundle all this software - it'll try and import the relevant software but if it's not present then those CLI commands will error (telling you what you need to install).