Skip to content

PostgreSQL

Usage example

apiVersion: aiven.io/v1alpha1
kind: PostgreSQL
metadata:
  name: my-postgresql
spec:
  authSecretRef:
    name: aiven-token
    key: token

  connInfoSecretTarget:
    name: postgresql-secret
    prefix: MY_SECRET_PREFIX_
    annotations:
      foo: bar
    labels:
      baz: egg

  project: aiven-project-name
  cloudName: google-europe-west1
  plan: startup-4

  maintenanceWindowDow: sunday
  maintenanceWindowTime: 11:00:00

  userConfig:
    pg_version: "15"

PostgreSQL

PostgreSQL is the Schema for the postgresql API.

Required

  • apiVersion (string). Value aiven.io/v1alpha1.
  • kind (string). Value PostgreSQL.
  • metadata (object). Data that identifies the object, including a name string and optional namespace.
  • spec (object). PostgreSQLSpec defines the desired state of postgres instance. See below for nested schema.

spec

Appears on PostgreSQL.

PostgreSQLSpec defines the desired state of postgres instance.

Required

  • plan (string, MaxLength: 128). Subscription plan.
  • project (string, Immutable, MaxLength: 63, Format: ^[a-zA-Z0-9_-]+$). Identifies the project this resource belongs to.

Optional

  • authSecretRef (object). Authentication reference to Aiven token in a secret. See below for nested schema.
  • cloudName (string, MaxLength: 256). Cloud the service runs in.
  • connInfoSecretTarget (object). Information regarding secret creation. Exposed keys: POSTGRESQL_HOST, POSTGRESQL_PORT, POSTGRESQL_DATABASE, POSTGRESQL_USER, POSTGRESQL_PASSWORD, POSTGRESQL_SSLMODE, POSTGRESQL_DATABASE_URI, POSTGRESQL_CA_CERT. See below for nested schema.
  • connInfoSecretTargetDisabled (boolean, Immutable). When true, the secret containing connection information will not be created, defaults to false. This field cannot be changed after resource creation.
  • disk_space (string, Format: ^[1-9][0-9]*(GiB|G)*). The disk space of the service, possible values depend on the service type, the cloud provider and the project. Reducing will result in the service re-balancing.
  • maintenanceWindowDow (string, Enum: monday, tuesday, wednesday, thursday, friday, saturday, sunday). Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.
  • maintenanceWindowTime (string, MaxLength: 8). Time of day when maintenance operations should be performed. UTC time in HH:mm:ss format.
  • projectVPCRef (object). ProjectVPCRef reference to ProjectVPC resource to use its ID as ProjectVPCID automatically. See below for nested schema.
  • projectVpcId (string, MaxLength: 36). Identifier of the VPC the service should be in, if any.
  • serviceIntegrations (array of objects, Immutable, MaxItems: 1). Service integrations to specify when creating a service. Not applied after initial service creation. See below for nested schema.
  • tags (object, AdditionalProperties: string). Tags are key-value pairs that allow you to categorize services.
  • technicalEmails (array of objects, MaxItems: 10). Defines the email addresses that will receive alerts about upcoming maintenance updates or warnings about service instability. See below for nested schema.
  • terminationProtection (boolean). Prevent service from being deleted. It is recommended to have this enabled for all services.
  • userConfig (object). PostgreSQL specific user configuration options. See below for nested schema.

authSecretRef

Appears on spec.

Authentication reference to Aiven token in a secret.

Required

  • key (string, MinLength: 1).
  • name (string, MinLength: 1).

connInfoSecretTarget

Appears on spec.

Information regarding secret creation. Exposed keys: POSTGRESQL_HOST, POSTGRESQL_PORT, POSTGRESQL_DATABASE, POSTGRESQL_USER, POSTGRESQL_PASSWORD, POSTGRESQL_SSLMODE, POSTGRESQL_DATABASE_URI, POSTGRESQL_CA_CERT.

Required

  • name (string). Name of the secret resource to be created. By default, it is equal to the resource name.

