连接到外部 PostgreSQL 数据库

LangSmith 使用 PostgreSQL 数据库作为事务性工作负载和操作数据（除了运行数据以外的几乎所有内容）的主要数据存储。默认情况下，自托管版 LangSmith 会使用一个内置的 PostgreSQL 数据库。然而，您可以配置 LangSmith 使用外部 PostgreSQL 数据库。通过配置外部 PostgreSQL 数据库，您可以更轻松地管理数据库的备份、扩展和其他操作任务。

如果您使用的是托管 PostgreSQL 服务，我们推荐：

关于云特定的 IAM/工作负载身份认证，请参阅 IAM 认证章节。

要求

您的 LangSmith 实例需要网络访问一个已配置的 PostgreSQL 数据库。我们推荐使用托管 PostgreSQL 服务，例如：
注意：我们仅官方支持 PostgreSQL 14 及以上版本。
我们支持密码认证和 IAM/工作负载身份认证。
一个拥有 PostgreSQL 数据库管理员访问权限的用户。此用户将用于创建必要的表、索引和模式。
此用户还需要拥有在数据库中创建扩展的能力。我们将使用（或尝试安装） btree_gin、btree_gist、pgcrypto、citext、ltree 和 pg_trgm 扩展。
如果使用的模式不是 public，请确保没有其他模式启用了这些扩展，或者您必须将该模式包含在您的搜索路径中。
对 pgbouncer 和其他连接池的支持是基于社区的。社区成员报告称，pgbouncer 在 pool_mode = session 以及对 ignore_startup_parameters 进行适当设置（截至撰写时，需要忽略 search_path 和 lock_timeout）的情况下可以工作。需要小心避免污染连接池；具备一定 PostgreSQL 专业知识是明智的。LangChain Inc 目前没有为 pgbouncer、Amazon RDS 代理或其他任何连接池工具提供正式测试覆盖或商业支持的路线图计划，但欢迎社区通过 GitHub 问题讨论和协作支持。
默认情况下，我们推荐使用至少 2 个 vCPU 和 8GB 内存的实例。然而，实际需求将取决于您的工作负载和用户数量。我们建议监控您的 PostgreSQL 实例，并根据需要进行扩展。

连接字符串

您需要提供一个到 PostgreSQL 数据库的连接字符串。该连接字符串应包含以下信息：

主机
端口
数据库
用户名
密码（如果包含特殊字符，请确保进行 URL 编码） - 注意： 使用 IAM 认证时，连接字符串中不需要密码。详见下文。
URL 参数

其格式如下：

username:password@host:port/database?<url_params>

一个示例连接字符串可能如下所示：

myuser:mypassword@myhost:5432/mydatabase?sslmode=disable

不带 URL 参数时，连接字符串如下：

myuser:mypassword@myhost:5432/mydatabase

对于 IAM 认证，请省略密码，并将身份名称用作用户名：

my-workload-identity@myhost:5432/mydatabase?sslmode=require

配置

准备好连接字符串后，您可以配置 LangSmith 实例使用外部 PostgreSQL 数据库。这可以通过修改您的 LangSmith Helm Chart 安装的 values 文件来完成。

Helm

postgres:
  external:
    enabled: true
    connectionUrl: "您的连接 URL"

配置完成后，您应该能够重新安装您的 LangSmith 实例。如果一切配置正确，您的 LangSmith 实例现在应该正在使用您的外部 PostgreSQL 数据库。

使用 PostgreSQL 的 TLS

使用本节为 PostgreSQL 连接配置 TLS。有关挂载内部/公共 CA 以便 LangSmith 信任您的 PostgreSQL 服务器证书，请参阅配置自定义 TLS 证书。

服务器 TLS（单向）

要验证 PostgreSQL 服务器证书：

通过 config.customCa.secretName 和 config.customCa.secretKey 提供一个 CA 包。
在您的连接 URL 中使用 sslmode=require 或 sslmode=verify-full，以及 sslrootcert=system。

仅当您的 PostgreSQL 服务器使用内部或私有 CA 时，才需要挂载自定义 CA。公开受信任的 CA 不需要此配置。

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 包的键名
postgres:
  external:
    enabled: true
    connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system"
    customTls: true

apiVersion: v1
kind: Secret
metadata:
  name: langsmith-custom-ca
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <ROOT_OR_INTERMEDIATE_CA_CERT_CHAIN>
    -----END CERTIFICATE-----

双向 TLS 与客户端认证 (mTLS)

