PostgreSQL

PostgreSQL 是一个流行的开源关系型数据库管理系统。它广泛用于 Web 应用程序和后端系统。

ShipAny 支持 PostgreSQL 数据库。按照以下步骤快速开始。

快速开始

创建 PostgreSQL 数据库

根据你的操作系统类型，自行搜索安装 PostgreSQL，通过命令行创建数据库：

或者你也可以使用各类云服务器厂商提供的 PostgreSQL 云数据库服务。

设置数据库连接参数

对上一步创建的数据库，你需要设置用户名、密码，分配权限，开启远程访问权限等。

得到的数据库连接地址 DATABASE_URL 如下：

postgresql://user:password@host:port/database

通过以下命令测试数据库连接是否正常：

psql "postgresql://user:password@host:port/database"

配置数据库

在项目的环境变量文件中，填入 PostgreSQL 数据库相关的配置。

本地开发环境变量文件 .env.development
生产环境变量文件 .env.production

DATABASE_PROVIDER = "postgresql"
DATABASE_URL = "postgresql-database-url"
DB_SCHEMA_FILE = "./src/config/db/schema.postgres.ts"
DB_MIGRATIONS_OUT = "./src/config/db/migrations"

DATABASE_PROVIDER，必填，固定值 postgresql
DATABASE_URL，必填，填 PostgreSQL 数据库的 Database URL
DB_SCHEMA_FILE，必填，固定值 ./src/config/db/schema.postgres.ts
DB_MIGRATIONS_OUT，选填，数据库迁移文件输出路径，默认值 ./src/config/db/migrations，可以根据数据库类型选择不同的输出路径

修改数据库 Schema 文件

使用 PostgreSQL 数据库时，数据表结构定义在 ./src/config/db/schema.postgres.ts 文件中，你需要导出这个文件的数据表。

打开 ./src/config/db/schema.ts 文件，修改内容为：

export * from './schema.postgres';

迁移数据表

执行以下命令，迁移数据表

pnpm db:generate
pnpm db:migrate

管理数据库

你可以在 PostgreSQL 数据库管理后台管理数据库，也可以在本地执行命令:

pnpm db:studio

打开数据库管理面板。

自定义

修改数据表

如果你需要新增数据表，或者修改数据表字段，可以打开 ./src/config/db/schema.postgres.ts 文件，修改数据表结构。

修改完成后，执行以下命令，迁移数据表

pnpm db:generate
pnpm db:migrate

修改数据库连接

如果你需要修改数据表连接参数，比如配置自定义选项、连接池等，可以修改 ./src/core/db/postgres.ts 文件中的逻辑。

在进行数据操作时，默认使用的是 ./src/core/db/index.ts 导出的 db() 对象，导出类型是 any，在某些情况下，可能会缺乏类型提示。

import { db } from '@/core/db';
import { user } from '@/config/db/schema';

const [result] = await db().select().from(user).limit(1);

如果你希望使用强类型的数据库对象，可以在操作数据时，使用以下方式获取数据库对象：

import { dbPostgres } from '@/core/db';
import { user } from '@/config/db/schema';

const [result] = await dbPostgres().select().from(user).limit(1);

或者：

import { getPostgresDb } from '@/core/db/postgres';
import { user } from '@/config/db/schema';

const [result] = await getPostgresDb().select().from(user).limit(1);

部署到 Cloudflare Workers

使用 Cloudflare Workers 部署项目时，暂不支持使用 PostgreSQL 数据库。

你可以使用 Supabase、Neon 等兼容 PostgreSQL 的数据库服务。

通过 Schema 隔离数据

PostgreSQL 使用 public 作为默认 Schema。在同一个 PostgreSQL 数据库中，可以创建多个 Schema，来存储多个不同项目的数据。

创建自定义 Schema

通过命令登录到 PostgreSQL 数据库。

psql "postgresql://user:password@host:port/database"

比如这里创建一个名为 project_2 的 Schema，创建自定义 Schema 的命令如下：

CREATE SCHEMA project_2;

配置数据库

在新项目的环境变量文件中，填入 PostgreSQL 数据库相关的配置。

本地开发环境变量文件 .env.development
生产环境变量文件 .env.production

# postgresql
DATABASE_PROVIDER = "postgresql"
DATABASE_URL = "postgresql://user:password@host:port/database"

DB_SCHEMA_FILE = "./src/config/db/schema.postgres.ts"
DB_MIGRATIONS_OUT = "./src/config/db/migrations_project_2"
DB_SCHEMA = "project_2"
DB_MIGRATIONS_SCHEMA = "project_2"
DB_MIGRATIONS_TABLE = "__drizzle_migrations"

DATABASE_PROVIDER，必填，固定值 postgresql
DATABASE_URL，必填，填 PostgreSQL 数据库的 DATABASE_URL
DB_SCHEMA_FILE，必填，固定值 ./src/config/db/schema.postgres.ts
DB_MIGRATIONS_OUT，选填，数据库迁移文件输出路径，默认值 ./src/config/db/migrations，可以根据数据库类型和项目名称选择不同的输出路径
DB_SCHEMA，选填，数据库 Schema 名称，默认值 public，填入新项目的 Schema 名称，达到隔离数据的目的
DB_MIGRATIONS_SCHEMA，选填，数据库迁移 Schema 名称，默认值 drizzle，这里填入新项目的 Schema 名称，达到隔离数据的目的
DB_MIGRATIONS_TABLE，选填，数据库迁移表名称，默认值 __drizzle_migrations，可以保持不变。

迁移数据表

执行以下命令，迁移数据表

pnpm db:generate
pnpm db:migrate

管理数据库

可以通过命令登录到 PostgreSQL 数据库。

psql "postgresql://user:password@host:port/database"

切换到新项目的 Schema，管理数据。

SET search_path TO project_2;

也可以在本地执行命令:

pnpm db:studio

打开数据库管理面板，切换到新项目的 Schema，管理数据表。