Release Notes and Announcements

Release Notes

Product Announcements

Product Introduction

Overview

Features

Strengths

Scenarios

Information Security

Regions and AZs

Product Feature List

Large version lifecycle description

MSSQL Compatible Version

Billing

Billing Overview

Instance Type and Specification

Purchase Methods

Refund

Overdue Payments

Backup Space Billing

Database Audit Billing Overview

Getting Started

Creating TencentDB for PostgreSQL Instance

Connecting to TencentDB for PostgreSQL Instance

Managing TencentDB for PostgreSQL Instance

Importing Data

Migrating Data with DTS

Kernel Version Introduction

Kernel Version Overview

Kernel Version Release Notes

Viewing Kernel Version

Proprietary Kernel Features

Database Audit

Audit Service Description

Activating Audit Service

View Audit Logs

Modify audit services

Audit Performance Description

User Guide

Instance Management

Upgrading Instance

CPU Elastic Scaling

Read-Only Instance

Account Management

Database Management

Parameter Management

Log Management and Analysis

Backup and Restoration

Data Migration

Extension Management

Network Management

Access Management

Data Security

Tenant and Resource Isolation

Security Groups

Monitoring and Alarms

Tag

AI Practice

Using the Tencentdb_ai Plug-In to Call Large Models

Building Ai Applications with the Tencentdb Ai Plug-In

Combining Supabase to Quickly Build Backend Service Based on TencentDB for PostgreSQL

Use Cases

postgres_fdw Extension for Cross-database Access

Automatically Creating Partition in PostgreSQL

Searching in High Numbers of Tags Based on pg_roaringbitmap

Querying People Nearby with One SQL Statement

Configuring TencentDB for PostgreSQL as GitLab's External Data Source

Supporting Tiered Storage Based on cos_fdw Extension

Implement Read/Write Separation via pgpool

Implementing Slow SQL Analysis Using the Auto_explain Plugin

Using pglogical for Logical Replication

Using Debezium to Collect PostgreSQL Data

Set Up a Remote Disaster Recovery Environment for PostgreSQL Locally on CVM

Read-Only Instance and Read-Only Group Practical Tutorial

How to Use SCF for Scheduled Database Operations

Fix Table Bloat

Performance White Paper

Test Methods

Test Results

API Documentation

History

Introduction

API Category

Making API Requests

Instance APIs

Read-Only Instance APIs

Backup and Recovery APIs

Parameter Management APIs

Security Group APIs

Performance Optimization APIs

Account APIs

Specification APIs

Network APIs

Data Types

Error Codes

FAQs

Service Agreement

Service Level Agreement

Glossary

CreateReadOnlyDBInstance

PDF

Focus Mode

Font Size

Last updated: 2026-04-01 18:23:13

1. API Description

Domain name for API request: postgres.intl.tencentcloudapi.com.

This API is used to create read-only replicas.

A maximum of 100 requests can be initiated per second for this API.

We recommend you to use API Explorer

Try it

