YDB Go SDK 开源项目手册

本手册旨在指导开发者了解并使用 ydb-go-sdk, 一个纯Go编写的用于YDB数据库的原生驱动和database/sql接口实现。本SDK支持YDB的数据发现、操作、表处理、查询、协调、限流器、方案、脚本及主题客户端，适用于需要在Go语言中集成YDB功能的应用。

1. 目录结构及介绍

YDB Go SDK的仓库遵循标准的Go模块组织结构。下面是其主要目录结构的概览：

.
├── AUTHORS                  # 作者列表
├── CHANGELOG.md             # 变更日志
├── CODE_OF_CONDUCT.md       # 代码行为规范
├── CONTRIBUTING.md          # 贡献指南
├── LICENSE                  # 许可证文件，采用Apache-2.0协议
├── MIGRATION_v2_v3.md       # 版本迁移指南
├── NEXT_MAJOR_RELEASE.md    # 下一重大版本更新说明
├── NOTICE                   # 注意事项
├── README.md                # 项目简介
├── SECURITY.md              # 安全政策
├── SQL.md                   # SQL相关使用文档
├── codecov.yml              # Codecov配置文件
├── go.mod                   # Go模块描述文件
├── go.sum                   # Go依赖校验文件
└── src                       # 源码目录
    ├── ...                   # 含有多个子目录，如
    │   ├── examples         # 示例代码
    │   ├── internal         # 内部库
    │   ├── ...
    └── ydb                  # 主要包，包含核心逻辑
        ├── ...               # 包含driver、options、query等关键组件

每个子目录和文件都有明确的功能分工，例如examples目录提供多种使用场景示例，而ydb目录则包含核心的数据库交互逻辑。

2. 项目的启动文件介绍

虽然YDB Go SDK本身不涉及特定应用的“启动文件”，但使用该SDK的项目通常会从调用ydb.Open()函数开始，这是连接到YDB数据库的入口点。下面是一个简化的应用示例，展示了如何初始化连接：

package main

import (
    "context"
    "log"
    "github.com/ydb-platform/ydb-go-sdk/v3"
)

func main() {
    ctx := context.Background()
    db, err := ydb.Open(ctx, "grpc://localhost:2136/local")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close() // 确保资源最终被释放
    // 进一步的操作，比如执行查询或事务...
}

3. 项目的配置文件介绍

YDB Go SDK主要通过环境变量和连接字符串来配置。它不直接依赖于传统的配置文件（如.yaml或.toml），而是允许通过代码参数或环境变量来定制行为。关键的配置选项包括SSL证书路径(YDB_SSL_ROOT_CERTIFICATES_FILE)、日志级别(YDB_LOG_SEVERITY_LEVEL)和连接字符串中的认证信息等。这些可以通过设置环境变量的方式来个性化配置。例如，若需修改SSL证书的位置，可以在运行应用程序前设置：

export YDB_SSL_ROOT_CERTIFICATES_FILE=/path/to/your/certificates.pem

对于更加复杂的配置需求，如自定义认证方式，通常会在创建数据库连接时直接指定相应的配置项，如使用匿名凭证、访问令牌或者静态凭证等。

---

以上就是关于YDB Go SDK的基本结构、启动流程及配置方法的概述，这将帮助开发者快速上手使用此SDK进行数据库操作。记得查看项目文档和示例代码以获得更详尽的信息和最佳实践。