PostgreSQLAdministrators

Manage the compute plans

Where the PostgreSQL compute plans are stored, which of them the module resets on every start, how to add a plan of your own, and where the storage classes come from.

The PostgreSQL compute plans are rows in the table db_postgres.postgres_compute_plans in the platform database. There is no page in the portal and no API to change them: you change the rows. The module connects to that database with the connection string in the Secret stackship-db-credentials (key connection-string) in stackship-system.

The table

Column	Holds
`name`	The plan's name, at most 90 characters; unique
`description`	The text the portal shows with it
`cpu_request`, `cpu_limit`	CPU per instance, as a Kubernetes quantity such as `500m` or `2`
`memory_request`, `memory_limit`	Memory per instance, such as `4Gi`. Keep them equal: PostgreSQL sizes its memory against the limit
`storage_size`	The data volume of a new cluster, such as `50Gi`
`storage_class`	The storage class of a new cluster's volumes
`wal_storage_size`	The separate WAL volume, or `NULL` for none
`replicas`	The number of instances
`is_production_ready`	Marks a production tier
`engine_parameters_json`	PostgreSQL parameters, as a JSON object of name and value, written into a cluster created from the plan
`pooling_enabled`, `pooling_mode`, `pooling_instances`	Whether a cluster created through the CLI or the API without saying otherwise gets PgBouncer, and how
`id`, `created_utc`	A UUID and a timestamp

The seven built-in plans

Every time the module starts it writes the plans nano, small, medium, standard, large, xlarge and 2xlarge back to the values it ships with, parameters included. A change to one of those rows lasts until the next start. Rows with any other name are left alone.

Add a plan

Add a row under a name of your own:

sql

INSERT INTO db_postgres.postgres_compute_plans
  (id, name, description, cpu_request, cpu_limit, memory_request, memory_limit,
   storage_size, storage_class, wal_storage_size, replicas, is_production_ready,
   engine_parameters_json, pooling_enabled, pooling_mode, pooling_instances, created_utc)
VALUES
  (gen_random_uuid(), 'reporting', 'Two instances for reporting workloads.',
   '2000m', '4000m', '8Gi', '8Gi', '200Gi', '<storage-class>', '16Gi', 2, true,
   '{"shared_buffers":"2GB","effective_cache_size":"5734MB","max_connections":"200"}',
   false, NULL, NULL, now());

Creating a cluster, changing its plan and listing the plans read the table directly. The plan an existing cluster is shown on comes from a copy each module instance keeps for up to a minute, so it can lag behind an edit for that long. Do not call a plan custom: that name means a cluster that matches no plan.

How clusters relate to plans

A cluster does not store its plan. Each time a cluster is read, the module compares its CPU, memory and instance count with the catalogue and reports the plan that matches, or Custom. Changing a plan's CPU, memory or replicas therefore changes nothing in running clusters — but the clusters created from it no longer match, and show as Custom. Deleting a plan does the same, unless another plan has the same shape. Renaming a plan only changes the name its clusters show.

A plan that no node of the target cluster could run is refused on create and on a plan change. Which plans a boundary may use is decided by its compute plan policies.

Storage classes

The built-in plans take their storage class from the module's settings Storage__Standard — for nano and small — and Storage__Premium for the others; the installer calls them Standard Storage Class and Premium Storage Class. They are listed in the module's configuration reference. A changed setting reaches the rows at the module's next start, and from then on new clusters; an existing cluster keeps the class its volumes were created with.