YugabyteDB中使用Npgsql驱动连接YSQL的完整指南

最新推荐文章于 2025-06-05 09:05:15 发布

鲍爽沛David

最新推荐文章于 2025-06-05 09:05:15 发布

阅读量259

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00929/article/details/148440658

YugabyteDB中使用Npgsql驱动连接YSQL的完整指南

yugabyte-db yugabyte/yugabyte-db: 是 YugaByte DB 的官方仓库，一个高性能、高可扩展、分布式的 SQL 数据库，支持 PostgreSQL 兼容性。适合对分布式数据库、SQL 数据库和云原生应用的开发者。项目地址: https://gitcode.com/gh_mirrors/yu/yugabyte-db

概述

YugabyteDB是一个高性能的分布式SQL数据库，兼容PostgreSQL协议。本文将详细介绍如何在C#应用程序中使用PostgreSQL的Npgsql驱动连接YugabyteDB的YSQL接口，并执行基本的CRUD操作。

环境准备

在开始之前，请确保满足以下条件：

已安装.NET Core SDK（推荐3.1或更高版本）
已部署YugabyteDB集群并获取连接信息
对于SSL连接，准备好相应的CA证书

Npgsql驱动安装

使用Visual Studio安装

在解决方案资源管理器中右键点击"依赖项"
选择"管理NuGet程序包"
搜索"Npgsql"并安装最新稳定版

使用命令行安装

dotnet add package Npgsql

数据库连接配置

基本连接参数

YugabyteDB的YSQL接口使用以下默认连接参数：

| 参数名 | 描述 | 默认值 | |-----------|----------------------|-----------| | Host | 数据库服务器地址 | localhost | | Port | YSQL监听端口 | 5433 | | Database | 默认数据库名 | yugabyte | | Username | 默认用户名 | yugabyte | | Password | 用户密码 | yugabyte |

基本连接示例

var connString = "Host=localhost;Port=5433;Database=yugabyte;Username=yugabyte;Password=password";
using var conn = new NpgsqlConnection(connString);

SSL连接配置

对于需要SSL加密的连接，需要额外配置以下参数：

| 参数名 | 描述 | |-----------------|------------------------------| | SslMode | SSL验证模式 | | RootCertificate | CA证书路径 |

var connStringBuilder = new NpgsqlConnectionStringBuilder
{
    Host = "cluster.example.com",
    Port = 5433,
    SslMode = SslMode.VerifyFull,
    RootCertificate = "/path/to/root.crt",
    Username = "admin",
    Password = "securepassword",
    Database = "yugabyte"
};

性能优化建议

重要提示：Npgsql驱动在每次新建连接时会额外查询系统表来映射类型，这会显著增加连接时间。建议在连接字符串中添加以下配置来禁用此行为：

connStringBuilder.ServerCompatibilityMode = ServerCompatibilityMode.NoTypeLoading;

或直接在连接字符串中添加：

Server Compatibility Mode=NoTypeLoading;

CRUD操作示例

完整示例代码

using System;
using Npgsql;

namespace YugabyteDBNpgsqlDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var connString = "Host=localhost;Port=5433;Database=yugabyte;" +
                           "Username=yugabyte;Password=password;" +
                           "Server Compatibility Mode=NoTypeLoading";
            
            using var conn = new NpgsqlConnection(connString);
            
            try
            {
                conn.Open();
                
                // 创建表
                using (var cmd = new NpgsqlCommand(
                    "CREATE TABLE IF NOT EXISTS employee (" +
                    "id INT PRIMARY KEY, " +
                    "name VARCHAR, " +
                    "age INT, " +
                    "language VARCHAR)", conn))
                {
                    cmd.ExecuteNonQuery();
                    Console.WriteLine("员工表创建成功");
                }
                
                // 插入数据
                using (var cmd = new NpgsqlCommand(
                    "INSERT INTO employee (id, name, age, language) " +
                    "VALUES (1, '张三', 28, 'C#')", conn))
                {
                    int rows = cmd.ExecuteNonQuery();
                    Console.WriteLine($"插入了 {rows} 行数据");
                }
                
                // 查询数据
                using (var cmd = new NpgsqlCommand(
                    "SELECT name, age, language FROM employee WHERE id = @id", conn))
                {
                    cmd.Parameters.AddWithValue("id", 1);
                    
                    using var reader = cmd.ExecuteReader();
                    Console.WriteLine("查询结果:\n姓名\t年龄\t使用语言");
                    
                    while (reader.Read())
                    {
                        Console.WriteLine($"{reader.GetString(0)}\t" +
                                        $"{reader.GetInt32(1)}\t" +
                                        $"{reader.GetString(2)}");
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"操作失败: {ex.Message}");
            }
        }
    }
}

