Create a PostgreSQL service

Create PostgreSQL using Zerops GUI

First, set up a project in Zerops GUI. Then go to the project dashboard page and choose Add new service in the left menu in the Services block. Then add a new PostgreSQL service:

// TODO screenshot (add a new service page)

Parameter	Description	Limitations
hostname	A unique service identifier like postgresql,sql, db etc.	- duplicate services with the same name in the same project are forbidden - maximum 25 characters - must contain only lowercase ASCII letters (a-z) or numbers (0-9)

Caution

The hostname is fixed after the service is created. It can't be changed later.

Choose PostgreSQL service mode

Zerops provides PostgreSQL service in two modes: Highly available and Single container.

Highly available

//TODO review

Creates a PostgreSQL cluster with 3 database containers and 2 free database proxies. This mode is suited for production.

Zerops always keeps the 3 database containers on different physical machines. All your data is stored redundantly in 3 identical copies. In case of a container or the underlying physical machine failure, Zerops automatically disconnects the failed container from the cluster, creates a new container, and syncs all data from the remaining 2 copies. Finally, the broken container is automatically deleted.

Learn more about specific behaviour and technical limitations of the PostgreSQL cluster.

Single container

A PostgreSQL database installed in a single container is created. Useful for non-essential data or dev environments.

Caution

Your data is stored only in a single container. If the container or the underlying physical machine fails, your data since the last backup is lost. Zerops doesn't provide any automatic repairs of single-node PostgreSQL services.

Info

The PostgreSQL service mode is fixed after the service is created. It can't be changed later.

Choose PostgreSQL version

Currently, only PostgreSQL v12 version is available.

Set auto-scaling configuration

Zerops scales the PostgreSQL services automatically by raising or lowering the hardware resources of each database container.

CPU Mode

Shared Your application gets a full physical CPU core, but it is shared with up to 10 other applications. In this mode, the power your application gets is dependent on other applications running on the same CPU core. In best case scenario your application gets 10/10 of CPU core power and 1/10 in the worst-case scenario.

Dedicated The CPU core is dedicated to your application.

Info

See the pricing for the difference between CPU modes.

Choose the CPU mode when starting a new service or change it later. The CPU mode doesn't change automatically.

Vertical auto-scaling

Vertical auto-scaling has the following default configuration:

	Minimum resource	Maximum resource
CPU cores	1	5
RAM	0.25 GB	8 GB
Disk	1 GB	2.5 GB

For most cases, the default parameters will work without issues. If you need to limit the cost of the PostgreSQL service, lower the maximal resources. Zerops will never scale above the selected maximums.

When you are experiencing problems with insufficient PostgreSQL performance or capacity, increase the minimal resources. Zerops will never scale below the selected minimums.

Tip

Learn more about how to fine tune the auto-scaling to fit your application needs.

Info

You can change the auto-scaling parameters later.

Tip

Learn more about PostgreSQL auto-scaling.

Create PostgreSQL using zCLI

zCLI is the Zerops command-line tool. To create a new PostgreSQL service via the command line, follow these steps:

1. Install & setup zCLI
2. Create a project description file
3. Create a project and a PostgreSQL service

Create a project description file

Zerops uses a YAML format file to describe the project infrastructure.

Basic example

Create a directory my-project. Create a description.yml file inside the directory with the following content:

# Basic project data
project:
  # project name
  name: my-project
# array of project services
services:
  - # service name
    hostname: postgresql1
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"NON_HA"
    mode: NON_HA

The YAML file describes your future project infrastructure. The project will contain one PostgreSQL service in the single container mode with default auto scaling configuration. The hostname will be set to postgresql1.

Full example

Create a directory my-project. Create a description.yml file inside the directory with the following content:

# Basic project data
project:
  # project name
  name: my-project
  # optional: project description
  description: A project with a PostgreSQL database
  # optional: project tags
  tags:
    - DEMO
    - ZEROPS
# array of project services
services:
  - # first service hostname
    hostname: postgresql1
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"NON_HA"
    mode: HA
    # optional: vertical auto-scaling customization
    verticalAutoscaling:
      cpuMode: DEDICATED
      minCpu: 2
      maxCpu: 5
      minRam: 2
      maxRam: 24
      minDisk: 6
      maxDisk: 50
      startCpuCoreCount: 3
      minFreeRamGB: 0.5
      minFreeRamPercent: 20
  - # second service hostname
    hostname: postgresql2
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"non_HA"
    mode: NON_HA

