Create a DBaaS PostgreSQL service

POST /dbaas-postgres/{name}

Path parameters

  • name string Required

    Service name

    Minimum length is 0, maximum length is 63.

application/json

Body Required

  • PGBouncer connection pooling settings

    Hide pgbouncer-settings attributes Show pgbouncer-settings attributes
  • Hide backup-schedule attributes Show backup-schedule attributes
    • backup-hour integer(int64)

      The hour of day (in UTC) when backup for the service is started. New backup is only started if previous backup has already completed.

      Minimum value is 0, maximum value is 23.

    • backup-minute integer(int64)

      The minute of an hour when backup for the service is started. New backup is only started if previous backup has already completed.

      Minimum value is 0, maximum value is 59.

  • variant string

    Variant of the PostgreSQL service, may affect the features that are exposed by default

    Values are timescale or aiven.

  • integrations array[object]

    Service integrations to be enabled when creating the service.

    Hide integrations attributes Show integrations attributes object
    • type string Required

      Integration type

      Value is read_replica.

    • Service name

      Minimum length is 0, maximum length is 63.

    • Service name

      Minimum length is 0, maximum length is 63.

    • settings object

      Integration settings

  • TimescaleDB extension configuration values

    Hide timescaledb-settings attributes Show timescaledb-settings attributes
    • 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.

      Minimum value is 1, maximum value is 4096.

  • ip-filter array[string]

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

  • Service is protected against termination and powering off

  • Service name

    Minimum length is 0, maximum length is 63.

  • Synchronous replication type. Note that the service plan also needs to support synchronous replication.

    Values are quorum or off.

  • ISO time of a backup to recover from for services that support arbitrary times

    Minimum length is 1.

  • PGLookout settings

    Default value is {"max_failover_replication_time_lag"=>60}.

    Hide pglookout-settings attributes Show pglookout-settings attributes
  • Automatic maintenance settings

    Hide maintenance attributes Show maintenance attributes
    • dow string Required

      Day of week for installing updates

      Values are saturday, tuesday, never, wednesday, sunday, friday, monday, or thursday.

    • time string Required

      Time for installing updates, UTC

      Minimum length is 8, maximum length is 8.

  • Custom username for admin user. This must be set only when a new service is being created.

    Minimum length is 1, maximum length is 64. Format should match the following pattern: ^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$.

  • version string

    Target version for upgrade

    Values are 14, 15, 12, 13, or 16.

  • plan string Required

    Subscription plan

    Minimum length is 1, maximum length is 128.

  • work-mem integer(int64)

    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).

    Minimum value is 1, maximum value is 1024.

  • 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.

    Minimum value is 20, maximum value is 60.

  • PostgreSQL-specific settings

    Hide pg-settings attributes Show pg-settings attributes
    • Specifies the number of bytes reserved to track the currently executing command for each active session.

      Minimum value is 1024, maximum value is 10240.

    • timezone string

      PostgreSQL service timezone

      Maximum length is 64.

    • 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.

      Values are off or on.

    • Enables or disables query plan monitoring

    • PostgreSQL maximum number of files that can be open per process

      Minimum value is 1000, maximum value is 4096.

    • Sets the maximum number of buckets

      Minimum value is 1, maximum value is 10.

    • wal object
      Hide wal attributes Show wal attributes
      • WAL flush interval in milliseconds. Note that setting this value to lower than the default 200ms may negatively impact performance

        Minimum value is 10, maximum value is 200.

      • wal_sender_timeout integer
        Any of:

        Terminate replication connections that are inactive for longer than this amount of time, in milliseconds. Setting this value to zero disables the timeout.

        Minimum value is 0, maximum value is 0.

        Terminate replication connections that are inactive for longer than this amount of time, in milliseconds. Setting this value to zero disables the timeout.

        Minimum value is 5000, maximum value is 10800000.

      • PostgreSQL maximum WAL senders

        Minimum value is 20, maximum value is 64.

      • PostgreSQL maximum WAL size (MB) reserved for replication slots. Default is -1 (unlimited). wal_keep_size minimum WAL size setting takes precedence over this.

        Minimum value is -1, maximum value is 2147483647.

    • Specifies the default TOAST compression method for values of compressible columns (the default is lz4).

      Values are lz4 or pglz.

    • This is the amount of time, in milliseconds, to wait on a lock before checking to see if there is a deadlock condition.

      Minimum value is 500, maximum value is 1800000.

    • Time out sessions with open transactions after this number of milliseconds

      Minimum value is 0, maximum value is 604800000.

    • PostgreSQL maximum predicate locks per transaction

      Minimum value is 64, maximum value is 5120.

    • PostgreSQL maximum replication slots

      Minimum value is 8, maximum value is 64.

    • Hide autovacuum attributes Show autovacuum attributes
      • 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.

        Minimum value is -1, maximum value is 2147483647.

      • 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.

        Minimum value is -1, maximum value is 10000.

      • 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.

        Minimum value is 1, maximum value is 20.

      • Specifies the minimum number of updated or deleted tuples needed to trigger a VACUUM in any one table. The default is 50 tuples

        Minimum value is 0, maximum value is 2147483647.

      • Specifies the minimum delay between autovacuum runs on any given database. The delay is measured in seconds, and the default is one minute

        Minimum value is 1, maximum value is 86400.

      • 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)

        Minimum value is 0.0, maximum value is 1.0.

      • 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

        Minimum value is -1, maximum value is 100.

      • 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)

        Minimum value is 0.0, maximum value is 1.0.

      • Specifies the minimum number of inserted, updated or deleted tuples needed to trigger an ANALYZE in any one table. The default is 50 tuples.

        Minimum value is 0, maximum value is 2147483647.

      • 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.

        Minimum value is 200000000, maximum value is 1500000000.

    • Sets the maximum number of workers that can be started by a single Gather or Gather Merge node

      Minimum value is 0, maximum value is 96.

    • Sets the time interval to run pg_partman's scheduled tasks

      Minimum value is 3600, maximum value is 604800.

    • Choose from one of the available log-formats. These can support popular log analyzers like pgbadger, pganalyze etc.

      Values are 'pid=%p,user=%u,db=%d,app=%a,client=%h ', '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h ', or '%m [%p] %q[user=%u,db=%d,app=%a] '.

    • Log statements for each temporary file created larger than this number of kilobytes, -1 disables

      Minimum value is -1, maximum value is 2147483647.

    • PostgreSQL maximum locks per transaction

      Minimum value is 64, maximum value is 6400.

    • Record commit time of transactions.

      Values are off or on.

    • Enables tracking of function call counts and time used.

      Values are all, pl, or none.

    • Maximum depth of the stack in bytes

      Minimum value is 2097152, maximum value is 6291456.

    • Sets the maximum number of workers that the system can support for parallel queries

      Minimum value is 0, maximum value is 96.

    • Controls which role to use for pg_partman's scheduled background tasks.

      Maximum length is 64. Format should match the following pattern: ^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$.

    • PostgreSQL maximum logical replication workers (taken from the pool of max_parallel_workers)

      Minimum value is 4, maximum value is 64.

    • PostgreSQL maximum prepared transactions

      Minimum value is 0, maximum value is 10000.

    • Sets the maximum number of background processes that the system can support

      Minimum value is 8, maximum value is 96.

    • 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.

      Values are all, top, or none.

    • PostgreSQL temporary file limit in KiB, -1 for unlimited

      Minimum value is -1, maximum value is 2147483647.

    • Controls the amount of detail written in the server log for each message that is logged.

      Values are TERSE, DEFAULT, or VERBOSE.

    • Log statements that take more than this number of milliseconds to run, -1 disables

      Minimum value is -1, maximum value is 86400000.

    • Max standby streaming delay in milliseconds

      Minimum value is 1, maximum value is 43200000.

    • jit boolean

      Controls system-wide use of Just-in-Time Compilation (JIT).

    • Max standby archive delay in milliseconds

      Minimum value is 1, maximum value is 43200000.

    • Hide bg-writer attributes Show bg-writer attributes
      • Specifies the delay between activity rounds for the background writer in milliseconds. Default is 200.

        Minimum value is 10, maximum value is 10000.

      • 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.

        Minimum value is 0, maximum value is 2048.

      • 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.

        Minimum value is 0, maximum value is 10.

      • 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.

        Minimum value is 0, maximum value is 1073741823.

  • Custom password for admin user. Defaults to random string. This must be set only when a new service is being created.

    Minimum length is 8, maximum length is 256. Format should match the following pattern: ^[a-zA-Z0-9-_]+$.

  • Migrate data from existing server

    Hide migration attributes Show migration attributes
    • host string Required

      Hostname or IP address of the server where to migrate data from

      Minimum length is 1, maximum length is 255.

    • port integer(int64) Required

      Port number of the server where to migrate data from

      Minimum value is 1, maximum value is 65535.

    • password string

      Password for authentication with the server where to migrate data from

      Minimum length is 1, maximum length is 255.

    • ssl boolean

      The server where to migrate data from is secured with SSL

    • username string

      User name for authentication with the server where to migrate data from

      Minimum length is 1, maximum length is 255.

    • dbname string

      Database name for bootstrapping the initial connection

      Minimum length is 1, maximum length is 63.

    • Comma-separated list of databases, which should be ignored during migration (supported by MySQL only at the moment)

      Minimum length is 1, maximum length is 2048.

    • method string

      The migration method to be used

      Values are dump or replication.