带SSL的完整示例

using System;
using Npgsql;

namespace YugabyteDBNpgsqlSSL
{
    class Program
    {
        static void Main(string[] args)
        {
            var connString = new NpgsqlConnectionStringBuilder
            {
                Host = "secure.cluster.example.com",
                Port = 5433,
                SslMode = SslMode.VerifyFull,
                RootCertificate = "/path/to/root.crt",
                Username = "admin",
                Password = "securepassword",
                Database = "yugabyte",
                ServerCompatibilityMode = ServerCompatibilityMode.NoTypeLoading
            }.ToString();
            
            ExecuteCRUDOperations(connString);
        }
        
        static void ExecuteCRUDOperations(string connString)
        {
            using var conn = new NpgsqlConnection(connString);
            
            try
            {
                conn.Open();
                
                // 创建表
                using (var cmd = new NpgsqlCommand(
                    "CREATE TABLE IF NOT EXISTS employee (" +
                    "id INT PRIMARY KEY, " +
                    "name VARCHAR, " +
                    "age INT, " +
                    "language VARCHAR)", conn))
                {
                    cmd.ExecuteNonQuery();
                    Console.WriteLine("员工表创建成功(SSL)");
                }
                
                // 插入数据
                using (var cmd = new NpgsqlCommand(
                    "INSERT INTO employee (id, name, age, language) " +
                    "VALUES (1, '李四', 32, 'C# with SSL')", conn))
                {
                    int rows = cmd.ExecuteNonQuery();
                    Console.WriteLine($"插入了 {rows} 行数据(SSL)");
                }
                
                // 查询数据
                using (var cmd = new NpgsqlCommand(
                    "SELECT name, age, language FROM employee WHERE id = @id", conn))
                {
                    cmd.Parameters.AddWithValue("id", 1);
                    
                    using var reader = cmd.ExecuteReader();
                    Console.WriteLine("查询结果(SSL):\n姓名\t年龄\t使用语言");
                    
                    while (reader.Read())
                    {
                        Console.WriteLine($"{reader.GetString(0)}\t" +
                                        $"{reader.GetInt32(1)}\t" +
                                        $"{reader.GetString(2)}");
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"操作失败: {ex.Message}");
            }
        }
    }
}

运行应用程序

在Visual Studio中运行

点击"调试"菜单
选择"开始执行(不调试)"

使用命令行运行

dotnet run

预期输出

非SSL连接示例输出：

员工表创建成功
插入了 1 行数据
查询结果:
姓名    年龄    使用语言
张三    28      C#

SSL连接示例输出：

员工表创建成功(SSL)
插入了 1 行数据(SSL)
查询结果(SSL):
姓名    年龄    使用语言
李四    32      C# with SSL

常见问题排查

连接失败：检查主机名、端口、用户名和密码是否正确
SSL验证失败：确保证书路径正确且证书有效
性能问题：确保已禁用类型加载(ServerCompatibilityMode)
超时问题：对于远程集群，考虑增加连接超时设置

进阶主题

连接池管理：Npgsql默认启用连接池，可通过连接字符串参数调整
批量操作：使用Npgsql的批量插入功能提高性能
事务处理：利用NpgsqlTransaction实现复杂事务
异步操作：使用ExecuteNonQueryAsync等异步方法提高吞吐量

通过本文的指南，您应该已经掌握了使用Npgsql驱动连接YugabyteDB并进行基本操作的方法。对于更高级的使用场景，建议参考Npgsql的官方文档和YugabyteDB的最佳实践。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考