gocql 不支持 SOURCE 命令（该命令仅限 cqlsh CLI 工具），需手动读取 CQL 文件内容、按语句分割并逐条执行，本文详解实现步骤、注意事项及健壮性优化方案。
gocql 不支持 `source` 命令（该命令仅限 cqlsh cli 工具），需手动读取 cql 文件内容、按语句分割并逐条执行，本文详解实现步骤、注意事项及健壮性优化方案。
在 Cassandra 应用开发中，常需通过 Go 程序初始化或重置数据库结构（如创建 keyspace、table 或插入基础数据）。虽然 cqlsh 提供了便捷的 SOURCE '/path/to/file.cql' 命令，但 SOURCE 并非标准 CQL 协议的一部分，而是 cqlsh 特有的客户端语法糖——gocql 作为底层驱动，仅支持合法的 CQL 语句（如 CREATE KEYSPACE, INSERT, DROP TABLE 等），因此直接传入 SOURCE (?) 必然触发解析错误：no viable alternative at input 'SOURCE'。
要正确执行本地 CQL 文件，核心思路是：读取文件 → 解析为独立语句 → 逐条提交执行。以下是推荐实现：
✅ 正确实现方式（含健壮性处理）
import (
"bufio"
"fmt"
"io"
"os"
"strings"
"github.com/gocql/gocql"
)
// ExecuteCQLFile 读取并执行 CQL 文件中的所有语句
func ExecuteCQLFile(session *gocql.Session, filePath string) error {
file, err := os.Open(filePath)
if err != nil {
return fmt.Errorf("failed to open CQL file %s: %w", filePath, err)
}
defer file.Close()
var statements []string
scanner := bufio.NewScanner(file)
var buffer strings.Builder
for scanner.Scan() {
line := strings.TrimSpace(scanner.Text())
// 跳过空行和注释行（支持 -- 和 /* */，此处简化处理单行注释）
if line == "" || strings.HasPrefix(line, "--") || strings.HasPrefix(line, "//") {
continue
}
// 累积多行语句（以分号结尾为完整语句）
buffer.WriteString(line)
if strings.HasSuffix(line, ";") {
stmt := strings.TrimSuffix(strings.TrimSpace(buffer.String()), ";")
if stmt != "" {
statements = append(statements, stmt)
}
buffer.Reset()
} else {
buffer.WriteString(" ")
}
}
if err := scanner.Err(); err != nil {
return fmt.Errorf("error reading file %s: %w", filePath, err)
}
// 处理缓冲区中未闭合的语句（无分号结尾）
if buffer.Len() > 0 {
stmt := strings.TrimSpace(buffer.String())
if stmt != "" {
statements = append(statements, stmt)
}
}
// 逐条执行
for i, stmt := range statements {
if err := session.Query(stmt).Exec(); err != nil {
return fmt.Errorf("failed to execute statement #%d (%q): %w", i+1, stmt[:min(len(stmt), 80)], err)
}
}
return nil
}
// 辅助函数：取最小值（Go 1.21+ 可用 slices.Min，此处兼容旧版）
func min(a, b int) int {
if a <h3>⚠️ 关键注意事项</h3>
- 语句分割必须基于分号（;）：CQL 语句以分号终止，但注意分号可能出现在字符串字面量或注释中（本示例未处理嵌套情况，生产环境建议使用成熟解析器如 cqlparser 或预处理脚本校验）；
- 事务与原子性：gocql 默认不提供跨语句事务（Cassandra 本身对 DDL 不支持事务），若需强一致性，应将逻辑拆分为幂等操作（如 CREATE KEYSPACE IF NOT EXISTS）；
- 权限与上下文：确保连接 session 具备执行各语句所需的权限（如 CREATE 权限），且 keyspace 已提前设置（可通过 session.Keyspace = "mykeyspace" 或在语句中显式指定）；
- 错误恢复：上述实现在任一语句失败时立即返回，适合初始化场景；如需“尽力执行”，可改为记录失败语句并继续。
✅ 最佳实践建议
- 将 CQL 文件按功能模块拆分（如 schema.cql, indexes.cql, seed-data.cql），便于版本控制与按需加载；
- 在 CI/CD 流程中，结合 gocql 初始化代码与 cqlsh -f 进行双重校验，保障脚本语法正确性；
- 对敏感操作（如 TRUNCATE, DROP），添加运行前确认开关或环境标记（如 if os.Getenv("ENV") == "prod" { panic("unsafe operation") }）。
通过以上方式，即可在 Go 应用中安全、可靠地复用 CQL 脚本，真正实现数据库 Schema 的代码化管理。