Optional

  • annotations (object, AdditionalProperties: string). Annotations added to the secret.
  • labels (object, AdditionalProperties: string). Labels added to the secret.
  • prefix (string). Prefix for the secret's keys. Added "as is" without any transformations. By default, is equal to the kind name in uppercase + underscore, e.g. KAFKA_, REDIS_, etc.

projectVPCRef

Appears on spec.

ProjectVPCRef reference to ProjectVPC resource to use its ID as ProjectVPCID automatically.

Required

  • name (string, MinLength: 1).

Optional

serviceIntegrations

Appears on spec.

Service integrations to specify when creating a service. Not applied after initial service creation.

Required

technicalEmails

Appears on spec.

Defines the email addresses that will receive alerts about upcoming maintenance updates or warnings about service instability.

Required

  • email (string, Format: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$). Email address.

userConfig

Appears on spec.

PostgreSQL specific user configuration options.

Optional

  • additional_backup_regions (array of strings, MaxItems: 1). Additional Cloud Regions for Backup Replication.
  • admin_password (string, Immutable, Pattern: ^[a-zA-Z0-9-_]+$, MinLength: 8, MaxLength: 256). Custom password for admin user. Defaults to random string. This must be set only when a new service is being created.
  • admin_username (string, Immutable, Pattern: ^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$, MaxLength: 64). Custom username for admin user. This must be set only when a new service is being created.
  • backup_hour (integer, Minimum: 0, Maximum: 23). The hour of day (in UTC) when backup for the service is started. New backup is only started if previous backup has already completed.
  • backup_minute (integer, Minimum: 0, Maximum: 59). The minute of an hour when backup for the service is started. New backup is only started if previous backup has already completed.
  • enable_ipv6 (boolean). Register AAAA DNS records for the service, and allow IPv6 packets to service ports.
  • ip_filter (array of objects, MaxItems: 1024). Allow incoming connections from CIDR address block, e.g. 10.20.0.0/16. See below for nested schema.
  • migration (object). Migrate data from existing server. See below for nested schema.
  • pg (object). postgresql.conf configuration values. See below for nested schema.
  • pg_qualstats (object). Deprecated. System-wide settings for the pg_qualstats extension. See below for nested schema.
  • pg_read_replica (boolean). Should the service which is being forked be a read replica (deprecated, use read_replica service integration instead).
  • pg_service_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 64). Name of the PG Service from which to fork (deprecated, use service_to_fork_from). This has effect only when a new service is being created.
  • pg_stat_monitor_enable (boolean). Enable the pg_stat_monitor extension. Enabling this extension will cause the cluster to be restarted.When this extension is enabled, pg_stat_statements results for utility commands are unreliable.
  • pg_version (string, Enum: 12, 13, 14, 15, 16). PostgreSQL major version.
  • pgaudit (object). System-wide settings for the pgaudit extension. See below for nested schema.
  • pgbouncer (object). PGBouncer connection pooling settings. See below for nested schema.
  • pglookout (object). System-wide settings for pglookout. See below for nested schema.
  • private_access (object). Allow access to selected service ports from private networks. See below for nested schema.
  • privatelink_access (object). Allow access to selected service components through Privatelink. See below for nested schema.
  • project_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 63). Name of another project to fork a service from. This has effect only when a new service is being created.
  • public_access (object). Allow access to selected service ports from the public Internet. See below for nested schema.
  • recovery_target_time (string, Immutable, MaxLength: 32). Recovery target time when forking a service. This has effect only when a new service is being created.
  • service_log (boolean). Store logs for the service so that they are available in the HTTP API and console.
  • service_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 64). Name of another service to fork from. This has effect only when a new service is being created.
  • shared_buffers_percentage (number, Minimum: 20, Maximum: 60). Percentage of total RAM that the database server uses for shared memory buffers. Valid range is 20-60 (float), which corresponds to 20% - 60%. This setting adjusts the shared_buffers configuration value.
  • static_ips (boolean). Use static public IP addresses.
  • synchronous_replication (string, Enum: quorum, off). Synchronous replication type. Note that the service plan also needs to support synchronous replication.
  • timescaledb (object). System-wide settings for the timescaledb extension. See below for nested schema.
  • variant (string, Enum: aiven, timescale). Variant of the PostgreSQL service, may affect the features that are exposed by default.
  • work_mem (integer, Minimum: 1, Maximum: 1024). Sets the maximum amount of memory to be used by a query operation (such as a sort or hash table) before writing to temporary disk files, in MB. Default is 1MB + 0.075% of total RAM (up to 32MB).