The YAML file describes your future project infrastructure. The project will contain two PostgreSQL services.

The hostname of the first service will be set to postgresql1. The high availability mode will be chosen and the custom auto scaling configuration will be set.

The hostname of the second service will be set to postgresql2. The single container mode will be chosen and the default auto scaling configuration will be set.

Description of description.yml parameters

The project: section is required. Only one project can be defined.

Parameter	Description	Limitations
name	The name of the new project. Duplicates are allowed.
description	Optional. Description of the new project.	Maximum 255 characters.
tags	Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.

At least one service in the services: section is required. You can create a project with multiple services. The example above contains only PostgreSQL services but you can create a description.yml with [different types] of services.

Parameter	Description
hostname	The unique service identifier. The hostname of the new database will be set to the hostname value. Limitations: - duplicate services with the same name in the same project are forbidden maximum 25 characters - must contain only lowercase ASCII letters (a-z) or numbers (0-9)
type	Specifies the service type postgresql and version. Set type: postgresql<span>@</span>12 Limitations: Currently only PostgreSQL 12 is available.
mode	Defines the operation mode of the PostgreSQL service. HA Creates a PostgreSQL cluster with 3 database containers and 2 free database proxies. This mode is suited for production. Zerops always keeps the 3 database containers on different physical machines. All your data is stored redundantly in 3 identical copies. In case of a failure of a container or the underlying physical machine, Zerops automatically disconnects the failed container from the cluster, creates a new container and syncs all data from the remaining 2 copies. Finally, the broken container is automatically deleted. NON_HA Zerops will create a PostgreSQL database installed in a single container. Useful for non-essential data or dev environments. Your data is stored only in a single container. If the container or the the underlying physical machine fails, your data since the last backup are lost. Zerops doesn't provide any automatic repairs of a single node PostgreSQL services.
verticalAutoscaling	Optional. Defines custom vertical auto-scaling parameters . All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
- cpuMode	Optional. Accepts SHARED, DEDICATED values. Default is SHARED
- minCpu/maxCpu	Optional. Set the minCpu or maxCpu in CPU cores (integer).
- minRam/maxRam	Optional. Set the minRam or maxRam in GB (float).
- minDisk/maxDisk	Optional. Set the minDisk or maxDisk in GB (float).

Caution

The PostgreSQL service hostname and mode are fixed after the service is created. They can't be changed later.

Create a project based on the description.yml

When you have your description.yml ready, use the zcli project project-import command to create a new project and the service infrastructure.

Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                the project import command.
      --orgId string        If you have access to more than one organization, you must specify the org ID for which the
                            project will be created.
      --workingDie string   Sets a custom working directory. The default working directory is the current directory. (default "./")

Zerops will create a project and one or more services based on the description.yml content.

The maximum size of the description.yml file is 100 kB.

You don't specify the project name in the zcli project project-import command, because the project name is defined in the description.yml.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The clientID is located in the Zerops GUI under the client name on the project dashboard page.

Add PostgreSQL service to an existing project

Example

Create a directory my-project if it doesn't exist. Create an import.yml file inside the my-project directory with following content:

# array of project services
services:
  -
    # service name
    hostname: postgresql1
    # service type and version number in postgresql@{version} format
    type: postgresql@12
    # mode of operation "HA"/"NON_HA"
    mode: NON_HA

The YAML file describes the list of one or more services that you want to add to your existing project. In the example above, one PostgreSQL service in the single container mode with default auto scaling configuration will be added to your project. The hostname of the new service will be set to postgresql1.

The content of the services: section of import.yml is identical to the project description file. The import.yml never contains the project: section because the project already exists.

When your import.yml is ready, use the zcli project service-import command to add one or more services to your existing Zerops project.

Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help               the project service import command.
      --projectId string   If you have access to more than one project, you must specify the project ID for which the
                           command will be executed.

zCLI commands are interactive, when you press enter after zcli project service-import importYamlPath, you will be given a list of your projects to choose from.

The maximum size of the import.yml file is 100 kB.