dbd 是一个数据加载和转换工具，它使数据分析师和工程师能够加载和转换 SQL 数据库中的数据。
项目描述
dbd：数据库原型设计工具
dbd 是一个数据库原型设计工具，它使数据分析师和工程师能够快速加载和转换 SQL 数据库中的数据。
dbd 可帮助您完成以下任务：
- 将 CSV、JSON、Excel 和 Parquet 数据加载到数据库。它支持本地和在线文件（HTTP URL）。数据可以增量或全部加载。
- 使用 insert-from-sql 语句转换现有数据库表中的数据。
- 执行 DDL（数据定义语言）SQL 脚本（如
CREATE SCHEMA等语句）。
dbd 的工作原理
dbd 处理包含目录和文件的模型目录：
- 目录创建新的数据库模式。
- 文件创建新的数据库表或视图。新表或视图的名称与数据文件名相同。
.csv、.json、.xlsx和.parquet数据文件被内省并作为表加载到数据库中。.sql执行包含 SQL SELECT 语句的文件，并将结果作为表或视图加载到数据库中。.ref文件包含一个或多个指向支持的数据文件的本地路径或 URL。引用的文件作为表加载到数据库中。.yamlfiles 包含上述文件的元数据。该文件与数据、或文件.yaml同名，并指定目标表列的详细信息（数据类型、约束、索引等）。文件是可选的。如果未指定，dbd 使用默认值（例如CSV 列的数据类型）.sql.ref.yamlTEXT.ddl文件包含多个用分号分隔的 SQL 语句，这些语句针对数据库执行。
dbd 知道处理模型目录中文件的正确顺序，以尊重创建对象之间的相互依赖关系。
dbd 目前支持 Postgres、MySQL/MariaDB、SQLite、Snowflake、BigQuery 和 Redshift 数据库。
入门和示例
此处提供了一个简短的 5 分钟入门教程 。
您还可以在此处查看 dbd 的示例。执行它们的最简单方法是克隆或下载 dbd 的 github 存储库并从 SQLite 示例开始。
python3 -m venv dbd-env
source dbd-env/bin/activate
pip3 install dbd
git clone https://github.com/zsvoboda/dbd.git
cd dbd/examples/sqlite/basic
dbd run .
这些命令应该创建一个新的basic.dbSQLite 数据库area，其中包含从目录中的相应文件创建和加载的population表。statemodel
安装数据库
dbd 需要 Python 3.8 或更高版本。
先决条件
检查您是否拥有最新版本的 Python 3.8 或更高版本。
python3 -V
如果不使用包管理器来安装最新的 python：
在 Fedora 上运行：
sudo yum install python3
在 Ubuntu 上运行：
sudo apt install python3
安装 Python 虚拟环境：
在 Fedora 上运行：
sudo yum install python3-virtualenv
在 Ubuntu 上运行：
sudo apt install python3-venv
在 Windows 上，只需从商店安装 Python 3.8 或更高版本。
然后激活虚拟环境：
在 Linux 上运行：
python3 -m venv dbd-env
source dbd-env/bin/activate
在 Windows 上运行：
python3 -m venv dbd-env
call dbd-env\Scripts\activate.bat
派皮
pip3 install dbd
或者
git clone https://github.com/zsvoboda/dbd.git
cd dbd
pip3 install .
运行数据库
dbd安装必须驻留在您的路径上的命令行可执行文件。有时 Python 将可执行文件（称为dbd）放在您的PATH. 安装后尝试执行dbd。如果找不到该命令，请尝试执行
export PATH=~/.local/bin:$PATH
并dbd再次运行。pip3通常会抱怨放置可执行文件的目录不在PATH. 您需要获取它建议的脚本目录并将其放在您的PATH.
一旦可以执行dbd命令，克隆 dbd 存储库并从 SQLite 示例开始：
git clone https://github.com/zsvoboda/dbd.git
cd dbd/examples/sqlite/basic
dbd run .
您也可以从本教程开始。
启动一个新的 dbd 项目
init您可以通过执行命令生成 dbd 项目初始布局：
dbd init <new-project-name>
该init命令生成一个新的 dbd 项目目录，内容如下：
model包含内容文件的目录。dbd.profile定义数据库连接的配置文件。profile 文件通常由更多的 dbd 项目共享。dbd.project项目配置文件引用配置文件中的连接之一并定义model目录位置。
dbd 配置文件
dbd 将数据库连接存储在dbd.profile配置文件中。dbd 在当前目录或您的主目录中搜索它。您可以使用--profile选项将其指向不同位置的配置文件。
profile 文件是 YAML 文件，结构如下：
databases:
db1:
db.url: <sql-alchemy-database-url>
db2:
db.url: <sql-alchemy-database-url>
db3:
db.url: <sql-alchemy-database-url>
有关特定 SQLAlchemy 数据库 URL 格式的更多详细信息，请阅读此文档。
dbd项目配置文件
dbd 将项目配置存储在项目配置文件中，该文件通常存储在您的 dbd 项目目录中。dbd.projectdbd在项目的根目录中搜索文件。您还可以使用命令的--project选项dbd来指定自定义项目配置文件。
项目配置文件还使用 YAML 格式，并从配置文件配置文件中引用 dbd 模型目录和数据库连接。项目文件中的所有路径都是相对于配置文件所在目录的绝对路径或相对路径。
例如：
model: ./model
database: db2
模型目录
模型目录包含目录和文件。目录代表数据库模式。在大多数情况下，文件代表数据库表。
比如这个model目录布局
dbd-model-directory
+- schema1
+-- us_states.csv
+- schema2
+-- us_counties.csv
创建两个数据库模式：schema1和schema2和两个数据库表：us_statesinschema1和us_countiesin schema2。这两个表都填充了 CSV 文件中的数据。
dbd 支持位于model目录中的以下文件：
- DATA 文件：
.csv,.json,.xls,.xlsx,.parquet文件作为表加载到数据库 - REF 文件：
.ref文件包含一个或多个本地文件的绝对或相对路径或以表格形式加载到数据库的在线数据文件的 URL。所有引用的文件必须具有相同的结构，因为它们被加载到同一个表中。 - SQL 文件：
.sqlwith SQL SELECT 语句使用 insert-from-select SQL 结构执行。生成 INSERT 命令（SQL 文件只包含 SQL SELECT 语句） - DDL 文件：包含一系列以分号分隔的 SQL 语句。DDL 文件可以命名
prolog.ddl为epilog.ddl. 在prolog.ddl特定模式中的所有其他文件之前执行。最后epilog.ddl执行。顶层模型目录中的 和 作为模型中的第一个或最后一个文件执行prolog.ddl。epilog.ddl - YAML 文件：为DATA、SQL和REF文件指定附加配置。
参考文件
.reffile 包含对 dbd 作为表加载到数据库的文件的一个或多个引用。引用可以是 URL、绝对文件路径或相对于文件的路径.ref。所有引用的数据文件必须具有相同的结构，因为它们被加载到同一个数据库表中。
下面是一个.ref文件示例：
https://raw.githubusercontent.com/CSSEGISandData/COVID-19/master/csse_covid_19_data/csse_covid_19_daily_reports/01-03-2022.csv
https://raw.githubusercontent.com/CSSEGISandData/COVID-19/master/csse_covid_19_data/csse_covid_19_daily_reports/01-04-2022.csv
../data/01-05-2022.csv
../data/01-06-2022.csv
只要文件具有相同的结构（列数和列类型），路径和 URL 可以指向具有不同格式（例如 CSV 或 JSON）的数据文件。
引用 ZIP 档案中的文件
>REF 文件支持使用路径分隔符引用 ZIP 存档中的文件的路径。例如：
../data/archive.zip>covid-variants.csv
或者
https://raw.githubusercontent.com/zsvoboda/dbd/master/tests/fixtures/capabilities/zip_local/data/archive.zip>covid-variants.csv
Kaggle 数据集
kaggle://kaggle-dataset-name>dataset-file您可以使用url引用 kaggle 数据集。
例如：
kaggle://kalilurrahman/new-york-times-covid19-dataset>us.csv
Kaggle 身份验证
要使用 Kaggle API，请在https://www.kaggle.com注册一个 Kaggle 帐户。然后转到您的用户配置文件 ( https://www.kaggle.com/<username>/account) 的“帐户”选项卡并选择“创建 API 令牌”。这将触发 kaggle.json 的下载，该文件包含您的 API 凭据。将此文件放在该位置~/.kaggle/kaggle.json（在 Windows 上的该位置
C:\Users\<Windows-username>\.kaggle\kaggle.json- 您可以检查确切的位置，无驱动器，使用echo %HOMEPATH%）。您可以定义一个 shell 环境变量KAGGLE_CONFIG_DIR来将此位置更改为$KAGGLE_CONFIG_DIR/kaggle.json
（在 Windows 上它将是%KAGGLE_CONFIG_DIR%\kaggle.json）。
为了您的安全，请确保您计算机的其他用户对您的凭据没有读取权限。在基于 Unix 的系统上，您可以使用以下命令执行此操作：
chmod 600 ~/.kaggle/kaggle.json
您还可以选择将您的 Kaggle 用户名和令牌导出到环境中：
export KAGGLE_USERNAME=datadinosaur
export KAGGLE_KEY=xxxxxxxxxxxxxx
SQL 文件
.sql文件在目标数据库中执行 SQL 数据转换。它包含一个 SQL SELECT 语句，dbd 将其包装在 insert-from-select 语句中，执行它，并将结果存储到从 SQL 文件名继承其名称的表或视图中。
下面是一个us_states.sql创建新us_states数据库表的文件示例：
SELECT
state.abbrev AS state_code,
state.state AS state_name,
population.population AS state_population,
area.area_sq_mi AS state_area_sq_mi
FROM state
JOIN population ON population.state = state.abbrev
JOIN area on area.state_name = state.state
YAML 文件
.yamlfile 为具有相同基本文件名的相应DATA、REF或SQL文件指定附加配置。以下是上述us_states.sql文件的 YAML 配置示例：
table:
columns:
state_code:
nullable: false
primary_key: true
type: CHAR(2)
state_name:
nullable: false
index: true
type: VARCHAR(50)
state_population:
nullable: false
type: INTEGER
state_area_sq_mi:
nullable: false
type: INTEGER
process:
materialization: table
mode: drop
该文件将和列.yaml重新键入为 INTEGER，不允许所有列中的 NULL 值，并使列表的主键。state_populationstate_area_sq_mistate_code
您不必描述所有表格的列。对于 DATA 文件，您遗漏的列的类型将设置为默认的 TEXT 数据类型，并且在 SQL 文件的情况下由 insert-from-select 定义。
每次 dbd 执行此模型时，us_states.sql都会删除表并重新加载完整的数据。
表格部分
.yaml文件的列映射到 dbd 从相应的DATA、REF或SQL文件创建的表的列。例如，CSV 标题列或 SQL SELECT 列AS列子句。
dbd 支持以下列的参数：
- type：列的 SQL 类型。
- primary_key：是表主键的列部分（true|false）？
- foreign_keys：从表中的列引用的所有其他数据库表列（格式为
foreign-table.referenced-column）。 - 可空：列是否允许空值（真|假）？
- 索引：列是否被索引（真|假）？
- unique：列是否存储唯一值（true|false）？
工艺部分
该process部分定义了以下处理选项：
- materialization：指定 dbd在处理 SQL 文件时是创建物理文件
table还是创建文件。REF和DATA文件总是产生物理表view。 - mode：指定 dbd 对表数据的处理方式。您可以指定值
drop、truncate或keep。视图的 模式选项被忽略。
迭代开发
该dbd工具的参数--only允许您指定要处理的表的子集，从而有助于迭代开发过程。该--only参数接受以逗号分隔的完全限定表名 ( schema. table-name) 列表。例如：
dbd run --only stage.ext_country
只处理模式ext_country中的表stage。
该--only参数还处理所有传递的表的依赖项。您可以使用选项跳过依赖--no-deps项。
神社模板
大多数模型文件都支持Jinja2 模板。例如，此REF文件将 6 个 CSV 文件加载到数据库（4 个来自 URL 的在线文件和 2 个来自本地文件系统的文件）：
{% for n in range(4) %}
https://raw.githubusercontent.com/CSSEGISandData/COVID-19/master/csse_covid_19_data/csse_covid_19_daily_reports/01-0{{ n+1 }}-2022.csv
{% endfor %}
../data/01-05-2022.csv
../data/01-06-2022.csv
Profile 项目配置文件也是我们 Jinja2 模板。{{ environment-variable-name }}您可以使用语法扩展任何环境变量。例如，您可以在环境变量中定义数据库连接参数，如用户名或密码，并使用此配置文件配置文件：
databases:
states_snowflake:
db.url: "snowflake://{{ SNOWFLAKE_USER }}:{{ SNOWFLAKE_PASSWORD }}@{{ SNOWFLAKE_ACCOUNT_IDENTIFIER }}/{{ SNOWFLAKE_DB }}/{{ SNOWFLAKE_SCHEMA }}?warehouse={{SNOWFLAKE_WAREHOUSE }}"
covid:
db.url: "snowflake://{{ SNOWFLAKE_USER }}:{{ SNOWFLAKE_PASSWORD }}@{{ SNOWFLAKE_ACCOUNT_IDENTIFIER }}/{{ SNOWFLAKE_DB }}/{{ SNOWFLAKE_SCHEMA }}?warehouse={{SNOWFLAKE_WAREHOUSE }}"
快速数据加载模式
除 SQLite 外，所有支持的数据库引擎都支持快速数据加载模式。在此模式下，使用批量加载 (SQL COPY) 命令而不是单独的 INSERT 语句将数据加载到数据库表中。
MySQL 和 Redshift 需要额外的配置来启用快速数据加载模式。如果没有这个额外的配置，dbd 会通过 INSERT 语句恢复到慢速插入模式。
MySQL
要启用快速加载模式，您需要local_infile=1在 MySQL 连接 url 中指定查询参数。您还必须在 MySQL 服务器上启用 LOCAL INFILE 模式。例如，您可以通过执行以下 SQL 语句来做到这一点：
SET GLOBAL local_infile = true
红移
要启用快速加载模式，您需要copy_stage在dbd.project配置文件中指定参数。该参数必须引用配置文件copy_stage中的存储定义。dbd.profile检查examples/redshift/covid_cz目录中的示例配置文件。以下是这些配置文件使用的环境变量的示例定义：
export AWS_COVID_STAGE_S3_URL="s3://covid/stage"
export AWS_COVID_STAGE_S3_ACCESS_KEY="AKIA43SWERQGXMUYFIGMA"
export AWS_COVID_STAGE_S3_S3_SECRET_KEY="iujI78eDuFFGJF6PSjY/4CIhEJdMNkuS3g4t0BRwX"
执照
dbd 代码在BSD 3-clause license下开源。
