文档/ 数据库/ 连接字符串

连接字符串

通过自动注入的环境变量将应用连接到数据库。sh0 处理内部网络，让你的应用通过主机名即可访问数据库。

查找连接字符串

在 sh0 中创建的每个数据库都可以在控制台中查看连接详情。导航到数据库详情页并点击连接选项卡以查看所有连接信息。

Database connection tab -- showing the full connection string, host, port, username, password, and database name

连接选项卡显示：

完整连接 URL -- 可直接复制粘贴到应用配置中。
各字段 -- 主机、端口、用户名、密码和数据库名称作为独立值。
连接命令 -- 可直接连接的 CLI 命令（例如 psql、mysql）。

例如，PostgreSQL 数据库连接字符串如下所示：

PostgreSQL Connection URL

postgresql://myuser:secretpass@mydb:5432/myapp

自动注入的环境变量

当你在堆栈中创建数据库时，sh0 会自动将连接环境变量注入同一堆栈中的所有应用服务。你的应用可以在运行时读取这些变量，无需任何手动配置。

Environment variables panel -- showing auto-injected database variables with a badge indicating they are managed by sh0

变量命名约定

自动注入的变量遵循基于数据库名称和引擎的一致命名模式：

PostgreSQL (database named 'mydb')

DATABASE_URL=postgresql://sh0:generated_pass@mydb:5432/sh0
MYDB_HOST=mydb
MYDB_PORT=5432
MYDB_USER=sh0
MYDB_PASSWORD=generated_pass
MYDB_DATABASE=sh0

MySQL (database named 'maindb')

DATABASE_URL=mysql://sh0:generated_pass@maindb:3306/sh0
MAINDB_HOST=maindb
MAINDB_PORT=3306
MAINDB_USER=sh0
MAINDB_PASSWORD=generated_pass
MAINDB_DATABASE=sh0

Redis (database named 'cache')

REDIS_URL=redis://:generated_pass@cache:6379
CACHE_HOST=cache
CACHE_PORT=6379
CACHE_PASSWORD=generated_pass

MongoDB (database named 'docs')

MONGO_URL=mongodb://sh0:generated_pass@docs:27017/sh0
DOCS_HOST=docs
DOCS_PORT=27017
DOCS_USER=sh0
DOCS_PASSWORD=generated_pass
DOCS_DATABASE=sh0

Tip

如果你的堆栈只有一个数据库，sh0 还会设置 DATABASE_URL（或 REDIS_URL / MONGO_URL）作为便捷变量。如果你有多个相同引擎的数据库，请使用名称前缀变量以避免冲突。

从同一堆栈连接

同一堆栈内的服务共享一个 Docker 网络。这意味着你的应用可以使用数据库容器的名称作为主机名来连接数据库。无需 IP 地址、无需端口映射——只需容器名称。

Node.js example

// The DATABASE_URL is auto-injected by sh0
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

Python / Django example

# settings.py
import dj_database_url

DATABASES = {
    'default': dj_database_url.config(
        default=os.environ['DATABASE_URL']
    )
}

Stack network diagram -- showing an app container and database container connected on the same internal Docker network

Note

同一堆栈中容器之间的内部连接不会离开 Docker 网络。流量不通过 TLS 加密，因为它从不经过公共互联网。这是标准的 Docker 网络行为。

外部访问

默认情况下，数据库只能从堆栈网络内部访问。要从本地计算机连接（例如使用 pgAdmin、TablePlus 或 DBeaver 等 GUI 工具），你需要启用外部访问。

打开数据库设置。
将 公共访问 切换为启用。
sh0 将容器端口映射到主机上的随机高端口（例如 54321）。
使用 your-server-ip:54321 和数据库凭据进行连接。

External access toggle and the resulting public connection string with the mapped port

Warning

启用外部访问会将数据库暴露到互联网。请始终使用强密码，并考虑通过防火墙规则限制 IP 访问。

连接池

大多数数据库对并发连接数有限制。连接池帮助你在服务大量请求的同时保持在这些限制范围内。

sh0 中连接池的最佳实践：

使用框架内置连接池 -- 大多数 ORM 和数据库驱动支持连接池。根据数据库限制配置连接池大小。
将连接池大小与可用连接数匹配 -- PostgreSQL 默认最大连接数为 100。如果你有 3 个应用副本，每个连接池设置为约 30 个连接。
设置连接超时 -- 配置空闲连接超时，防止过期连接占用连接槽。
监控连接数 -- 使用数据库指标控制台跟踪随时间变化的活跃连接数。

Node.js pool configuration

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,              // Maximum connections in the pool
  idleTimeoutMillis: 30000,  // Close idle connections after 30s
  connectionTimeoutMillis: 5000, // Fail if connection takes > 5s
});

常见框架示例

以下是常用框架的连接示例。它们都使用 sh0 自动注入的 DATABASE_URL 环境变量。

Ruby on Rails (config/database.yml)

production:
  url: <%= ENV['DATABASE_URL'] %>

Laravel (.env)

DB_CONNECTION=pgsql
DB_HOST=${{ MYDB_HOST }}
DB_PORT=${{ MYDB_PORT }}
DB_DATABASE=${{ MYDB_DATABASE }}
DB_USERNAME=${{ MYDB_USER }}
DB_PASSWORD=${{ MYDB_PASSWORD }}

Rust / SQLx

let pool = PgPoolOptions::new()
    .max_connections(20)
    .connect(&std::env::var("DATABASE_URL")?)
    .await?;

Go / pgx

pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))

Tip

大多数现代框架会自动检测 DATABASE_URL。如果你的框架支持此功能，则无需配置任何内容——只需部署到 sh0 即可开箱即用。

Backups & Restore

BaaS Overview