Responses

  • 200 application/json

    200

    Hide response attributes Show response attributes object
    • id string(uuid)

      Operation ID

    • reason string

      Operation failure reason

      Values are incorrect, unknown, unavailable, forbidden, busy, fault, partial, not-found, interrupted, unsupported, or conflict.

    • Related resource reference

      Hide reference attributes Show reference attributes
      • id string(uuid)

        Reference ID

      • command string

        Command name

    • message string

      Operation message

    • state string

      Operation status

      Values are failure, pending, success, or timeout.

POST /dbaas-postgres/{name}
curl \
 -X POST https://api-ch-gva-2.exoscale.com/v2/dbaas-postgres/{name} \
 -H "Content-Type: application/json" \
 -d '{"pgbouncer-settings":{"min_pool_size":0,"ignore_startup_parameters":["extra_float_digits","search_path"],"server_lifetime":3600,"autodb_pool_mode":"session","server_idle_timeout":600,"autodb_max_db_connections":0,"server_reset_query_always":false,"autodb_pool_size":0,"autodb_idle_timeout":3600},"backup-schedule":{"backup-hour":42,"backup-minute":42},"variant":"timescale","integrations":[{"type":"read_replica","source-service":"string","dest-service":"string","settings":{}}],"timescaledb-settings":{"max_background_workers":8},"ip-filter":["string"],"termination-protection":true,"fork-from-service":"string","synchronous-replication":"quorum","recovery-backup-time":"string","pglookout-settings":{"max_failover_replication_time_lag":60},"maintenance":{"dow":"saturday","time":"string"},"admin-username":"string","version":"14","plan":"string","work-mem":42,"shared-buffers-percentage":42,"pg-settings":{"track_activity_query_size":1024,"timezone":"Europe/Helsinki","track_io_timing":"off","pg_stat_monitor.pgsm_enable_query_plan":false,"max_files_per_process":42,"pg_stat_monitor.pgsm_max_buckets":10,"wal":{"wal_writer_delay":50,"wal_sender_timeout":60000,"max_wal_senders":42,"max_slot_wal_keep_size":42},"default_toast_compression":"lz4","deadlock_timeout":1000,"idle_in_transaction_session_timeout":42,"max_pred_locks_per_transaction":42,"max_replication_slots":42,"autovacuum":{"log_autovacuum_min_duration":42,"autovacuum_vacuum_cost_limit":42,"autovacuum_max_workers":42,"autovacuum_vacuum_threshold":42,"autovacuum_naptime":42,"autovacuum_vacuum_scale_factor":42.0,"autovacuum_vacuum_cost_delay":42,"autovacuum_analyze_scale_factor":42.0,"autovacuum_analyze_threshold":42,"autovacuum_freeze_max_age":200000000},"max_parallel_workers_per_gather":42,"pg_partman_bgw.interval":3600,"log_line_prefix":"'pid=%p,user=%u,db=%d,app=%a,client=%h '","log_temp_files":42,"max_locks_per_transaction":42,"track_commit_timestamp":"off","track_functions":"all","max_stack_depth":42,"max_parallel_workers":42,"pg_partman_bgw.role":"myrolename","max_logical_replication_workers":42,"max_prepared_transactions":42,"max_worker_processes":42,"pg_stat_statements.track":"all","temp_file_limit":5000000,"log_error_verbosity":"TERSE","log_min_duration_statement":42,"max_standby_streaming_delay":42,"jit":true,"max_standby_archive_delay":42,"bg-writer":{"bgwriter_delay":200,"bgwriter_flush_after":512,"bgwriter_lru_multiplier":2.0,"bgwriter_lru_maxpages":100}},"admin-password":"string","migration":{"host":"string","port":42,"password":"string","ssl":true,"username":"string","dbname":"string","ignore-dbs":"string","method":"dump"}}'