自 LangSmith Helm chart 版本 0.12.29 起，我们支持 PostgreSQL 客户端的 mTLS。对于 mTLS 中的服务器端认证，请在以下客户端证书配置的基础上，使用服务器 TLS 步骤（自定义 CA）。如果您的 PostgreSQL 服务器要求客户端证书认证：

提供包含客户端证书和密钥的 Secret。
通过 postgres.external.clientCert.secretName 引用它，并使用 certSecretKey 和 keySecretKey 指定密钥。
在连接 URL 中使用 sslmode=verify-full 和 sslrootcert=system。

postgres:
  external:
    enabled: true
    connectionUrl: "myuser:mypassword@myhost:5432/mydatabase?sslmode=verify-full&sslrootcert=system"
    customTls: true
    clientCert:
      secretName: "postgres-mtls-secret"
      certSecretKey: "tls.crt"
      keySecretKey: "tls.key"

apiVersion: v1
kind: Secret
metadata:
  name: postgres-mtls-secret
type: Opaque
stringData:
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    <CLIENT_CERT>
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    <CLIENT_KEY>
    -----END PRIVATE KEY-----

用于证书卷的 Pod 安全上下文

为 mTLS 挂载的证书卷受文件访问限制保护。为确保所有 LangSmith Pod 能够读取证书文件，您必须在 Pod 安全上下文中设置 fsGroup: 1000。您可以通过以下两种方式之一进行配置： 选项 1：使用 commonPodSecurityContext 在顶层设置 fsGroup 以将其应用于所有 Pod：

commonPodSecurityContext:
  fsGroup: 1000

选项 2：添加到各个 Pod 安全上下文 如果您需要更细粒度的控制，请将 fsGroup 单独添加到每个 Pod 的安全上下文中。有关完整参考，请参阅 mTLS 配置示例。

IAM 认证

自 LangSmith Helm chart 版本 0.12.34 起，我们支持 PostgreSQL 的 IAM 认证。这允许您使用云提供商的工作负载身份而不是静态密码。

IAM 认证仅处理连接认证。您可能仍然需要在数据库中运行 SQL 命令来创建 IAM 用户/角色，并授予其访问 LangSmith 模式所需的权限和特权。

AWS
GCP
Azure

Amazon RDS IAM 认证

Amazon RDS 支持 IAM 数据库认证，允许您使用 AWS IAM 凭证而不是数据库密码来认证到您的 PostgreSQL 实例。

先决条件

在您的 Kubernetes 集群中配置工作负载身份，使用 AWS IRSA 或 EKS Pod Identity
在您的 RDS PostgreSQL 实例上启用 IAM 认证 并授予您的工作负载身份访问权限

配置

如果您在 LangSmith 已经运行初始迁移后切换到新的 IAM 用户，您可能需要将现有表的所有权转移给新的 IAM 用户。否则，迁移可能会因对前一个用户拥有的表权限不足而失败。

将 iamAuthProvider 设置为 "aws" 并提供一个 IAM 兼容的连接字符串（不带密码）：

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "aws"

apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
type: Opaque
stringData:
  # IAM 连接 URL - 注意没有密码，用户名是 IAM 身份名称
  connection_url: "<iam-identity-name>@<rds-host>:5432/<database>?sslmode=require"

IAM 认证需要 TLS。您必须在连接字符串中包含 sslmode=require。

所需注解

您必须将 AWS IRSA 所需的 ServiceAccount 注解应用到所有连接到 PostgreSQL 的 LangSmith 组件：Deployments： backend、queue、platformBackend、hostBackend、ingestQueueJobs： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

上面列出的所有作业（e2eTest 除外）都使用 backend 服务账户。e2eTest 作业使用其自己的服务账户，并且需要单独的注解配置。

后端服务的示例配置：

backend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

queue:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

platformBackend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

hostBackend:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

ingestQueue:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"

有关可配置服务的完整列表，请参阅 Helm values 参考。

Cloud SQL IAM 认证

Cloud SQL 支持 IAM 认证，允许您使用 GCP 服务账户而不是数据库密码进行认证。

先决条件

在您的 Kubernetes 集群中配置工作负载身份，使用 GCP Workload Identity
在您的 Cloud SQL 实例上启用 IAM 认证 并授予您的工作负载身份访问权限

配置

将 iamAuthProvider 设置为 "gcp" 并提供一个 IAM 兼容的连接字符串（不带密码）：

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "gcp"

apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
type: Opaque
stringData:
  # IAM 连接 URL - 注意没有密码，用户名是服务账户邮箱
  connection_url: "<service-account>@<project>.iam@<cloud-sql-host>:5432/<database>?sslmode=require"

IAM 认证需要 TLS。您必须在连接字符串中包含 sslmode=require。

所需注解

您必须将 GCP Workload Identity 所需的 ServiceAccount 注解应用到所有连接到 PostgreSQL 的 LangSmith 组件：Deployments： backend、queue、platformBackend、hostBackend、ingestQueueJobs： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

上面列出的所有作业（e2eTest 除外）都使用 backend 服务账户。e2eTest 作业使用其自己的服务账户，并且需要单独的注解配置。

后端服务的示例配置：

backend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

queue:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

platformBackend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

hostBackend:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

ingestQueue:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: "<service-account>@<project>.iam.gserviceaccount.com"

有关可配置服务的完整列表，请参阅 Helm values 参考。

使用 Microsoft Entra 认证的 Azure Database for PostgreSQL

Azure Database for PostgreSQL 支持 Microsoft Entra 认证，允许您使用 Azure 托管标识而不是数据库密码进行认证。

先决条件

在您的 Kubernetes 集群中配置工作负载身份，使用 Azure Workload Identity
在您的 Azure Database for PostgreSQL 实例上启用 Microsoft Entra 认证 并授予您的工作负载身份访问权限

配置

将 iamAuthProvider 设置为 "azure" 并提供一个 IAM 兼容的连接字符串（不带密码）：

postgres:
  external:
    enabled: true
    existingSecretName: "postgres-secret"
    iamAuthProvider: "azure"

apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
type: Opaque
stringData:
  # IAM 连接 URL - 注意没有密码，用户名是托管标识名称
  connection_url: "<managed-identity-name>@<azure-postgres-host>:5432/<database>?sslmode=require"

IAM 认证需要 TLS。您必须在连接字符串中包含 sslmode=require。

所需注解和标签

您必须将 Azure Workload Identity 所需的 ServiceAccount 注解和 Pod 标签应用到所有连接到 PostgreSQL 的 LangSmith 组件：Deployments： backend、queue、platformBackend、hostBackend、ingestQueueJobs： migrations、authBootstrap、feedbackConfigMigration、feedbackDataMigration、e2eTest

上面列出的所有作业（e2eTest 除外）都使用 backend 服务账户。对于这些作业，您只需要配置 Pod 标签（Azure 要求 Pod 上带有 azure.workload.identity/use: "true"）。e2eTest 作业使用其自己的服务账户，并且需要单独的注解配置。

后端服务的示例配置：

backend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"
  migrations:
    labels:
      azure.workload.identity/use: "true"

queue:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

platformBackend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

hostBackend:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

ingestQueue:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"
  deployment:
    labels:
      azure.workload.identity/use: "true"

有关可配置服务的完整列表，请参阅 Helm values 参考。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started by cloud provider

Deploy with Terraform

Setup guides

Configuration

Connect external services

Platform auth & access control

Self-hosted observability

Hybrid

Scripts

Reference

要求

连接字符串

配置

使用 PostgreSQL 的 TLS

服务器 TLS（单向）

双向 TLS 与客户端认证 (mTLS)

用于证书卷的 Pod 安全上下文

IAM 认证

Amazon RDS IAM 认证

先决条件

配置

所需注解

Cloud SQL IAM 认证

先决条件

配置

所需注解

使用 Microsoft Entra 认证的 Azure Database for PostgreSQL

先决条件

配置

所需注解和标签

​要求

​连接字符串

​配置

​使用 PostgreSQL 的 TLS

​服务器 TLS（单向）

​双向 TLS 与客户端认证 (mTLS)

​用于证书卷的 Pod 安全上下文

​IAM 认证

​Amazon RDS IAM 认证

​先决条件

​配置

​所需注解

​Cloud SQL IAM 认证

​先决条件

​配置

​所需注解

​使用 Microsoft Entra 认证的 Azure Database for PostgreSQL

​先决条件

​配置

​所需注解和标签

要求

连接字符串

配置

使用 PostgreSQL 的 TLS

服务器 TLS（单向）

双向 TLS 与客户端认证 (mTLS)

用于证书卷的 Pod 安全上下文

IAM 认证

Amazon RDS IAM 认证

先决条件

配置

所需注解

Cloud SQL IAM 认证

先决条件

配置

所需注解

使用 Microsoft Entra 认证的 Azure Database for PostgreSQL

先决条件

配置

所需注解和标签