PolarDB for PostgreSQL enforces two categories of limits: limits specific to PolarDB's cloud architecture, and limits inherited from the PostgreSQL kernel. Review these limits before designing your application or planning schema changes to avoid hitting them in production.
PolarDB-specific limits
These limits are unique to PolarDB for PostgreSQL and exist to ensure stability and resource isolation in a multitenant cloud environment.
File count limit per cluster
Each cluster has a maximum number of files, determined by the node specifications. If a cluster reaches this limit, new tables and indexes cannot be created, and the database returns a could not create file error.
What counts as a file: A non-partitioned table uses three files: a data file, a Free Space Map (FSM) file, and a Visibility Map (VM) file. Each index on the table adds one more file. System catalog files and log files also count toward the total.
File count limits by node specification:
| Node specification | Maximum files | Adjustable |
|---|---|---|
| polar.pg.x4.medium | 1,048,576 | Yes — |
| polar.pg.x4.large | 2,097,152 | Yes — upgrade specifications |
| polar.pg.x4.xlarge | 2,097,152 | Yes — upgrade specifications |
| polar.pg.x8.xlarge | 4,194,304 | Yes — upgrade specifications |
| polar.pg.x8.2xlarge | 8,388,608 | Yes — upgrade specifications |
| polar.pg.x8.4xlarge | 12,582,912 | Yes — upgrade specifications |
| polar.pg.x8.12xlarge | 20,971,520 | Yes — upgrade specifications |
If your cluster is approaching the file limit:
Monitor your total table and index count as part of routine database maintenance.
Drop unused tables and indexes to free up file slots.
Upgrade the cluster specifications to increase the limit.
Permission limits
| Item | Limit | Details |
|---|---|---|
| Database permissions | superuser is not available | PolarDB provides the polar_superuser role instead. This role is a subset of the superuser permission and is sufficient for most daily administrative tasks. For details, see Create a database account. |
Inherited PostgreSQL limits
PolarDB for PostgreSQL is built on the PostgreSQL kernel and inherits its object-level limits. The table below lists the limits most relevant to schema design and application development.
For the full upstream reference, see the PostgreSQL documentation:
| Limit | Value | Notes |
|---|---|---|
| Database size | 500 TB / unlimited | Centralized clusters: 500 TB maximum (actual capacity depends on node specifications). Distributed clusters: theoretically unlimited. |
| Table size | 32 TB | Based on the default 8 KB block size (BLCKSZ). |
| Columns per table | 1,600 (theoretical) | The effective limit is lower. A single row, excluding TOAST values, cannot exceed one data page (~8 KB). Wide types like bigint reduce the usable column count. Keep columns below 250 for reliable performance. |
| Field size | 1 GB | Applies to variable-length types: text, jsonb, bytea. Oversized values are stored out-of-line via TOAST (The Oversized-Attribute Storage Technique). |
| Identifier length | 63 bytes | Names for tables, columns, and other database objects. Names longer than 63 bytes are silently truncated, which can cause unexpected behavior if two long names share the same 63-byte prefix. |
| Indexes per table | Unlimited | The actual number of indexes is constrained by storage space, the cluster's file count limit, and system resources. |
| Columns per index | 32 | The maximum number of columns in a single index. |
| Partition key columns | 32 | The maximum number of columns in a partition key for a partitioned table. |
| Function parameters | 100 | The maximum number of parameters for a user-defined function. |
| Query parameters | 65,535 | The maximum number of parameter markers (such as $1 and $2) in a single query. |