ip_filter

Appears on spec.userConfig.

Allow incoming connections from CIDR address block, e.g. 10.20.0.0/16.

Required

  • network (string, MaxLength: 43). CIDR address block.

Optional

  • description (string, MaxLength: 1024). Description for IP filter list entry.

migration

Appears on spec.userConfig.

Migrate data from existing server.

Required

  • host (string, MaxLength: 255). Hostname or IP address of the server where to migrate data from.
  • port (integer, Minimum: 1, Maximum: 65535). Port number of the server where to migrate data from.

Optional

  • dbname (string, MaxLength: 63). Database name for bootstrapping the initial connection.
  • ignore_dbs (string, MaxLength: 2048). Comma-separated list of databases, which should be ignored during migration (supported by MySQL and PostgreSQL only at the moment).
  • method (string, Enum: dump, replication). The migration method to be used (currently supported only by Redis, Dragonfly, MySQL and PostgreSQL service types).
  • password (string, MaxLength: 256). Password for authentication with the server where to migrate data from.
  • ssl (boolean). The server where to migrate data from is secured with SSL.
  • username (string, MaxLength: 256). User name for authentication with the server where to migrate data from.

pg

Appears on spec.userConfig.

postgresql.conf configuration values.

Optional

  • autovacuum_analyze_scale_factor (number, Minimum: 0, Maximum: 1). Specifies a fraction of the table size to add to autovacuum_analyze_threshold when deciding whether to trigger an ANALYZE. The default is 0.2 (20% of table size).
  • autovacuum_analyze_threshold (integer, Minimum: 0, Maximum: 2147483647). Specifies the minimum number of inserted, updated or deleted tuples needed to trigger an ANALYZE in any one table. The default is 50 tuples.
  • autovacuum_freeze_max_age (integer, Minimum: 200000000, Maximum: 1500000000). Specifies the maximum age (in transactions) that a table's pg_class.relfrozenxid field can attain before a VACUUM operation is forced to prevent transaction ID wraparound within the table. Note that the system will launch autovacuum processes to prevent wraparound even when autovacuum is otherwise disabled. This parameter will cause the server to be restarted.
  • autovacuum_max_workers (integer, Minimum: 1, Maximum: 20). Specifies the maximum number of autovacuum processes (other than the autovacuum launcher) that may be running at any one time. The default is three. This parameter can only be set at server start.
  • autovacuum_naptime (integer, Minimum: 1, Maximum: 86400). Specifies the minimum delay between autovacuum runs on any given database. The delay is measured in seconds, and the default is one minute.
  • autovacuum_vacuum_cost_delay (integer, Minimum: -1, Maximum: 100). Specifies the cost delay value that will be used in automatic VACUUM operations. If -1 is specified, the regular vacuum_cost_delay value will be used. The default value is 20 milliseconds.
  • autovacuum_vacuum_cost_limit (integer, Minimum: -1, Maximum: 10000). Specifies the cost limit value that will be used in automatic VACUUM operations. If -1 is specified (which is the default), the regular vacuum_cost_limit value will be used.
  • autovacuum_vacuum_scale_factor (number, Minimum: 0, Maximum: 1). Specifies a fraction of the table size to add to autovacuum_vacuum_threshold when deciding whether to trigger a VACUUM. The default is 0.2 (20% of table size).
  • autovacuum_vacuum_threshold (integer, Minimum: 0, Maximum: 2147483647). Specifies the minimum number of updated or deleted tuples needed to trigger a VACUUM in any one table. The default is 50 tuples.
  • bgwriter_delay (integer, Minimum: 10, Maximum: 10000). Specifies the delay between activity rounds for the background writer in milliseconds. Default is 200.
  • bgwriter_flush_after (integer, Minimum: 0, Maximum: 2048). Whenever more than bgwriter_flush_after bytes have been written by the background writer, attempt to force the OS to issue these writes to the underlying storage. Specified in kilobytes, default is 512. Setting of 0 disables forced writeback.
  • bgwriter_lru_maxpages (integer, Minimum: 0, Maximum: 1073741823). In each round, no more than this many buffers will be written by the background writer. Setting this to zero disables background writing. Default is 100.
  • bgwriter_lru_multiplier (number, Minimum: 0, Maximum: 10). The average recent need for new buffers is multiplied by bgwriter_lru_multiplier to arrive at an estimate of the number that will be needed during the next round, (up to bgwriter_lru_maxpages). 1.0 represents a “just in time” policy of writing exactly the number of buffers predicted to be needed. Larger values provide some cushion against spikes in demand, while smaller values intentionally leave writes to be done by server processes. The default is 2.0.
  • deadlock_timeout (integer, Minimum: 500, Maximum: 1800000). This is the amount of time, in milliseconds, to wait on a lock before checking to see if there is a deadlock condition.
  • default_toast_compression (string, Enum: lz4, pglz). Specifies the default TOAST compression method for values of compressible columns (the default is lz4).
  • idle_in_transaction_session_timeout (integer, Minimum: 0, Maximum: 604800000). Time out sessions with open transactions after this number of milliseconds.
  • jit (boolean). Controls system-wide use of Just-in-Time Compilation (JIT).
  • log_autovacuum_min_duration (integer, Minimum: -1, Maximum: 2147483647). Causes each action executed by autovacuum to be logged if it ran for at least the specified number of milliseconds. Setting this to zero logs all autovacuum actions. Minus-one (the default) disables logging autovacuum actions.
  • log_error_verbosity (string, Enum: TERSE, DEFAULT, VERBOSE). Controls the amount of detail written in the server log for each message that is logged.
  • log_line_prefix (string, Enum: 'pid=%p,user=%u,db=%d,app=%a,client=%h ', '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h ', '%m [%p] %q[user=%u,db=%d,app=%a] '). Choose from one of the available log-formats. These can support popular log analyzers like pgbadger, pganalyze etc.
  • log_min_duration_statement (integer, Minimum: -1, Maximum: 86400000). Log statements that take more than this number of milliseconds to run, -1 disables.
  • log_temp_files (integer, Minimum: -1, Maximum: 2147483647). Log statements for each temporary file created larger than this number of kilobytes, -1 disables.
  • max_files_per_process (integer, Minimum: 1000, Maximum: 4096). PostgreSQL maximum number of files that can be open per process.
  • max_locks_per_transaction (integer, Minimum: 64, Maximum: 6400). PostgreSQL maximum locks per transaction.
  • max_logical_replication_workers (integer, Minimum: 4, Maximum: 64). PostgreSQL maximum logical replication workers (taken from the pool of max_parallel_workers).
  • max_parallel_workers (integer, Minimum: 0, Maximum: 96). Sets the maximum number of workers that the system can support for parallel queries.
  • max_parallel_workers_per_gather (integer, Minimum: 0, Maximum: 96). Sets the maximum number of workers that can be started by a single Gather or Gather Merge node.
  • max_pred_locks_per_transaction (integer, Minimum: 64, Maximum: 5120). PostgreSQL maximum predicate locks per transaction.
  • max_prepared_transactions (integer, Minimum: 0, Maximum: 10000). PostgreSQL maximum prepared transactions.
  • max_replication_slots (integer, Minimum: 8, Maximum: 64). PostgreSQL maximum replication slots.
  • max_slot_wal_keep_size (integer, Minimum: -1, Maximum: 2147483647). PostgreSQL maximum WAL size (MB) reserved for replication slots. Default is -1 (unlimited). wal_keep_size minimum WAL size setting takes precedence over this.
  • max_stack_depth (integer, Minimum: 2097152, Maximum: 6291456). Maximum depth of the stack in bytes.
  • max_standby_archive_delay (integer, Minimum: 1, Maximum: 43200000). Max standby archive delay in milliseconds.
  • max_standby_streaming_delay (integer, Minimum: 1, Maximum: 43200000). Max standby streaming delay in milliseconds.
  • max_wal_senders (integer, Minimum: 20, Maximum: 64). PostgreSQL maximum WAL senders.
  • max_worker_processes (integer, Minimum: 8, Maximum: 96). Sets the maximum number of background processes that the system can support.
  • pg_partman_bgw.interval (integer, Minimum: 3600, Maximum: 604800). Sets the time interval to run pg_partman's scheduled tasks.
  • pg_partman_bgw.role (string, Pattern: ^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$, MaxLength: 64). Controls which role to use for pg_partman's scheduled background tasks.
  • pg_stat_monitor.pgsm_enable_query_plan (boolean). Enables or disables query plan monitoring.
  • pg_stat_monitor.pgsm_max_buckets (integer, Minimum: 1, Maximum: 10). Sets the maximum number of buckets.
  • pg_stat_statements.track (string, Enum: all, top, none). Controls which statements are counted. Specify top to track top-level statements (those issued directly by clients), all to also track nested statements (such as statements invoked within functions), or none to disable statement statistics collection. The default value is top.
  • temp_file_limit (integer, Minimum: -1, Maximum: 2147483647). PostgreSQL temporary file limit in KiB, -1 for unlimited.
  • timezone (string, Pattern: ^[\w/]*$, MaxLength: 64). PostgreSQL service timezone.
  • track_activity_query_size (integer, Minimum: 1024, Maximum: 10240). Specifies the number of bytes reserved to track the currently executing command for each active session.
  • track_commit_timestamp (string, Enum: off, on). Record commit time of transactions.
  • track_functions (string, Enum: all, pl, none). Enables tracking of function call counts and time used.
  • track_io_timing (string, Enum: off, on). Enables timing of database I/O calls. This parameter is off by default, because it will repeatedly query the operating system for the current time, which may cause significant overhead on some platforms.
  • wal_sender_timeout (integer). Terminate replication connections that are inactive for longer than this amount of time, in milliseconds. Setting this value to zero disables the timeout.
  • wal_writer_delay (integer, Minimum: 10, Maximum: 200). WAL flush interval in milliseconds. Note that setting this value to lower than the default 200ms may negatively impact performance.

