with-postgresql

StepZen Example: with-postgresql

Introduction

This project builds a GraphQL API connected to your PostgreSQL database using StepZen. We will use the @dbquery directive to generate our GraphQL schema.

For a step-by-step walkthrough of this example, please go to Getting started with a PostgreSQL database on StepZen.

Getting Started

You'll need to create a StepZen account first. Once you've got that set up, git clone this repository onto your machine and open the working directory:

git clone https://github.com/stepzen-dev/examples.git
cd examples/with-postgresql

Before you can run this example, you need to have a PostgreSQL database. Which you can either run in the cloud or set up locally with Docker.

Run a database in the cloud

The easiest way to try out this example is by running a database in the cloud.

If you don't have a database running in the cloud yet, you can try our read-only mocked PostgreSQL database:

Click to show credentials!

• host: postgresql.introspection.stepzen.net
• database: introspection
• username: testUserIntrospection
• password: HurricaneStartingSample1934

You can copy the file sample.config.yaml to a new config.yaml file:

cp sample.config.yaml config.yaml

Replace the contents of config.yaml with the following:

# config.yaml

configurationset:
  - configuration:
      name: postgresql_config
      uri: postgresql://testUserIntrospection:HurricaneStartingSample1934@postgresql.introspection.stepzen.net/introspection

Creating a local database with Docker

Alternatively, you can create a local database using our Docker script. This requires you to have Docker installed (no prior knowledge needed) and using ngrok to create a TCP tunnel so you can link it to StepZen.

Prerequisites

• Docker (Mac/Windows)
• ngrok account
• ngrok installed (Mac/Windows)

Make sure you have an account for ngrok and have linked your authtoken by running:

ngrok authtoken [YOUR_AUTH_TOKEN]

After doing so start the Docker container with the PostgreSQL database from this directory:

docker-compose up -d

This will start the container with the PostgreSQL server, makes it available on port 5432 and prepopulates it with the data from ./init.sql.

To make this database available to other services outside your private network, you need to create a TCP tunnel. For this ngrok will be used:

ngrok tcp 5432

Ngrok will return the forwarding address for the local PostgreSQL database, which will looks something like this: tcp://0.tcp.ngrok.io:15650.

You need to add this to the file ./config.yaml where you need to replace {{ngrok_tunnel}} with (in example) 0.tcp.ngrok.io:15650:

# config.yaml

configurationset:
  - configuration:
      name: postgresql_config
      uri: postgresql://testUserIntrospection:HurricaneStartingSample1934@{{ngrok_tunnel}}/introspection

Run StepZen

Open your terminal and install the StepZen CLI:

npm install -g stepzen

You need to login here using the command:

stepzen login

After you've installed the CLI and logged in, run:

stepzen start

A proxy of the GraphiQL playground becomes available at http://localhost/5001 (in example http://localhost:5001/api/with-postgresql), which you can use to explore the GraphQL API. Also, the endpoint at which your GraphQL API is deployed gets logged in the terminal. You can query your GraphQL API from any application, browser, or IDE by providing the API Key linked to your account.

Learn More

You can learn more in the StepZen documentation. Questions? Head over to Discord or GitHub Discussions to ask questions.