API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name	Required	Type	Description
Action	Yes	String	Common Params. The value used for this API: CreateReadOnlyDBInstance.
Version	Yes	String	Common Params. The value used for this API: 2017-03-12.
Region	Yes	String	Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-bangkok, ap-beijing, ap-chengdu, ap-chongqing, ap-guangzhou, ap-hongkong, ap-jakarta, ap-nanjing, ap-seoul, ap-shanghai, ap-shanghai-fsi, ap-shenzhen-fsi, ap-singapore, ap-tokyo, eu-frankfurt, na-ashburn, na-siliconvalley, sa-saopaulo.
Zone	Yes	String	Primary AZ of an instance, such as "ap-guangzhou-3". The information of AZ can be obtained from the `Zone` field in the return value of the DescribeZones API.
MasterDBInstanceId	Yes	String	Primary instance ID of the read-only instance. obtain through the api DescribeDBInstances.
SpecCode	Yes	String	Purchasable code, which can be obtained from the `SpecCode` field in the return value of the DescribeClasses API.
Storage	Yes	Integer	Instance disk capacity size in GB. specifies the step length for parameter settings as 10.
InstanceCount	Yes	Integer	Number of instances to purchase. value range: [1-6]. maximum allowed number is 6.
Period	Yes	Integer	Purchase duration, in months. Prepaid: supports `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `24`, and `36`. . Pay-as-you-go: Only supports `1`.
VpcId	No	String	VPC ID, in the format of vpc-xxxxxxxx (this parameter is currently required). A valid VpcId can be obtained by logging into the console; it can also be obtained from the unVpcId field in the return value of calling of the DescribeVpcEx API.
SubnetId	No	String	VPC subnet ID, in the format of subnet-xxxxxxxx (this parameter is currently required). A valid VPC subnet ID can be obtained by logging into the console; it can also be obtained from the unSubnetId field in the return value of calling of the DescribeSubnets API.
InstanceChargeType	No	String	Instance billing type, which currently supports:. PREPAID: prepaid, i.e., yearly/monthly subscription. . POSTPAID_BY_HOUR: pay-as-you-go, i.e., pay by consumption. . Default value: PREPAID. if the primary instance is postpaid, the read-only instance must also be postpaid.
AutoVoucher	No	Integer	Specifies whether to automatically use a voucher. 0: no. . `1`: yes. . Default value: 0
VoucherIds.N	No	Array of String	Voucher ID list. Currently, you can specify only one voucher.
AutoRenewFlag	No	Integer	Specifies the auto-renewal flag. `0`: manual renewal. . `1`: auto-renewal . Default value: 0
ProjectId	No	Integer	Project ID. default value is 0, means it belongs to the default project.
ActivityId	No	Integer	Special offer ID
ReadOnlyGroupId	No	String	RO group ID
TagList	No	Tag	The information of tags to be bound with the instance, which is left empty by default. This parameter can be obtained from the `Tags` field in the return value of the DescribeTags API.
SecurityGroupIds.N	No	Array of String	Security group of the instance, which can be obtained from the `sgld` field in the return value of the DescribeSecurityGroups API. If this parameter is not specified, the default security group will be bound.
NeedSupportIpv6	No	Integer	Specifies whether to support Ipv6. 0: no. . `1`: yes. . Default value: 0
Name	No	String	Instance name. only chinese characters, letters, digits, underscores (_), and delimiters (-) are supported. the length must be less than 60 characters.
DedicatedClusterId	No	String	CDC ID.
DeletionProtection	No	Boolean	Specifies whether to enable deletion protection for the instance. valid values: true (enable deletion protection), false (disable deletion protection).

3. Output Parameters

Parameter Name	Type	Description
DealNames	Array of String	Order number list. Each instance corresponds to an order number.
BillId	String	Bill ID of frozen fees
DBInstanceIdSet	Array of String	ID set of instances which have been created successfully. The parameter value will be returned only when the pay-as-you-go billing mode is used.
BillingParameters	String	BillingParameters specifies the parameters for product order placement. the output has a value only when billingparameters is provided.
RequestId	String	The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Creating a Read-Only Instance

This example shows you how to create a read-only instance, specify the primary instance as postgres-abcdef, and trigger the creation.

Input Example

POST / HTTP/1.1
Host: postgres.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateReadOnlyDBInstance
<Common request parameters>

{
    "DBVersion": "12.22",
    "InstanceChargeType": "POSTPAID_BY_HOUR",
    "InstanceCount": 1,
    "MasterDBInstanceId": "postgres-abcdef",
    "Period": 1,
    "ProjectId": 1,
    "ReadOnlyGroupId": "",
    "SecurityGroupIds": [
        "sg-iwnfp51z"
    ],
    "SpecCode": "pg.it.small2",
    "Storage": 100,
    "SubnetId": "subnet-1i9huswn",
    "VpcId": "vpc-8btfafeo",
    "Zone": "ap-beijing-4"
}

Output Example

{
    "Response": {
        "BillId": "2701077795",
        "DBInstanceIdSet": [],
        "DealNames": [
            "20251009929109544409421"
        ],
        "RequestId": "f3b13348-be76-4631-8d2f-0c8da1e07958"
    }
}

Example2 Creating a Read-Only Instance with Verification Mode

This example shows you how to create a read-only instance, specify the primary instance as postgres-abcdef, and validate without actual initiation.

Input Example

POST / HTTP/1.1
Host: postgres.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateReadOnlyDBInstance
<Common request parameters>

{
    "DBVersion": "12.22",
    "InstanceChargeType": "POSTPAID_BY_HOUR",
    "InstanceCount": 1,
    "MasterDBInstanceId": "postgres-abcdef",
    "Period": 1,
    "ProjectId": 1,
    "ReadOnlyGroupId": "",
    "SecurityGroupIds": [
        "sg-iwnfp51z"
    ],
    "SpecCode": "pg.it.small2",
    "Storage": 100,
    "SubnetId": "subnet-1i9huswn",
    "VpcId": "vpc-8btfafeo",
    "Zone": "ap-beijing-4"
}

Output Example

{
    "Response": {
        "BillId": "",
        "DBInstanceIdSet": [],
        "DealNames": [],
        "RequestId": "e0726ee5-3f5f-414c-9976-17e94dd0023e"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

Tencent Cloud CLI 3.0

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code	Description
AuthFailure.UnauthorizedOperation	Authentication failed.
FailedOperation.AllocateQuotasError	Failed to request a quota for resource tags.
FailedOperation.CamAuthFailed	CAM authentication failed.
FailedOperation.CamSigAndAuthError	Authentication failed. Please try again later. If the problem persists, please contact customer service.
FailedOperation.CdbCgwConnectError	Failed to get project information. Please try again later. If the problem persists, please contact customer service.
FailedOperation.CreateBasicNetworkDeniedError	Classic network creation is unsupported.
FailedOperation.CreateOrderFailed	Failed to create the renewal order.
FailedOperation.DatabaseAccessError	Failed to access database management service. Please try again later. If the problem persists, please contact customer service.
FailedOperation.DatabaseAffectedError	Data operation failed. Please contact customer service.
FailedOperation.FailedOperationError	Operation failed. Please try again later.
FailedOperation.GetSubnetError	Failed to query VPC subnets.
FailedOperation.GetVpcInfoError	Failed to query VPC information. Please try again later. If the problem persists, please contact customer service.
FailedOperation.InvalidTradeOperate	Billing error. Corresponding purchase/renewal/configuration change operations are not allowed for the current instance.
FailedOperation.PayOrderFailed	Failed to make order payment.
FailedOperation.PreCheckError	Pre-check failed
FailedOperation.QueryPriceFailed	Failed to query the price.
FailedOperation.QuerySpecError	Failed to query specifications. Please try again later. If the problem persists, please contact customer service.
FailedOperation.QueryVpcFailed	Failed to query VPC.
FailedOperation.QueryVpcFalied	Failed to get VPC details.
FailedOperation.ROGroupNotFoundError	The RO group does not exist.
FailedOperation.ROGroupNumExceedError	The maximum number of RO groups has been reached.
FailedOperation.ServiceAccessError	Failed to access internal service. Please try again later. If the problem persists, please contact customer service.
FailedOperation.StorageMemoryCheckError	The memory and storage capacity to which an instance is upgraded should be higher than its original memory and storage capacity.
FailedOperation.TradeCreateError	Failed to request the billing platform to create an order.
FailedOperation.TradePayOrdersError	Failed to request to pay for the order.
FailedOperation.WhitelistConnectError	Failed to query the allowlist. Try again later. If the problem persists, contact customer service.
InternalError.CgwError	CGW error.
InternalError.CnsError	Basic network error.
InternalError.DBError	Backend database execution error.
InternalError.DfwError	DFW error.
InternalError.FlowError	Failed to create the flow.
InternalError.InternalHttpServerError	An exception occurred while executing the request.
InternalError.JsonParseError	Json data parsing failed. contact our customer service for assistance.
InternalError.SystemError	System error. When this error occurs, please contact customer service for assistance.
InternalError.UnknownError	Unknown error. When this error occurs, please contact customer service for assistance.
InternalError.VpcError	VPC error.
InvalidParameter	Parameter error.
InvalidParameter.ParameterCheckError	Failed to check the parameter.
InvalidParameter.TradeAccessDeniedError	Incorrect PID
InvalidParameter.VpcNotFoundError	Failed to query VPC information.
InvalidParameterValue.AccountExist	The current account already exists.
InvalidParameterValue.BadSpec	The instance specification to upgrade to is not purchasable.
InvalidParameterValue.DataConvertError	Failed to convert data format. Please contact customer service.
InvalidParameterValue.IllegalInstanceChargeType	Incorrect billing mode.
InvalidParameterValue.IllegalProjectId	Invalid `ProjectId`.
InvalidParameterValue.IllegalRegion	Invalid `Region` parameter.
InvalidParameterValue.IllegalZone	Invalid `Zone` parameter.
InvalidParameterValue.InterfaceNameNotFound	Incorrect `ACTION`.
InvalidParameterValue.InvalidAccountFormat	Incorrect account format.
InvalidParameterValue.InvalidAccountName	The current account name cannot be a reserved character.
InvalidParameterValue.InvalidCharset	Incorrect database character set. Currently, only `UTF8` and `LATIN1` are supported.
InvalidParameterValue.InvalidInstanceNum	The number of purchased instances exceeds the limit.
InvalidParameterValue.InvalidOrderNum	Billing error. Invalid order type ID.
InvalidParameterValue.InvalidParameterValueError	Incorrect parameter value
InvalidParameterValue.InvalidPasswordFormat	Incorrect password format.
InvalidParameterValue.InvalidPid	Incorrect `PID` parameter.
InvalidParameterValue.ParameterCharacterError	Invalid parameter. The parameter can contain only letters, digits, underscores, and hyphens.
InvalidParameterValue.ParameterHandleError	Failed to process the parameter. Please check if the parameter value is valid.
InvalidParameterValue.ParameterLengthLimitError	The length of parameter exceeds the limit.
InvalidParameterValue.RegionNotSupported	The current region is not supported.
InvalidParameterValue.StructParseFailed	An error occurred while parsing parameters.
InvalidPid	Incorrect `PID` parameter.
OperationDenied.CamDeniedError	This operation cannot be performed.
OperationDenied.InstanceStatusLimitError	This operation cannot be performed on an instance in this status.
OperationDenied.InstanceStatusLimitOpError	This operation cannot be performed on an instance in this status.
OperationDenied.InsufficientBalanceError	Insufficient account balance.
OperationDenied.PayModeError	Unsupported billing mode
OperationDenied.ROGroupStatusError	This operation cannot be performed on an RO group in this status.
OperationDenied.RoInstanceCountExeedError	The total number of read-only nodes should not exceed the upper limit.
OperationDenied.TradePermissionError	No payment permission. activation failed.
OperationDenied.UserNotAuthenticatedError	You need to verify your identity to make a purchase.
OperationDenied.VpcDeniedError	You do not have the permission to operate the VPC.
ResourceInsufficient.ResourceNotEnough	There are not enough resources to purchase instances of this specification in the current region.
ResourceNotFound.InstanceNotFoundError	The instance does not exist.
ResourceUnavailable.InvalidInstanceStatus	Incorrect instance status.
ResourceUnavailable.ResourceNoPermission	No permission for the VPC.
ResourceUnavailable.VpcResourceNotFound	Failed to get the information of the VPC where the instance resides.
UnauthorizedOperation.UserHasNoRealnameAuthentication	Unverified user.
UnknownError	Unknown error. When this error occurs, please contact customer service for assistance.

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

tencent cloud

TencentDB for PostgreSQL

CreateReadOnlyDBInstance

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Example1 Creating a Read-Only Instance

Input Example

Output Example

Example2 Creating a Read-Only Instance with Verification Mode

Input Example

Output Example

5. Developer Resources

SDK

Command Line Interface

6. Error Code

Help and Support