This quick start guide will walk you through spinning up your first PostGraphile server, including installing the prerequisites such as Node and PostgreSQL.
Table of Contents
You need to be running Node.js v8.6 or higher to run PostGraphile. You can check
your current version of Node by running
node --version. If you're running a
recent version you can skip this section.
There's many ways of installing node; if you're on macOS you might prefer
installing with homebrew via
brew install node; if you're
on a unix-based system you might like to
nvm tool. Failing these, if
you're using OS X or Windows, use one of the installers from the
Node.js download page. Make sure you select
the version labelled LTS. Linux users can scroll down the page and find the
version that works with their system.
Once installed run
node -v in a terminal to check your version. It must be
8.6.0 or higher.
We need a PostgreSQL database to connect to. You can skip this section if you
already have PostgreSQL version
9.6.0 or higher installed.
PostgreSQL does not need to be installed on the same machine, but you'll have a better development experience if it is. Try and minimise database connection latency! If you do not use a local PostgreSQL server then you'll need to modify the commands that follow to account for this.
If you are running on macOS, it is recommended that you install and use
PostgreSQL.app. If you are on another platform, go to
the PostgreSQL download page to pick up
a copy of PostgreSQL. We recommend using a version of PostgreSQL higher than
9.6.0. You can read more about the reasoning behind this requirement
in our documentation.
After that, make sure your copy of PostgreSQL is running locally by running
psql postgres:/// in a terminal (the three slashes is deliberate - we're
deliberately not specifying a host so it uses the defaults of hostname:
localhost, port: 5432).
If you get something like this returned then PostgreSQL is successfully installed:
$ psql "postgres:///"
psql: FATAL: database "username" does not exist
however, if you receive a "Connection refused" error then that indicates your PostgreSQL server is not running, or not reachable:
$ psql "postgres:///"
psql: could not connect to server: Connection refused
If you want to connect to a different database within PostgreSQL, just add the database name to the end of the connection string:
$ psql postgres:///testdb # Connects to the `testdb` database on your local machine
$ psql "postgres://user:password@somehost:2345/somedb" # Connects to the `somedb` database at `postgres://somehost:2345` using login with `user` and `password`
Read the documentation on PostgreSQL connection strings to learn more about alternative formats (including using a password).
Create a Database
Next, create a database. You can do this by using the terminal:
$ createdb mydb
This will create a PostgreSQL database called "mydb". You can read more about
this on the
PostgreSQL Documentation site.
Now you can run
psql with your database URL and get a SQL prompt:
$ psql "postgres:///mydb"
Type "help" for help.
Run the following query to make sure things are working smoothly:
=# select 1 + 1 as two;
It is easy to install PostGraphile with npm:
$ npm install -g postgraphile
NOTE: we do not recommend installing PostGraphile globally (with the
npmused here) - local installs are preferred. However, if you're just getting started with Node.js then using the global install method is much simpler. Once you start wanting to use plugins with PostGraphile we recommend you move to using a local install.
To run PostGraphile, you’ll use the same URL that you used for
psql with the
database name added:
# Connect to the `mydb` database within the local PostgreSQL server
$ postgraphile -c "postgres:///mydb"
# Connect to a database that requires SSL/TLS
$ postgraphile -c "postgres://securehost:5432/db?ssl=true"
# Connect to the `somedb` database within the PostgreSQL at somehost port 2345
$ postgraphile -c "postgres://somehost:2345/somedb"
You can also run PostGraphile with the watch flag:
$ postgraphile -c "postgres:///mydb" --watch
--watch flag, PostGraphile will automatically update your GraphQL API
whenever the PostgreSQL schemas you are introspecting change.
Running PostGraphile will give you two endpoints:
‣ GraphQL endpoint served at http://localhost:5000/graphql
‣ GraphiQL endpoint served at http://localhost:5000/graphiql
The first endpoint is for your application to talk to; the second endpoint can
be opened in a web browser to give you access to your database through
GraphiQL - a visual GraphQL explorer.
Well done — you've got PostGraphile up and running!