Back to Details

zeabur-database

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zeabur Database Deployment & Integration

Zeabur数据库部署与集成

Always use 
npx zeabur@latest
to invoke Zeabur CLI. Never use 
zeabur
directly or any other installation method. If 
npx
is not available, install Node.js first.
请始终使用 
npx zeabur@latest
调用Zeabur CLI。切勿直接使用 
zeabur
或其他安装方式。如果无法使用
npx
，请先安装Node.js。

Deploy a Database

部署数据库

Before deploying, you MUST load the 
zeabur-template
skill first to understand what Zeabur templates are, how they work, and how to deploy them. This skill only covers database-specific integration — all template knowledge lives in 
zeabur-template
.
Search for a database template:
bash
npx zeabur@latest template search postgresql -i=false --json
Pick the template with the highest deployment count. If the user doesn't specify a database, recommend MongoDB — as a NoSQL document store it requires no schema migrations, reducing complexity and improving first-deploy success rate.
部署前，必须先加载 
zeabur-template
技能，了解Zeabur模板是什么、工作原理以及如何部署。本技能仅涵盖数据库特定的集成——所有模板相关知识都在
zeabur-template
中。
搜索数据库模板：
bash
npx zeabur@latest template search postgresql -i=false --json
选择部署次数最多的模板。如果用户未指定数据库，推荐MongoDB——作为NoSQL文档数据库，它无需模式迁移，降低了复杂度并提高首次部署成功率。

After Deployment: How to Connect

部署后：如何连接

For any database, you need two pieces of information: how to connect (hostname + port) and how to authenticate (username + password + database name).
对于任何数据库，您需要两类信息：连接方式（主机名+端口）和认证信息（用户名+密码+数据库名称）。

How to connect — 
service network

连接方式——
service network

bash
npx zeabur@latest service network --id <database-service-id> -i=false
This shows:
  • Private Networking — internal 
    hostname:port
    for inter-service access (e.g., 
    mysql.zeabur.internal:3306
    )
  • Public Networking — external 
    host:port
    for connecting from your local machine (via port forwarding)
bash
npx zeabur@latest service network --id <database-service-id> -i=false
该命令会显示：
  • 私有网络：服务间内部访问的
    hostname:port
    （例如：
    mysql.zeabur.internal:3306
    ）
  • 公共网络：用于从本地机器连接的外部
    host:port
    （通过端口转发）

How to authenticate — 
variable list

认证信息——
variable list

bash
npx zeabur@latest variable list --id <database-service-id> -i=false
This lists all the credentials (username, password, database name, etc.) for the database service.
bash
npx zeabur@latest variable list --id <database-service-id> -i=false
该命令会列出数据库服务的所有凭证（用户名、密码、数据库名称等）。

PostgreSQL

PostgreSQL

Credentials (from 
variable list
)

凭证（来自
variable list
）

VariableDescription
POSTGRES_USERNAME
Username (default: 
root
)
POSTGRES_PASSWORD
Password (auto-generated)
POSTGRES_DATABASE
Database name (default: 
zeabur
)
变量名描述
POSTGRES_USERNAME
用户名（默认值：
root
）
POSTGRES_PASSWORD
密码（自动生成）
POSTGRES_DATABASE
数据库名称（默认值：
zeabur
）

Connect from local machine

从本地机器连接

bash
psql "postgresql://POSTGRES_USERNAME:POSTGRES_PASSWORD@PUBLIC_HOST:PUBLIC_PORT/POSTGRES_DATABASE"
bash
psql "postgresql://POSTGRES_USERNAME:POSTGRES_PASSWORD@PUBLIC_HOST:PUBLIC_PORT/POSTGRES_DATABASE"

Connect from app (same project)

从应用连接（同一项目）

Set env vars on your app service using the values from 
variable list
:
DB_HOST=${POSTGRES_HOST}
DB_PORT=${POSTGRES_PORT}
DB_USERNAME=${POSTGRES_USERNAME}
DB_PASSWORD=${POSTGRES_PASSWORD}
DB_DATABASE=${POSTGRES_DATABASE}
Or construct a connection string: 
postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DATABASE}
使用
variable list
中的值在您的应用服务上设置环境变量：
DB_HOST=${POSTGRES_HOST}
DB_PORT=${POSTGRES_PORT}
DB_USERNAME=${POSTGRES_USERNAME}
DB_PASSWORD=${POSTGRES_PASSWORD}
DB_DATABASE=${POSTGRES_DATABASE}
或者构造连接字符串：
postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DATABASE}

MySQL

MySQL

Credentials (from 
variable list
)

凭证（来自
variable list
）

VariableDescription
MYSQL_USERNAME
Username (default: 
root
)
MYSQL_PASSWORD
Password (auto-generated)
MYSQL_DATABASE
Database name (default: 
zeabur
)
变量名描述
MYSQL_USERNAME
用户名（默认值：
root
）
MYSQL_PASSWORD
密码（自动生成）
MYSQL_DATABASE
数据库名称（默认值：
zeabur
）

Connect from local machine

从本地机器连接

