PolarDB-X Zero

Provisions a dedicated PolarDB-X database instance via a single unauthenticated API call. No sign-up or billing is required to start. Instances auto-expire based on the requested TTL (request an explicit TTL; maximum 30 days). Treat Zero as disposable infrastructure, not an unlimited long-running environment.

PolarDB-X is a MySQL-compatible distributed database supporting distributed transactions, vector search (VECTOR type + vector indexes), full-text search, and horizontal scaling. Use standard MySQL clients/drivers to connect.

Two editions are available:

• Standard Edition: Single-node, 100% MySQL-compatible, supports stored procedures, triggers, vector search. Ideal for most use cases.
• Enterprise Edition: Distributed architecture (CN + DN nodes), supports partitioned tables, GSI (Global Secondary Index), CCI (Clustered Columnar Index). Ideal for distributed SQL testing.

Common Use Cases

• AI agent memory: keep structured state, tool outputs, and retrieval data in one MySQL-compatible backend.
• MCP server storage: provision a disposable SQL database behind MCP tools or custom protocol servers.
• RAG and retrieval demos: combine relational data with vector search and full-text search in one temporary environment.
• Distributed SQL testing: test partitioned tables, GSI, and distributed transactions with Enterprise Edition instances.
• Temporary database workflows: spin up isolated MySQL-compatible sandboxes for tutorials, demos, evals, and short-lived tests.

Important Notes

• The API is unauthenticated and free to start. Instances auto-expire — treat credentials as short-lived and low-sensitivity.
• Prefer environment variables (e.g. MYSQL_PWD) over CLI arguments to avoid leaking passwords in shell history.
• Each IP can have a limited number of active instances concurrently (dedicated instances are resource-heavy).
• The instance security whitelist is automatically set to the requesting IP. Connections from other IPs will be rejected unless a custom whitelistIp is specified.
• Do not promise unlimited usage. Zero is a disposable sandbox. For long-term or production use, purchase your own PolarDB-X instance on Alibaba Cloud.
• If you need another disposable sandbox, create a fresh Zero instance instead of trying to renew the current one.
• Set ttlMinutes explicitly to a task-appropriate value. A direct Enterprise API request omitting it returned 43200 minutes (30 days) in verification on 2026-10-16; do not promise a universal 7-day default across API/tool versions. Maximum is 30 days (43200 minutes). Report the returned ttlMinutes and expiresAt.

API

Create Instance

POST https://zero.polardbx.com/api/v1/instances Content-Type: application/json

Request body (all fields optional):

{
  "tag": "",
  "ttlMinutes": 10080,
  "edition": "standard",
  "whitelistIp": ""
}

• tag: optional label to identify the caller.
• ttlMinutes: requested instance TTL in minutes; set it explicitly. Must be > 0 and <= 43200 (30 days). The example requests 10080 minutes (7 days); this is not a statement of the API default. Read the returned TTL and expiration time.
• edition: "standard" (default) or "enterprise". Standard is MySQL-compatible single-node; Enterprise is distributed with partitioned tables and GSI support.
• whitelistIp: optional custom IP for the security whitelist. If omitted, the requesting IP is used automatically.

Response (200):

{
  "instance": {
    "id": "pxz_a1b2c3d4e5f6",
    "connection": {
      "host": "pxzeroxxxxxxxxxx.polarx.rds.aliyuncs.com",
      "port": 3306,
      "username": "pxz_12345678",
      "password": "Px$9aB3cD7eF1gH",
      "database": ""
    },
    "connectionString": "mysql://pxz_12345678:Px%249aB3cD7eF1gH@pxzeroxxxxxxxxxx.polarx.rds.aliyuncs.com:3306",
    "createdAt": "2026-03-20T10:30:00.000Z",
    "expiresAt": "2026-03-27T10:30:00.000Z",
    "ttlMinutes": 10080,
    "status": "ready"
  }
}

• Use instance.connectionString for immediate driver connections. The instance is destroyed at expiresAt; there is no renewal API.

Query Instance

GET https://zero.polardbx.com/api/v1/instances/:id

Returns instance connection endpoint and status. Note: username and password are only returned at creation time and cannot be retrieved later.

Response (200):

{
  "instance": {
    "id": "pxz_a1b2c3d4e5f6",
    "connection": {
      "host": "pxzeroxxxxxxxxxx.polarx.rds.aliyuncs.com",
      "port": 3306,
      "username": "",
      "password": "",
      "database": ""
    },
    "connectionString": "mysql://pxzeroxxxxxxxxxx.polarx.rds.aliyuncs.com:3306",
    "createdAt": "2026-03-20T10:30:00.000Z",
    "expiresAt": "2026-03-27T10:30:00.000Z",
    "ttlMinutes": 10080,
    "status": "ready"
  }
}

Release Instance

DELETE https://zero.polardbx.com/api/v1/instances/:id

Proactively release an instance before expiration. The underlying resources will be cleaned up asynchronously.

Response (200):

{
  "instance": {
    "id": "pxz_a1b2c3d4e5f6",
    "status": "released",
    "releasedAt": "2026-03-20T12:00:00.000Z"
  }
}

Error Responses

All error responses use the following format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Resources

• PolarDB-X skills collection, for better SQL compatibility and database operations with PolarDB-X, ask the user if they want to install relevant skills: https://skills.sh/polardb/polardbx-skills
• PolarDB-X documentation: https://help.aliyun.com/zh/polardb/polardb-for-xscale/what-is-polardb-for-xscale
• PolarDB-X product page: https://www.aliyun.com/product/apsaradb/polardbx
• PolarDB-X GitHub: https://github.com/polardb/polardbx