pg_qualstats

Appears on spec.userConfig.

Deprecated. System-wide settings for the pg_qualstats extension.

Optional

  • enabled (boolean). Deprecated. Enable / Disable pg_qualstats.
  • min_err_estimate_num (integer, Minimum: 0). Deprecated. Error estimation num threshold to save quals.
  • min_err_estimate_ratio (integer, Minimum: 0). Deprecated. Error estimation ratio threshold to save quals.
  • track_constants (boolean). Deprecated. Enable / Disable pg_qualstats constants tracking.
  • track_pg_catalog (boolean). Deprecated. Track quals on system catalogs too.

pgaudit

Appears on spec.userConfig.

System-wide settings for the pgaudit extension.

Optional

  • feature_enabled (boolean). Enable pgaudit extension. When enabled, pgaudit extension will be automatically installed.Otherwise, extension will be uninstalled but auditing configurations will be preserved.
  • log (array of strings). Specifies which classes of statements will be logged by session audit logging.
  • log_catalog (boolean). Specifies that session logging should be enabled in the casewhere all relations in a statement are in pg_catalog.
  • log_client (boolean). Specifies whether log messages will be visible to a client process such as psql.
  • log_level (string, Enum: debug1, debug2, debug3, debug4, debug5, info, notice, warning, log). Specifies the log level that will be used for log entries.
  • log_max_string_length (integer, Minimum: -1, Maximum: 102400). Crop parameters representation and whole statements if they exceed this threshold. A (default) value of -1 disable the truncation.
  • log_nested_statements (boolean). This GUC allows to turn off logging nested statements, that is, statements that are executed as part of another ExecutorRun.
  • log_parameter (boolean). Specifies that audit logging should include the parameters that were passed with the statement.
  • log_parameter_max_size (integer). Specifies that parameter values longer than this setting (in bytes) should not be logged, but replaced with .
  • log_relation (boolean). Specifies whether session audit logging should create a separate log entry for each relation (TABLE, VIEW, etc.) referenced in a SELECT or DML statement.
  • log_rows (boolean). Specifies that audit logging should include the rows retrieved or affected by a statement. When enabled the rows field will be included after the parameter field.
  • log_statement (boolean). Specifies whether logging will include the statement text and parameters (if enabled).
  • log_statement_once (boolean). Specifies whether logging will include the statement text and parameters with the first log entry for a statement/substatement combination or with every entry.
  • role (string, Pattern: ^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$, MaxLength: 64). Specifies the master role to use for object audit logging.