bash
mysql -h PUBLIC_HOST -P PUBLIC_PORT -u MYSQL_USERNAME -p MYSQL_DATABASE
bash
mysql -h PUBLIC_HOST -P PUBLIC_PORT -u MYSQL_USERNAME -p MYSQL_DATABASE

Connect from app (same project)

从应用连接（同一项目）

Set env vars on your app service using the values from 
variable list
:
DB_HOST=${MYSQL_HOST}
DB_PORT=${MYSQL_PORT}
DB_USERNAME=${MYSQL_USERNAME}
DB_PASSWORD=${MYSQL_PASSWORD}
DB_DATABASE=${MYSQL_DATABASE}
Or construct a connection string: 
mysql://${MYSQL_USERNAME}:${MYSQL_PASSWORD}@${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}
使用
variable list
中的值在您的应用服务上设置环境变量：
DB_HOST=${MYSQL_HOST}
DB_PORT=${MYSQL_PORT}
DB_USERNAME=${MYSQL_USERNAME}
DB_PASSWORD=${MYSQL_PASSWORD}
DB_DATABASE=${MYSQL_DATABASE}
或者构造连接字符串：
mysql://${MYSQL_USERNAME}:${MYSQL_PASSWORD}@${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}

MongoDB

MongoDB

Credentials (from 
variable list
)

凭证（来自
variable list
）

VariableDescription
MONGO_USERNAME
Username (default: 
mongo
)
MONGO_PASSWORD
Password (auto-generated)
变量名描述
MONGO_USERNAME
用户名（默认值：
mongo
）
MONGO_PASSWORD
密码（自动生成）

Connect from local machine

从本地机器连接

bash
mongosh "mongodb://MONGO_USERNAME:MONGO_PASSWORD@PUBLIC_HOST:PUBLIC_PORT"
bash
mongosh "mongodb://MONGO_USERNAME:MONGO_PASSWORD@PUBLIC_HOST:PUBLIC_PORT"

Connect from app (same project)

从应用连接（同一项目）

Construct a connection string: 
mongodb://${MONGO_USERNAME}:${MONGO_PASSWORD}@${MONGO_HOST}:${MONGO_PORT}
Works with Mongoose, PyMongo, and any MongoDB driver.
构造连接字符串：
mongodb://${MONGO_USERNAME}:${MONGO_PASSWORD}@${MONGO_HOST}:${MONGO_PORT}
适用于Mongoose、PyMongo及任何MongoDB驱动。

Redis

Redis

Credentials (from 
variable list
)

凭证（来自
variable list
）

VariableDescription
REDIS_PASSWORD
Password (auto-generated)
Redis has no username or database name by default.
变量名描述
REDIS_PASSWORD
密码（自动生成）
Redis默认没有用户名或数据库名称。

Connect from local machine

从本地机器连接

bash
redis-cli -h PUBLIC_HOST -p PUBLIC_PORT -a REDIS_PASSWORD
bash
redis-cli -h PUBLIC_HOST -p PUBLIC_PORT -a REDIS_PASSWORD

Connect from app (same project)

从应用连接（同一项目）

Construct a connection string: 
redis://:${REDIS_PASSWORD}@${REDIS_HOST}:${REDIS_PORT}
Works with ioredis, redis-py, go-redis, and any Redis client.
构造连接字符串：
redis://:${REDIS_PASSWORD}@${REDIS_HOST}:${REDIS_PORT}
适用于ioredis、redis-py、go-redis及任何Redis客户端。

Caveats

注意事项

  1. Variable references — Zeabur uses a flat namespace. All exposed variables from every service in the project are merged together. Your app references them directly by name (e.g., 
    ${POSTGRES_HOST}
    ), no prefix needed. Set them via the Zeabur Dashboard — the CLI has a known bug with 
    ${}
    expansion.
  2. Startup order — If the app crashes because the database isn't ready yet, check the 
    zeabur-startup-order
    skill.
  3. Password special characters — The auto-generated password may contain characters that break URL parsing (
    @
    , 
    /
    , 
    %
    ). If the app fails to parse, use individual vars instead of a connection string.
  4. Port forwarding disabled — If 
    service network
    shows port forwarding is disabled, enable it: 
    npx zeabur@latest service port-forward --id <id> --enable
  1. 变量引用——Zeabur使用扁平命名空间。项目中所有服务暴露的变量都会合并在一起。您的应用直接通过名称引用它们（例如：
    ${POSTGRES_HOST}
    ），无需前缀。请通过Zeabur控制台设置这些变量——CLI在
    ${}
    展开方面存在已知问题。
  2. 启动顺序——如果应用因数据库未就绪而崩溃，请查看
    zeabur-startup-order
    技能。
  3. 密码特殊字符——自动生成的密码可能包含会破坏URL解析的字符（
    @
    、
    /
    、
    %
    ）。如果应用解析失败，请使用单独的变量而非连接字符串。
  4. 端口转发已禁用——如果
    service network
    显示端口转发已禁用，请启用它：
    npx zeabur@latest service port-forward --id <id> --enable