graphql-engine/docs/graphql/cloud/projects/create.rst

.. meta::
   :description: Creating projects on Hasura Cloud
   :keywords: hasura, cloud, docs, start

.. _create_project:

Creating projects
=================

.. contents:: Table of contents
  :backlinks: none
  :depth: 2
  :local:

Introduction
------------

You can create a new Hasura Cloud project with either a new Postgres database, or an existing Postgres database with a publicly available IP address.

Step 1: Project setup
---------------------

To begin, navigate to the ``Projects`` page, and click the ``New Project`` link.

.. thumbnail:: /img/graphql/cloud/projects/create-new-project.png
   :alt: create new project button
   :width: 400px

This opens a form on the right where you can create your new project.

Choose a pricing plan, select a region and optionally enter the project name for your project in this form.

.. thumbnail:: /img/graphql/cloud/projects/project-setup.png
   :alt: project setup
   :width: 1100px

Once you have completed the project setup, click ``Create Project``.

Step 2: Database setup
----------------------

To get started, Click ``Launch Console`` to open the Hasura console in your browser.

.. thumbnail:: /img/graphql/cloud/getting-started/project-launch-console.png
   :alt: database setup with new database
   :width: 900px

On the Hasura console, navigate to ``Data -> Manage -> Connect Database``:

New database
^^^^^^^^^^^^

Hasura Cloud does not host databases, but does provide integrations with which you can create databases on managed cloud providers like Heroku. Integrations for AWS, GCP, and Azure are coming soon.

To get started, choose ``Create Heroku Database -> Create Database``, and follow the prompts to authenticate with Heroku. Hasura Cloud will integrate with your Heroku account and manage the initial setup of a dev-tier Postgres instance. You can always upgrade the instance and manage options later through your Heroku account.

.. thumbnail:: /img/graphql/cloud/projects/project-new-database-setup.png
   :alt: database setup with new database
   :width: 700px

Existing database
^^^^^^^^^^^^^^^^^
To use an existing database, choose ``Connect existing database`` and enter your database connection URL and enter your database connection string (looks like ``postgres://username:password@hostname:port/dbname``).

.. thumbnail:: /img/graphql/cloud/projects/existing-db-setup.png
   :alt: database setup with existing database
   :width: 700px

.. note::

  You can connect to databases either using env vars or by using their raw connection string/parameters. It is
  recommended to use env vars for better security *(as connection details are part of Hasura metadata)* as well as
  to allow configuring different databases in different environments *(like staging/production)* easily.

Allowing connections from Hasura Cloud IP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For some cloud services, like GCP, you'll need to adjust your Postgres connection settings to allow connections from the Hasura Cloud IP address. You can copy the IP address from the copy icon in the ``Hasura Cloud IP`` field on the project's details view. You may also need to disable SSL. Adding custom cert information to a Hasura Cloud instance is not yet available. 

.. thumbnail:: /img/graphql/cloud/projects/hasura-cloud-ip.png
   :alt: Hasura Cloud IP field
   :width: 1000px

.. thumbnail:: /img/graphql/cloud/projects/gcp-postgres-authorized-network.png
   :alt: whitelist Hasura instance IP in Postgres settings
   :width: 727px

Postgres requirements
---------------------

Hasura Cloud works with **Postgres versions 9.5 and above**.

Make sure your database user has the right :ref:`Postgres permissions <cloud_postgres_permissions>`.

Connecting to a database not exposed over the internet
------------------------------------------------------

`Contact us <https://hasura.io/contact-us/>`__ for VPC peering and on-premise solutions.

More databases
--------------

Support for more databases (MySQL, SQL Server etc) is coming soon.