pgbouncer

Appears on spec.userConfig.

PGBouncer connection pooling settings.

Optional

  • autodb_idle_timeout (integer, Minimum: 0, Maximum: 86400). If the automatically created database pools have been unused this many seconds, they are freed. If 0 then timeout is disabled. [seconds].
  • autodb_max_db_connections (integer, Minimum: 0, Maximum: 2147483647). Do not allow more than this many server connections per database (regardless of user). Setting it to 0 means unlimited.
  • autodb_pool_mode (string, Enum: session, transaction, statement). PGBouncer pool mode.
  • autodb_pool_size (integer, Minimum: 0, Maximum: 10000). If non-zero then create automatically a pool of that size per user when a pool doesn't exist.
  • ignore_startup_parameters (array of strings, MaxItems: 32). List of parameters to ignore when given in startup packet.
  • min_pool_size (integer, Minimum: 0, Maximum: 10000). Add more server connections to pool if below this number. Improves behavior when usual load comes suddenly back after period of total inactivity. The value is effectively capped at the pool size.
  • server_idle_timeout (integer, Minimum: 0, Maximum: 86400). If a server connection has been idle more than this many seconds it will be dropped. If 0 then timeout is disabled. [seconds].
  • server_lifetime (integer, Minimum: 60, Maximum: 86400). The pooler will close an unused server connection that has been connected longer than this. [seconds].
  • server_reset_query_always (boolean). Run server_reset_query (DISCARD ALL) in all pooling modes.

