连接

一旦您安装了驱动程序并拥有一个正在运行的 Neo4j 实例，您就可以将应用程序连接到数据库了。

连接到数据库

您可以通过创建一个 IDriver 对象并提供 URL 和身份验证令牌来连接到数据库。

using Neo4j.Driver;

// URI examples: "neo4j://", "neo4j+s://xxx.databases.neo4j.io"
const string dbUri = "<database-uri>";
const string dbUser = "<username>";
const string dbPassword = "<password>";

await using var driver = GraphDatabase.Driver(dbUri, AuthTokens.Basic(dbUser, dbPassword));  (1)
await driver.VerifyConnectivityAsync();  (2)
Console.WriteLine("Connection established.");

1	创建 `IDriver` 实例仅提供有关如何访问数据库的信息，并不会真正建立连接。连接会被推迟到执行第一个查询时才进行。
2	若要立即验证驱动程序是否可以连接到数据库（验证凭据、版本兼容性等），请在初始化驱动程序后使用 `.VerifyConnectivityAsync()` 方法。如果出现失败，启用驱动程序日志有助于诊断问题。

创建 IDriver 对象和验证连接都可能引发多种不同的异常。由于连接错误会阻碍后续任何任务的执行，最常见的做法是在建立连接时如果发生异常，就让程序崩溃。

IDriver 对象是不可变的、线程安全的，且创建开销较大，因此您的应用程序应仅创建一个实例并将其传递使用（您可以在多个线程间共享 IDriver 实例）。您可以在不创建新 IDriver 实例的情况下，以不同用户身份运行查询。如果您想更改 IDriver 配置，则需要创建一个新对象。

该驱动程序还支持其他身份验证方法（Kerberos、Bearer、自定义）。

连接到 Aura 实例

当您创建 Aura 实例时，会收到一个文本文件（所谓的 Dotenv 文件），其中包含以环境变量形式存储的数据库连接信息。该文件名为 Neo4j-a0a2fa1d-Created-2023-11-06.txt 之类格式。

您可以手动从该文件中提取 URI 和凭据，也可以使用第三方模块来加载它们。我们推荐使用 dotenv.net 模块来实现此目的。

使用 dotenv.net 从 Dotenv 文件中提取凭据

using Neo4j.Driver;
using dotenv.net;

DotEnv.Load(options: new DotEnvOptions(
    envFilePaths: new[] {"Neo4j-a0a2fa1d-Created-2023-11-06.txt"},
    ignoreExceptions: false,
    overwriteExistingVars: false
));

string? dbUri = Environment.GetEnvironmentVariable("NEO4J_URI");
string? dbUser = Environment.GetEnvironmentVariable("NEO4J_USERNAME");
string? dbPassword = Environment.GetEnvironmentVariable("NEO4J_PASSWORD");

await using var driver = GraphDatabase.Driver(dbUri, AuthTokens.Basic(dbUser, dbPassword));
await driver.VerifyConnectivityAsync();
Console.WriteLine("Connection established.");

Aura 实例在概念上与其他任何 Neo4j 实例没有区别，因为 Aura 只是 Neo4j 的一种部署模式。当通过驱动程序与 Neo4j 数据库交互时，无论它是否为 Aura 实例或其他部署方式，都没有区别。

连接到集群

使用 Neo4j 集群时，根据其部署方式，您有几种连接选项。

连接后，驱动程序会获取一个路由表，其中包含有关集群中所有机器（包括其角色）的信息，并将根据需要将请求指向主节点或从节点。路由表会定期刷新。

如果集群成员均可通过提供多个 A/AAAA 记录的主机名进行发现，则可以使用该主机名和端口。

如果已知集群成员的地址，但它们未通过 A/AAAA 记录发布，则可以使用自定义地址解析器在客户端扩展 DNS 解析。

using Neo4j.Driver;

const string dbUser = "<username>";
const string dbPassword = "<password>";

var addresses = new ListAddressResolver(
    ServerAddress.From("server01.example.com", 7687),
    ServerAddress.From("server02.example.com", 7687),
    ServerAddress.From("server03.example.com", 7687),
    ServerAddress.From("backup.example.org", 7687)
);

await using var driver = GraphDatabase.Driver(
    "neo4j://example.com:7687",
    AuthTokens.Basic(dbUser, dbPassword),
    conf => conf.WithResolver(addresses)
);
await driver.VerifyConnectivityAsync();

class ListAddressResolver : IServerAddressResolver {
    private readonly ServerAddress[] _servers;

    public ListAddressResolver(params ServerAddress[] servers) {
        _servers = servers;
    }

    public ISet<ServerAddress> Resolve(ServerAddress address) {
        return new HashSet<ServerAddress>(_servers);
    }
}

您也可以使用属于集群的任何机器的地址：驱动程序会自动发现其他机器。这是容错性最低的选项，因为如果您用作入口点的机器变得不可用，驱动程序将无法获取路由表。

您还可以绕过路由表，使用其地址以及 bolt[+s[sc]]:// 方案连接到集群中的特定机器（有关更多信息，请参阅连接 URI）。

关闭连接

请务必关闭 IDriver 对象以释放所有已分配的资源，即使在连接失败或发生运行时错误时也是如此。您可以通过 using 关键字创建 IDriver 对象，或者显式调用 Driver.DisposeAsync() 方法。

其他连接参数

有关更多 IDriver 配置参数和进一步的连接设置，请参阅高级连接信息。

术语表

LTS (长期支持版): 长期支持 (Long Term Support) 版本是保证在若干年内得到支持的版本。Neo4j 4.4 和 5.26 是 LTS 版本。
Aura: Aura 是 Neo4j 的全托管云服务。它提供免费和付费计划。
Cypher: Cypher 是 Neo4j 的图查询语言，允许您从数据库中检索数据。它就像 SQL，但专用于图数据库。
APOC: Awesome Procedures On Cypher (APOC) 是一个包含（许多）函数的库，这些函数在 Cypher 本身中难以轻松实现。
Bolt: Bolt 是用于 Neo4j 实例和驱动程序之间交互的协议。默认监听 7687 端口。
ACID: 原子性 (Atomicity)、一致性 (Consistency)、隔离性 (Isolation)、持久性 (Durability) (ACID) 是保证数据库事务可靠处理的属性。符合 ACID 的 DBMS 确保即使发生故障，数据库中的数据也能保持准确和一致。
最终一致性: 如果一个数据库能保证所有集群成员在某个时间点都存储了数据的最新版本，则该数据库具有最终一致性。
因果一致性: 如果读写查询被集群中的每个成员以相同的顺序看到，则数据库具有因果一致性。这比最终一致性更强。
NULL: 空标记不是一种类型，而是缺失值的占位符。更多信息，请参阅 Cypher → 使用 null。
事务: 事务是一个工作单元，要么被提交，要么在失败时被回滚。例如银行转账：它涉及多个步骤，但它们必须全部成功或全部撤销，以避免钱从一个账户扣除却未存入另一个账户的情况。
背压: 背压是对数据流的抵抗力。它确保客户端不会被过快发送的数据压垮，从而超出其处理能力。
书签: 书签是代表数据库某种状态的标记。通过将一个或多个书签与查询一起传递，服务器将确保在所表示的状态建立之前，该查询不会被执行。
事务函数: 事务函数是由 .ExecuteReadAsync() 或 .ExecuteWriteAsync() 调用执行的回调。如果服务器发生故障，驱动程序会自动重新执行回调。
IDriver: IDriver 对象保存了与 Neo4j 数据库建立连接所需的详细信息。