import-db
将数据库中的表或 SQL 查询结果快照为 CSV/JSON 格式。
usage: dvc import-db [-h] [-q | -v]
[--sql sql | --table table] [--conn conn]
[--output-format [{csv,json}]] [-o [<path>]] [-f]描述
使用 import-db，你可以将 ETL/数据库内容快照为文件，用于数据管道中。该命令支持将表或 SQL 查询结果导入为多种文件格式。为此，你需要设置连接字符串以连接数据库，可通过配置项 db.<name> 进行设置。更多信息请参见 数据库连接。
目前，import-db 支持两种输出格式：
- JSON 记录
- CSV（含表头，无索引）
将在相同位置创建一个 导入 .dvc 文件，例如 customers.txt.dvc。这样可以在数据源发生变化时更新导入内容（参见 dvc update）。
数据库连接
要连接数据库，DVC 需要一个数据库连接字符串 URI。该字符串必须在 db 配置节中进行配置。
$ dvc config db.pgsql.url postgresql://user@hostname:port/database
$ dvc config --local db.pgsql.password password安全警告
使用 --local 选项配置 password，使其写入被 Git 忽略的配置文件中。
安全警告
请使用具有只读权限的受限访问账户，因为 --sql 可以执行任意查询。不同数据库对此有不同的管理方式，请参考相应文档了解详情。
使用 import-db 时，需要指定要使用的数据库连接名称。
$ dvc import-db --table customers_table --conn pgsql除了连接字符串外，DVC 还需要相应的驱动程序来连接数据库。请参见 安装数据库驱动，了解特定数据库所需的连接字符串格式和必要驱动。
安装数据库驱动
DVC 不预装所有数据库的驱动程序，你需要为所使用的数据库手动安装必要的包。
以下列出了一些推荐的包及其对应的连接字符串：
| 数据库 | PyPI 包 | 连接字符串 |
|---|---|---|
| Amazon Redshift | sqlalchemy-redshift | redshift+psycopg2://{username}:{password}@{aws_endpoint}:5439/{database_name} |
| Big Query | pip install sqlalchemy-bigquery | bigquery://{project_id} |
| Databricks | databricks-sql-connector | databricks://token:{token}@{hostname}:{port}/{database}?http_path={http_path} |
| MySQL | mysqlclient | mysql://{username}:{password}@{hostname}/{database_name} |
| Oracle | cx_Oracle | oracle://{username}:{password}@{hostname}/{database_name} |
| PostgreSQL | psycopg2 | postgresql://{username}:{password}@{hostname}/{database_name} |
| Snowflake | snowflake-sqlalchemy | snowflake://{user}:{password}@{account}.{region}/{database}?role={role}&warehouse={warehouse} |
| SQLite | - | sqlite://path/to/file.db |
| SQL Server | pyodbc | mssql+pyodbc://{username}:{password}@{hostname}:{port}/{database_name} |
| Trino | trino | trino://{username}:{password}@{hostname}:{port}/{catalog} |
DVC 内部使用 sqlalchemy，因此理论上应支持所有为 SQLAlchemy 提供方言的 SQL 数据库。更多细节请参考其 文档。
选项
-
-o <路径>，--out <路径>- 指定工作区中存放文件的目标路径。如果未指定，则文件名将根据--output-format和--table的参数生成；对于--sql，默认以 "results" 开头。 -
--table <表名>- 要快照的表。 -
--sql <查询语句>- 执行 SQL 查询并对其结果进行快照。 -
--output-format- 要物化的格式类型。支持csv（默认）和json。 -
--conn 连接名称- 要使用的数据库连接名称。该连接必须在 配置 中设置。 -
-f,--force- 当使用--out指定本地目标文件或目录时，如果这些路径已存在，操作将失败。使用此标志会强制执行操作，导致命令覆盖现有的本地文件/目录。 -
-h,--help- 打印使用说明/帮助信息，然后退出。 -
-q,--quiet- 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。 -
-v,--verbose- 显示详细的跟踪信息。
示例
下载一个表
要使用已设置的 db 配置从数据库导入一张表：
$ dvc import-db --table "customers_table" --conn pgsql
...dvc import-db 将对整个表进行快照，并保存为名为 customers_table.csv 的文件。同时还会创建一个 customers_table.csv.dvc 文件，其内容如下：
md5: ddd4654188815dcae6ce4d4a37f83bde
frozen: true
deps:
- db:
file_format: csv
connection: pgsql
table: customers_table
outs:
- md5: 131543a828b297ce0a5925800bd88810
size: 15084226
hash: md5
path: customers_table.csv你可以使用 dvc update 来更新此快照。
下载 SQL 查询结果
类似地，你也可以按如下方式对 SQL 查询结果进行快照：
$ dvc import-db --sql "select * from customers" --conn pgsql
...dvc import-db 将对查询结果进行快照，并保存为名为 results.csv 的文件。同样，它也会创建一个 results.csv.dvc 文件，可用于后续通过 dvc update 进行更新。