pglookout

Appears on spec.userConfig.

System-wide settings for pglookout.

Required

private_access

Appears on spec.userConfig.

Allow access to selected service ports from private networks.

Optional

  • pg (boolean). Allow clients to connect to pg with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.
  • pgbouncer (boolean). Allow clients to connect to pgbouncer with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.
  • prometheus (boolean). Allow clients to connect to prometheus with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.

Appears on spec.userConfig.

Allow access to selected service components through Privatelink.

Optional

  • pg (boolean). Enable pg.
  • pgbouncer (boolean). Enable pgbouncer.
  • prometheus (boolean). Enable prometheus.

public_access

Appears on spec.userConfig.

Allow access to selected service ports from the public Internet.

Optional

  • pg (boolean). Allow clients to connect to pg from the public internet for service nodes that are in a project VPC or another type of private network.
  • pgbouncer (boolean). Allow clients to connect to pgbouncer from the public internet for service nodes that are in a project VPC or another type of private network.
  • prometheus (boolean). Allow clients to connect to prometheus from the public internet for service nodes that are in a project VPC or another type of private network.

timescaledb

Appears on spec.userConfig.

System-wide settings for the timescaledb extension.

Required

  • max_background_workers (integer, Minimum: 1, Maximum: 4096). The number of background workers for timescaledb operations. You should configure this setting to the sum of your number of databases and the total number of concurrent background workers you want running at any given point in time.