Quick Start

GraphJin can generate your initial app for you. The generated app will have config files, database migrations and seed files among other things like docker related files.

You can then add your database schema to the migrations, maybe create some seed data using the seed script and launch GraphJin. You’re now good to go and can start working on your UI frontend in React, Vue or whatever.

1. Quick Install

Mac (Homebrew)

brew install dosco/graphjin/graphjin

Ubuntu (Snap)

sudo snap install --classic graphjin

Debian and Redhat (releases)

Download the .deb or .rpm from the releases page and install with dpkg -i and rpm -i respectively.

Go Install

go install github.com/dosco/graphjin@latest

2. Create New API

# Create a new app and change to it's directory
graphjin new blog

cd blog

# Create the app database
# Docker compose will start a Postgres database for your app
docker-compose run api db create

# Run migrations and seed it with fake data.
# Docker compose will start a Postgres database for your app
docker-compose run api db setup

# Finally launch GraphJin configured for your app
docker-compose up

What just happened?

Lets take a look at the files generated by GraphJin when you create a new app

graphjin new blog

> created 'blog'
> created 'blog/Dockerfile'
> created 'blog/docker-compose.yml'
> created 'blog/config'
> created 'blog/config/dev.yml'
> created 'blog/config/prod.yml'
> created 'blog/config/seed.js'
> created 'blog/config/migrations'
> created 'blog/config/migrations/100_init.sql'
> app 'blog' initialized
What is docker-compose? Docker Compose is a great way to run multiple services while developing on your desktop or laptop. In our case we need Postgres and GraphJin to both be running and the docker-compose.yml is configured to do just that. The GraphJin service is named api you are free to change this. The Dockerfile can be used build a containr of your app for production deployment.

Run GraphJin with Docker compose

docker-compose run api help

Config files

All the config files needed to configure GraphJin for your app are contained in this folder; to start you have dev.yaml and prod.yaml. When the GO_ENV environment variable is set to development then dev.yaml is used and the prod one when it’s set to production. Stage and Test are the other two environment options, but you can set the GO_ENV to whatever you like (eg. alpha-test) and GraphJin will look for a yaml file with that name to load config from.

Migrations

Easy database migrations is the most important thing when building products backend by a relational database. We make it super easy to manage and migrate your database.

graphjin db migrate new create_users
> created migration 'config/migrations/101_create_users.sql'

Migrations in GraphJin are plain old Postgres SQL. Here’s an example for the above migration:

-- Write your migrate up statements here

CREATE TABLE users (
  id BIGINT NOT NULL PRIMARY KEY,
  full_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE (email)
);

---- create above / drop below ----

-- Write your down migrate statements here. If this migration is irreversible
-- then delete the separator line above.

DROP TABLE public.users

Seed.js

Having data flowing through your API makes building your frontend UI so much easier. When crafting say a user profile wouldn’t it be nice for the API to return a fake user with name, picture and all. This is why having the ability to seed your database is important. Seeding can also be used in production to setup some initial users like the admins or to add an initial set of products to a ecommerce store.

GraphJin makes this easy by allowing you to write your seeding script in plain old Javascript. The below file - auto-generated for new apps - uses our built-in functions fake and graphql to generate fake data and use GraphQL mutations to insert it into the database.

// Example script to seed database

var users = [];

for (i = 0; i < 10; i++) {
  var data = {
    id: i,
    full_name: fake.name(),
    email: fake.email(),
    created_at: "now",
  };

  var res = graphql(" \
	mutation { \
	  users(insert: $data) { \
	    id \
	  } \
	}", {
    data: data,
  });

  users = users.concat(res.users);
}

If you want to import a lot of data using a CSV file is the best and fastest option. The import_csv command uses the COPY FROM Postgres method to load massive amounts of data into tables. The first line of the CSV file must be the header with column names.

var post_count = import_csv("posts", "posts.csv");

You can generate the following fake data for your seeding purposes. Below is the list of fake data functions supported by the built-in fake data library. For example fake.image_url() will generate a fake image url or fake.shuffle_strings(['hello', 'world', 'cool']) will generate a randomly shuffled version of that array of strings or fake.rand_string(['hello', 'world', 'cool']) will return a random string from the array provided.