Add a DuckDB analytical instance

Features

A DuckDB-based analytical instance is a specialized read-only instance designed for analytical queries. It provides the following features:

• Read/write splitting and workload isolation: As a dedicated node, the instance completely isolates resource-intensive analytical queries from the transactional operations on the primary instance, ensuring that your core business operations remain stable and performant.

• Zero-ETL real-time columnar conversion: The instance synchronizes data from the primary instance in real time using physical replication and logical subscription, and automatically converts the data to the columnar storage format. You can also configure synchronization policies for each database.

• Hybrid row and columnar storage: The instance stores two copies of the data: a row store (original format) copy and a columnar storage (analytical format) copy. By default, the instance uses the columnar engine to accelerate complex analytical queries. For queries that cannot be processed by the columnar engine, the system automatically falls back to the row store engine to ensure compatibility. The instance also supports row store compression.

Prerequisites

To create a DuckDB-based analytical instance, the primary ApsaraDB RDS for PostgreSQL instance must meet the following requirements:

• Instance status: Running.

• Major engine version: ApsaraDB RDS for PostgreSQL 13.0 or later.

• Edition: High-availability Edition.

• Billing method: Subscription or pay-as-you-go.

• Minor engine version: 20260130 or later.

• Instance parameters: The following parameters are configured as required.

  wal_level is set to logical, shared_preload_libraries includes rds_duckdb, and max_replication_slots, max_worker_processes, and max_wal_senders are all set to 1024 or greater.

• The instance is not a disaster recovery instance.

Free trial

After you create a primary ApsaraDB RDS for PostgreSQL instance, you can add a DuckDB analysis read-only instance for free. The specifications for the DuckDB analysis read-only instance free trial are as follows:

• Billing Method:Subscription (select a Duration of one month).

• Major engine version: ApsaraDB RDS for PostgreSQL 16 or later.

• Edition: Basic Edition.

• Instance Type: pgro.x2.large.1c (4 vCPUs, 8 GB, Dedicated).

• Capacity: less than 3 TB.

Billing

The cost depends on factors such as the edition, instance type, storage type, and storage capacity. The final price is shown on the purchase page.

Usage notes

• After you create a DuckDB-based analytical instance, do not modify the required parameters on the primary instance.

• If you create multiple DuckDB-based analytical instances for a single primary instance, they all share the same columnar storage configuration, such as which databases are enabled for automatic conversion.

• If the primary instance has columnar acceleration enabled through the rds_duckdb extension, we recommend that you disable this feature on the primary instance after you create the DuckDB-based analytical instance. This ensures complete workload isolation.

• To ensure query compatibility, the DuckDB-based analytical instance retains a copy of the data in row store format. You can compress the row store data to control storage costs.

Create a DuckDB analytical instance

1. Go to the ApsaraDB RDS console, select a region in the top navigation bar, and then click the ID of the target instance.

2. On the Basic Information page, in the Instance Distribution section, click Add to the right of DuckDB-based analytical instance.

   

3. A pre-check runs automatically. Once it passes, click Confirm opening.

   If the pre-check fails, click One-key repair and select a time for the fix in the panel that appears. The system automatically configures the dependencies that failed the pre-check. After the fix is complete, click Add to the right of DuckDB-based analytical instance again. On the pre-check page, click Confirm opening.

   Important

   If the major engine version of the instance does not meet the requirements, you must manually upgrade the major engine version.

4. Configure the parameters for the DuckDB-based analytical instance.

   Parameter	Description
   Billing Method	Subscription : Ideal for long-term use (one-time payment). Pay-As-You-Go: Ideal for short-term use (hourly billing). You can start with a pay-as-you-go instance and switch to a Subscription plan once it meets your needs.
   Edition	Basic Edition: A single-node DuckDB-based analytical instance. This edition is cost-effective and suitable for learning or testing purposes. Recovery and restart times for the instance can be long. High-availability Edition (default): Includes a primary node and a secondary node to provide high availability for the DuckDB-based analytical instance. It is suitable for production environments and meets the requirements of more than 80% of use cases. Note If you select Edition, you must also specify the zone for the primary node, the deployment solution (multi-zone deployment or single-zone deployment), and the zone for the secondary node.
   Product Type	Only Standard Edition is supported. For more information, see Product types.
   Zone	A zone is an independent physical region. All zones within the same region provide the same level of service. Compared with a single-zone deployment, a multi-zone deployment provides zone-level disaster recovery.
   Instance Type	Only Dedicated instance types are supported. The instance types are the same as the ApsaraDB RDS for PostgreSQL read-only instance types.
   Storage Capacity	Storage space includes data space, system file space, write-ahead logging (WAL) file space, and transaction file space. You can adjust the storage space in increments of 5 GB. Note The storage space of a DuckDB-based analytical instance cannot be smaller than that of its primary instance. For information about the storage space of each instance type, see ApsaraDB RDS for PostgreSQL read-only instance type list.

5. Click Next: Instance Configurations and configure the following parameters.

   Parameter	Description
   Network Type	Defaults to the same network type, VPC, and vSwitch of Primary Node as the primary instance.
   Release Protection	If you set the Billing Method to pay-as-you-go, you can enable Release Protection for the instance to prevent it from being accidentally released. For more information, see Enable or disable release protection for an instance.
   Resource Group	Defaults to the same resource group as the primary instance and cannot be modified.
   Time Zone	Defaults to the same time zone as the primary instance.
   SLR Authorization	No action is required. The authorization was granted when you purchased the primary instance.
   Instance Name	Set a name for the instance for easy management.
   Tags	You can add tags to an instance when you create it. After the instance is created, you can filter instances by tag. For more information, see Filter instances by tag.

6. Click Next: Confirm Order.

7. Confirm the Parameter Configuration, select the Quantity and Duration (for Subscription instances only), and then click Pay Now to complete the payment.

Configure columnar databases

A DuckDB-based analytical instance uses columnar storage to accelerate analytical queries. Before you use the instance, you must convert row store data from the primary instance to the columnar storage format.

You can convert an entire database or convert tables on demand. We recommend that you first try converting the entire database. Select a method based on your business requirements and resource availability.

-- Create the rds_duckdb extension (skip if it already exists).
CREATE EXTENSION IF NOT EXISTS rds_duckdb;

-- Convert the specified table to the columnar storage format.
SELECT rds_duckdb.create_duckdb_table('local_table_name');

Related documents

• ApsaraDB RDS for PostgreSQL read-only instances

• How do I use DuckDB to accelerate queries?

• DuckDB performance tests

• Free trial of the rds_duckdb AP acceleration engine for ApsaraDB RDS for PostgreSQL