4.4.4 数据库连接：连接字符串与环境配置

一句话破题

正确配置数据库连接是使用 Prisma 的第一步——连接字符串决定了你的应用如何与数据库通信。

连接字符串格式

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA

组件	说明	示例
USER	数据库用户名	postgres
PASSWORD	用户密码	mypassword
HOST	数据库服务器地址	localhost
PORT	端口号	5432
DATABASE	数据库名	myapp
schema	PostgreSQL schema	public

不同环境的配置

本地开发（SQLite）：

# .env
DATABASE_URL="file:./dev.db"

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

本地开发（PostgreSQL + Docker）：

# docker-compose.yml
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"

# .env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp?schema=public"

Supabase：

# .env
DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"

Neon（Serverless PostgreSQL）：

# .env
DATABASE_URL="postgresql://[user]:[password]@[endpoint].neon.tech/[database]?sslmode=require"

环境变量管理

多环境配置：

.env                 # 默认配置（开发）
.env.local           # 本地覆盖（不提交到 Git）
.env.development     # 开发环境
.env.test            # 测试环境
.env.production      # 生产环境

.gitignore 配置：

# 不要提交包含密码的文件
.env
.env.local
.env.*.local

# 可以提交的示例文件
!.env.example

.env.example 示例：

# 复制此文件为 .env 并填入真实值
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

Prisma Client 初始化

基础用法：

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

export default prisma

开发环境单例模式（避免热重载创建多个连接）：

// lib/prisma.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const prisma = globalForPrisma.prisma ?? new PrismaClient()

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma
}

带日志配置：

const prisma = new PrismaClient({
  log: [
    { level: 'query', emit: 'event' },   // 查询日志
    { level: 'error', emit: 'stdout' },  // 错误日志
    { level: 'warn', emit: 'stdout' },   // 警告日志
  ],
})

// 监听查询事件
prisma.$on('query', (e) => {
  console.log('Query: ' + e.query)
  console.log('Duration: ' + e.duration + 'ms')
})

连接池配置

URL 参数方式：

DATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=5&pool_timeout=10"

参数	说明	默认值
connection_limit	最大连接数	num_cpus * 2 + 1
pool_timeout	获取连接超时（秒）	10
connect_timeout	建立连接超时（秒）	5

Serverless 环境配置：

# Vercel / Netlify 等 Serverless 环境
DATABASE_URL="postgresql://...?connection_limit=1"

Serverless 环境建议使用连接池服务（如 Supabase Pooler、PgBouncer）。

多数据源配置

// 主数据库
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// 如需连接多个数据库，使用多个 Prisma Client
// prisma/schema-analytics.prisma
datasource analytics {
  provider = "postgresql"
  url      = env("ANALYTICS_DATABASE_URL")
}

连接测试

async function testConnection() {
  try {
    await prisma.$connect()
    console.log('Database connected successfully')
  } catch (error) {
    console.error('Failed to connect to database:', error)
    process.exit(1)
  }
}

testConnection()

避坑指南

1. 密码中的特殊字符需要 URL 编码：

   # 原始密码：p@ss#word
   # 编码后：p%40ss%23word
   DATABASE_URL="postgresql://user:p%40ss%23word@host:5432/db"

2. SSL 连接（云数据库通常需要）：

   DATABASE_URL="postgresql://...?sslmode=require"

3. 开发环境连接数过多：使用单例模式避免热重载创建多个连接

4. 生产环境忘记设置环境变量：部署前检查所有必需的环境变量

本节小结

• 连接字符串包含用户名、密码、主机、端口和数据库名
• 使用 .env 文件管理环境变量，不要提交敏感信息
• 开发环境使用单例模式避免连接数过多
• Serverless 环境需要配置较小的连接池