# @deepnote/database-integrations 中文文档

规范地址：https://npmcn.com/package/%40deepnote/database-integrations/

版本：2\.1\.0
npm 元数据更新时间：2026-11-10T06:44:51.049Z
中文译文更新时间：2026-11-11T20:30:41.320Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepnote/database-integrations
原文对照：https://npmcn.com/package/%40deepnote/database-integrations/?lang=original
项目主页：https://github.com/deepnote/deepnote#readme
源码仓库：https://github.com/deepnote/deepnote

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：284 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-10-31T16:11:03.993Z
- 最新版本发布：2026-11-10T06:44:50.739Z
- 近 30 天下载量：6623（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 16 个）

## 中文简介

深注数据库整合定义

## 安装

```sh
npm install @deepnote/database-integrations
```

也可以使用：`pnpm add @deepnote/database-integrations`、`yarn add @deepnote/database-integrations`、`bun add @deepnote/database-integrations`

## README

# @deepnote/数据库整合

数据库-集成包定义了Deepnote数据库集成.

## 概览

这个软件包提供TypeScript类型和公用设备,用于Deepnote SQL块集成和其他数据库集成,包括:

-   **整合类型**
-   **认证方法类型**
-   **整合元数据计划**

## 支持的整合

-   数据Frame SQL (`pandas-dataframe`(中文(简体) )
-   亚马逊·雅典娜(亚马逊)`athena`(中文(简体) )
-   亚马逊红移( Amazon)`redshift`(中文(简体) )
-   点击之家( E)`clickhouse`(中文(简体) )
-   数据砖`databricks`(中文(简体) )
-   德雷米奥`dremio`(中文(简体) )
-   Google 合金数据库 (`alloydb`(中文(简体) )
-   谷歌大查询( G)`big-query`(中文(简体) )
-   Google Spanner (英语:`spanner`(中文(简体) )
-   马里亚DB(`mariadb`(中文(简体) )
-   物质化(`materialize`(中文(简体) )
-   微软 SQL 服务器 (Azure SQL) (`sql-server`(中文(简体) )
-   MindsDB (英语:`mindsdb`(中文(简体) )
-   蒙戈DB (英语:`mongodb`(中文(简体) )
-   MySQL (英语:`mysql`(中文(简体) )
-   PostgreSQL (英语:`pgsql`(中文(简体) )
-   雪花( 雪花 )`snowflake`(中文(简体) )
-   特里诺( Trino )`trino`(中文(简体) )

## API 参考

### 整合类型

-   类型
    -   `type DatabaseIntegrationType` - 所有支持的数据库整合类型
    -   `type DatabaseIntegrationTypeWithSslSupport` - 支持SSL(子集: `DatabaseIntegrationType`(中文(简体) )
    -   `type SqlIntegrationType` - SQL 集成类型(子集 `DatabaseIntegrationType`页:1 `mongodb`
-   运行时间值
    -   `databaseIntegrationTypes` - 所有支助数据库整合类型的阵列(`DatabaseIntegrationType[]`(中文(简体) )
    -   `databaseIntegrationTypesWithSslSupport` - 支持SSL的所有数据库集成类型阵列(`DatabaseIntegrationTypeWithSslSupport[]`(中文(简体) )
    -   `sqlIntegrationTypes` - 所有SQL集成类型的阵列(`SqlIntegrationType[]`(中文(简体) )

### 整合元数据

-   zod 计划
    -   `databaseMetadataSchemasByType` - Zod计划,按集成类型验证集成元数据
        
        ```ts
        databaseMetadataSchemasByType['big-query'].safeParse({ ... })
        ```
        
-   类型
    -   `type DatabaseIntegrationMetadataByType` - 按整合类型分列的整合元数据类型
        
        ```ts
        const metadata: DatabaseIntegrationMetadataByType['big-query'] = { ... }
        ```
        

### 环境变量和配置

-   水电费
    -   `getEnvironmentVariablesForIntegrations(integrations: Array<DatabaseIntegrationConfig>, params: { projectRootDirectory: string, snowflakePartnerIdentifier?: string })` – 创建一个执行使用集成的笔记本时需要设置的环境变量列表,变量的格式被Deepnote工具包所消耗
        -   参数 :
            -   `integrations` - 积极融合列表
            -   `params.projectRootDirectory` - 项目根目录,用于构建 CA 证书的路径
            -   `params.snowflakePartnerIdentifier` (可选) – Snowflake partner 标识符,用于构建 Snowflake 连接 URL;用于 Snowflake 的内部遥测/分析,不影响集成的功能
        -   返回 :
            -   `envVars: Array<EnvVar>` - 执行使用集成的笔记本时需要设置的环境变量列表
                -   所产生的可变名称格式如下:
                    -   `*INTEGRATION_NAME*_*METADATA_KEY*` - 用于整合的每个元数据领域
                    -   `SQL_*INTEGRATION_ID*` - 每个SQL集成的SQL Alchemy配置
            -   `errors: Array<Error>` – 生成环境变量时出错列表. 抛出这些功能不是为了允许部分功能,即使有些集成被错配置.
    -   `getSqlAlchemyInput(sqlIntegration: SqlIntegrationConfig, params: { projectRootDirectory: string, snowflakePartnerIdentifier?: string })` – 为 SQL 集成创建 SQL Alchemy 配置,用于从 SQL 块连接到数据库. 这在内部使用 `getEnvironmentVariablesForIntegrations()`。 。 。 .
        -   参数 :
            -   `sqlIntegration` - SQL 集成配置
            -   `params.projectRootDirectory` - 项目根目录,用于构建 CA 证书的路径
            -   `params.snowflakePartnerIdentifier` (可选)-见上文
        -   返回 :
            -   `SqlAlchemyInput | null` - SQL Alchemy 集成配置, `null` 当集成已联合认证时
        -   抛出 :
            -   `BigQueryServiceAccountParseError` — 当解析大查询服务账户失败时
            -   `SpannerServiceAccountParseError` - 当解析 Spanner 服务账户失败时
-   类型
    -   `type DatabaseIntegrationConfig` - 生成环境变量时的集成配置
        -   `type` - 整合类型
        -   `id` - 集成ID(通常是UUID)
        -   `name` - 整合名称
        -   `metadata` - 集成元数据
        -   `federated_auth_method` (可选) – 联合认证方法,仅在集成已启用联合认证时使用. 还检查了通过元数据配置的认证方法,这些方法应该匹配.
    -   `type SqlIntegrationConfig` - 当生成环境变量时, SQL 集成的配置( 子集) `DatabaseIntegrationConfig`,不包括非SQL整合)
    -   `type SqlAlchemyInput` - SQL Alchemy 集成SQL的配置
-   错误
    -   `BigQueryServiceAccountParseError` - 当解析大查询服务账户失败时
        -   `cause: Error` — 原始错误
    -   `SpannerServiceAccountParseError` - 当分析 Spanner 服务账户失败时
        -   `cause: Error` — 原始错误

### 认证方法

这些值可用于配置具有多种认证方法的集成.

-   类型
    -   `type DatabaseAuthMethod` - 数据库集成的认证方法
    -   `type AwsAuthMethod` - AWS集成的认证方法
    -   `type BigQueryAuthMethod` - 大查询集成的认证方法
    -   `type SnowflakeAuthMethod` - 雪花整合认证方法
    -   `type FederatedAuthMethod` - 联邦认证整合认证方法
-   运行时间值
    -   `AwsAuthMethods` - 都支持AWS认证方法
    -   `BigQueryAuthMethods` - 都支持大查询认证方法
    -   `DatabaseAuthMethods` - 所有支持的数据库认证方法
    -   `SnowflakeAuthMethods` - 所有人都支持雪花认证方法
    -   `federatedAuthMethods` - 所有得到支持的联邦认证方法

## 类型脚本中使用

### 示例: 显示可用的集成列表

```ts
import { databaseIntegrationTypes } from "@deepnote/database-integrations";

console.log(databaseIntegrationTypes); // ['athena', 'redshift', …]
```

### 示例:验证集成元数据

```ts
import { databaseMetadataSchemasByType } from "@deepnote/database-integrations";

const validationResult = databaseMetadataSchemasByType["big-query"].safeParse({
  authMethod: BigQueryAuthMethods.ServiceAccount,
  service_account: "my-account",
});
if (validationResult.error) {
  console.error(validationResult.error);
}
```

### 示例: 为配置集成获取环境变量

```ts
import { getEnvironmentVariablesForIntegrations } from "@deepnote/database-integrations";

const integrations = [
  {
    type: "pgsql",
    id: "my-postgres",
    name: "My PostgreSQL Integration",
    metadata: {
      host: "my-host",
      user: "my-user",
      password: "my-password",
      database: "my-database",
    },
  },
];

const { envVars } = getEnvironmentVariablesForIntegrations(integrations, {
  projectRootDirectory: "/path/to/project",
});

// envVars = [
//   { name: "INTEGRATION_MY_POSTGRES_HOST", value: "my-host" },
//   { name: "INTEGRATION_MY_POSTGRES_USER", value: "my-user" },
//   { name: "INTEGRATION_MY_POSTGRES_PASSWORD", value: "my-password" },
//   { name: "INTEGRATION_MY_POSTGRES_DATABASE", value: "my-database" },
//   { name: "SQL_MY_POSTGRES", value: '{"url": "postgresql://my-user:my-password@my-host/my-database", "params": {}, "param_style": "pyformat"}' },
// ]
```

### 示例: 映射类型

```ts
import {
  type DatabaseIntegrationMetadataByType,
  type DatabaseIntegrationType,
} from "@deepnote/database-integrations";

const myIntegrationDocsLinks: Record<
  DatabaseIntegrationType,
  { docsLink: string }
> = {
  "big-query": { docsLink: "https://example.com/my-docs/bq" },
  // …
};
```

## 笔记本的使用

SQL 块执行( 设置于 `@deepnote/blocks`· 选取环境变量并将其传递给 " 深意工具包 " (`_dntk.execute_sql()`(中文(简体) )

### MongoDB 用户

MongoDB不是SQL集成,不是通过SQL块使用,而是通过代码块和 `pymongo`。 。 。 .

```python
import os
from pymongo import MongoClient

# Connect to MongoDB using the connection string from environment variables
client = MongoClient(os.environ["INTEGRATION_NAME_CONNECTION_STRING"])
db = client[os.environ["INTEGRATION_NAME_DATABASE"]]
# Get the users collection
users_collection = db["users"]
# Find all documents in the users collection
users = list(users_collection.find())
```

说明: `INTEGRATION_NAME_` env变量的前缀使用下列逻辑构建.

> 在 IEEE Std 1003.1-2001 的 Shell 和 公用事业 卷中使用的环境可变名称仅由大写字母、数字和来自便携式字符集定义的字符的" "(下分数)组成,不以数字开头.

```python
import re

def convert_to_environment_variable_name(integration_name: str) -> str:
  without_first_digit = f"_{integration_name}" if re.match(r'^\d', integration_name) else integration_name
  upper_cased = without_first_digit.upper()
  return re.sub(r'[^\w]', '_', upper_cased)
```

## 常见问题

### @deepnote/database-integrations 是什么？

深注数据库整合定义

### 如何安装 @deepnote/database-integrations？

在项目目录运行 npm install @deepnote/database-integrations，或使用 pnpm add / yarn add / bun add。

### @deepnote/database-integrations 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deepnote/database-integrations 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deepnote/database-integrations 可以商用吗？

@deepnote/database-integrations 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @deepnote/database-integrations 的下载量有多少？

根据 npm 官方下载统计，@deepnote/database-integrations 在 2026/10/12 – 2026/11/10 这 30 天内被下载 6,623 次，日均约 221 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepnote/database-integrations 还在维护吗？

最新版本 2\.1\.0 发布于 2026/11/10（1 天前）；至今共发布 22 个版本，其中过去 12 个月发布了 16 个；首次发布于 2025/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。