Request example
{
  "pgbouncer-settings": {
    "min_pool_size": 0,
    "ignore_startup_parameters": [
      "extra_float_digits",
      "search_path"
    ],
    "server_lifetime": 3600,
    "autodb_pool_mode": "session",
    "server_idle_timeout": 600,
    "autodb_max_db_connections": 0,
    "server_reset_query_always": false,
    "autodb_pool_size": 0,
    "autodb_idle_timeout": 3600
  },
  "backup-schedule": {
    "backup-hour": 42,
    "backup-minute": 42
  },
  "variant": "timescale",
  "integrations": [
    {
      "type": "read_replica",
      "source-service": "string",
      "dest-service": "string",
      "settings": {}
    }
  ],
  "timescaledb-settings": {
    "max_background_workers": 8
  },
  "ip-filter": [
    "string"
  ],
  "termination-protection": true,
  "fork-from-service": "string",
  "synchronous-replication": "quorum",
  "recovery-backup-time": "string",
  "pglookout-settings": {
    "max_failover_replication_time_lag": 60
  },
  "maintenance": {
    "dow": "saturday",
    "time": "string"
  },
  "admin-username": "string",
  "version": "14",
  "plan": "string",
  "work-mem": 42,
  "shared-buffers-percentage": 42,
  "pg-settings": {
    "track_activity_query_size": 1024,
    "timezone": "Europe/Helsinki",
    "track_io_timing": "off",
    "pg_stat_monitor.pgsm_enable_query_plan": false,
    "max_files_per_process": 42,
    "pg_stat_monitor.pgsm_max_buckets": 10,
    "wal": {
      "wal_writer_delay": 50,
      "wal_sender_timeout": 60000,
      "max_wal_senders": 42,
      "max_slot_wal_keep_size": 42
    },
    "default_toast_compression": "lz4",
    "deadlock_timeout": 1000,
    "idle_in_transaction_session_timeout": 42,
    "max_pred_locks_per_transaction": 42,
    "max_replication_slots": 42,
    "autovacuum": {
      "log_autovacuum_min_duration": 42,
      "autovacuum_vacuum_cost_limit": 42,
      "autovacuum_max_workers": 42,
      "autovacuum_vacuum_threshold": 42,
      "autovacuum_naptime": 42,
      "autovacuum_vacuum_scale_factor": 42.0,
      "autovacuum_vacuum_cost_delay": 42,
      "autovacuum_analyze_scale_factor": 42.0,
      "autovacuum_analyze_threshold": 42,
      "autovacuum_freeze_max_age": 200000000
    },
    "max_parallel_workers_per_gather": 42,
    "pg_partman_bgw.interval": 3600,
    "log_line_prefix": "'pid=%p,user=%u,db=%d,app=%a,client=%h '",
    "log_temp_files": 42,
    "max_locks_per_transaction": 42,
    "track_commit_timestamp": "off",
    "track_functions": "all",
    "max_stack_depth": 42,
    "max_parallel_workers": 42,
    "pg_partman_bgw.role": "myrolename",
    "max_logical_replication_workers": 42,
    "max_prepared_transactions": 42,
    "max_worker_processes": 42,
    "pg_stat_statements.track": "all",
    "temp_file_limit": 5000000,
    "log_error_verbosity": "TERSE",
    "log_min_duration_statement": 42,
    "max_standby_streaming_delay": 42,
    "jit": true,
    "max_standby_archive_delay": 42,
    "bg-writer": {
      "bgwriter_delay": 200,
      "bgwriter_flush_after": 512,
      "bgwriter_lru_multiplier": 2.0,
      "bgwriter_lru_maxpages": 100
    }
  },
  "admin-password": "string",
  "migration": {
    "host": "string",
    "port": 42,
    "password": "string",
    "ssl": true,
    "username": "string",
    "dbname": "string",
    "ignore-dbs": "string",
    "method": "dump"
  }
}
Response examples (200)
{
  "id": "string",
  "reason": "incorrect",
  "reference": {
    "id": "string",
    "link": "string",
    "command": "string"
  },
  "message": "string",
  "state": "failure"
}