高级连接信息

连接 URI

驱动程序支持以下形式的连接 URI

<SCHEME>://<HOST>[:<PORT>[?policy=<POLICY-NAME>]]
  • <SCHEME>neo4j, neo4j+s, neo4j+ssc, bolt, bolt+s, bolt+ssc 中的一个。

  • <HOST> 是 Neo4j 服务器所在的主机名。

  • <PORT> 是可选的,表示 Bolt 协议可用的端口。

  • <POLICY-NAME> 是可选的 服务器策略 名称。服务器策略 需要在使用前进行设置。

驱动程序不支持连接到嵌套路径,例如 example.com/neo4j/。服务器必须可以从域名根目录访问。

连接协议和安全性

驱动程序和服务器之间的通信通过 Bolt 进行。服务器 URI 的方案决定了连接是否加密,如果加密,则决定接受哪种类型的证书。

URL 方案 加密 注释

neo4j

本地设置的默认值

neo4j+s

(仅限 CA 签名证书)

Aura 的默认值

neo4j+ssc

(CA 签名和自签名证书)

驱动程序在成功连接后会从服务器接收一个 路由表,无论实例是合适的集群环境还是单机环境。驱动程序的路由行为与 Neo4j 的集群 协同工作,将读/写事务定向到适当的集群成员。如果您想针对 特定 机器,请改用 boltbolt+sbolt+ssc URI 方案。

要使用的连接方案不是您的选择,而是由服务器要求决定的。您必须事先了解正确的服务器方案,因为在连接之前不会公开任何元数据。如果您不确定,请咨询数据库管理员。

身份验证方法

基本身份验证 (默认)

基本身份验证方案依赖于传统的用户名和密码。这些可以是您本地安装的凭据,也可以是 Aura 实例提供的凭据。

from neo4j import GraphDatabase

driver = GraphDatabase.driver(URI, auth=(USERNAME, PASSWORD))

基本身份验证方案也可用于针对 LDAP 服务器进行身份验证 (仅限企业版)。

Kerberos 身份验证

Kerberos 身份验证方案需要一个 base64 编码的票据。它只能在服务器安装了 Kerberos 附加组件 的情况下使用。

from neo4j import GraphDatabase, kerberos_auth

driver = GraphDatabase.driver(URI, auth=kerberos_auth(ticket))

不记名身份验证

不记名身份验证方案需要由身份提供商通过 Neo4j 的 单点登录功能 提供一个 base64 编码的令牌。

from neo4j import GraphDatabase, bearer_auth

driver = GraphDatabase.driver(URI, auth=bearer_auth(token))
不记名身份验证方案需要在 服务器上配置单点登录。配置完成后,客户端可以通过 发现 API 发现 Neo4j 的配置。

自定义身份验证

使用函数 custom_auth 登录到具有自定义身份验证方案的服务器。

无身份验证

如果服务器上禁用了身份验证,则可以完全省略身份验证参数。

轮换身份验证令牌

可以轮换预期会过期的身份验证令牌(例如 SSO)。在实例化 Driver 时,您需要提供一个 AuthManager 实例(对于异步驱动程序,则为 AsyncAuthManager),而不是一个静态身份验证令牌。

最简单的入门方法是使用 内置的 AuthManager 实现之一

轮换每 60 秒过期一次的不记名令牌
import neo4j
from neo4j.auth_management import (
    AuthManagers,
    ExpiringAuth,
)


def auth_provider():
    # Some way to get a token
    sso_token = get_sso_token()
    # Assume we know tokens expire every 60 seconds
    expires_in = 60
    # Include a little buffer so that new token is fetched before the old one expires
    expires_in -= 10

    auth = neo4j.bearer_auth(sso_token)
    return ExpiringAuth(auth=auth).expires_in(expires_in)

with neo4j.GraphDatabase.driver(
    URI,
    auth=AuthManagers.expiration_based(auth_provider)
) as driver:
    ...
此 API 不得用于切换用户。身份验证管理器必须始终为同一身份返回令牌。您可以在 查询级别会话级别 切换用户。
AuthManagers(包括传递给 AuthManagers.expiration_based() 的提供函数)不得以任何方式与驱动程序交互,因为这可能导致死锁和未定义的行为。

相互 TLS(客户端证书作为双因素认证)

相互 TLS (mTLS) 允许您使用客户端证书作为与服务器进行身份验证的第二因素。除非服务器上禁用了身份验证,否则证书只能与身份验证令牌一起使用,不能替代常规身份验证。

客户端的证书和公钥必须放在服务器的 <NEO4J_HOME>/certificates/bolt/trusted 目录下。有关服务器设置的更多信息,请参阅 通过 Bolt 配置 SSL

为了使 mTLS 正常工作,驱动程序与服务器的连接必须加密,即 连接 URI 方案 必须是 +s+ssc(例如 neo4j+s://example.com:7687)。

对于静态证书,请使用 ClientCertificateProviders.static()
该方法接受一个 ClientCertificate 实例,该实例接受与 Python 的 ssl.SSLContext.load_cert_chain() 相同的参数。

import neo4j
from neo4j.auth_management import (
    ClientCertificate,
    ClientCertificateProviders,
)
URI = "{neo4j-database-uri}"
AUTH = ("{neo4j-username}", "{neo4j-password}")
cert_provider = ClientCertificateProviders.static(
    ClientCertificate(
        # path to certificate
        "path/to/cert.pem",
        # path to private key (optional; needed if certificate does not contain private key too)
        "path/to/key.pem",
        # password to decrypt private key (can be function or string) (optional)
        lambda: "password",
    )
)
with neo4j.GraphDatabase.driver(
    URI,
    auth=AUTH,
    client_certificate=cert_provider,
) as driver:
    ...

对于轮换证书,请使用 ClientCertificateProviders.rotating()
该方法接受一个 ClientCertificate 实例。

import neo4j
from neo4j.auth_management import (
    ClientCertificate,
    ClientCertificateProviders,
)
URI = "{neo4j-database-uri}"
AUTH = ("{neo4j-username}", "{neo4j-password}")
cert_provider = ClientCertificateProviders.rotating(
    ClientCertificate(
        # path to public certificate to load
        "path/to/cert.pem",
        # path to private key to load
        "path/to/key.pem",
        # password to decrypt private key (can be a function or string)
        # see also Python's ssl.SSLContext.load_cert_chain()
        lambda: "password",
    )
)
driver = neo4j.GraphDatabase.driver(
   URI
   auth=(USERNAME, PASSWORD),
   client_certificate=cert_provider
)
# use the driver...
# ... until the certificate needs to be rotated
cert_provider.update_certificate(
    ClientCertificate(
        certfile="path/to/new/cert.pem",
        keyfile="path/to/new/key.pem",
        password=lambda: "new_super_secret_password"
    )
)
# use the driver again, until the certificate needs to be
# rotated again
# ...

更多信息,请参阅 API 文档 → ClientCertificateProvider

自定义地址解析器

创建 Driver 对象时,您可以指定一个 解析器 函数,用于在 DNS 解析之前解析驱动程序接收到的任何地址。您的解析器函数将使用 Address 对象调用,并应返回一个 Address 对象的迭代器(或可用于构造 Address 对象的值)

连接到端口 9999 上的 example.com 被解析为端口 7687 上的 localhost
import neo4j


def custom_resolver(socket_address):
    # assert isinstance(socket_address, neo4j.Address)
    if socket_address != ("example.com", 9999):
        raise OSError(f"Unexpected socket address {socket_address!r}")

    # You can return any neo4j.Address object
    yield neo4j.Address(("localhost", 7687))  # IPv4
    yield neo4j.Address(("::1", 7687, 0, 0))  # IPv6
    yield neo4j.Address.parse("localhost:7687")
    yield neo4j.Address.parse("[::1]:7687")

    # or any tuple that can be passed to neo4j.Address().
    # This will initially be interpreted as IPv4, but DNS resolution
    # will turn it into IPv6 if appropriate.
    yield "::1", 7687
    # This will be interpreted as IPv6 directly, but DNS resolution will
    # still happen.
    yield "::1", 7687, 0, 0
    yield "127.0.0.1", 7687


driver = neo4j.GraphDatabase.driver("neo4j://example.com:9999",
                                    auth=(USERNAME, PASSWORD),
                                    resolver=custom_resolver)

更多连接参数

您可以在 API 文档 中找到所有 Driver 配置参数。

术语表

LTS

长期支持 (LTS) 版本是保证多年提供支持的版本。Neo4j 4.4 是 LTS 版本,Neo4j 5 也将有一个 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

事务

事务是工作的一个单元,它要么全部 提交,要么在失败时 回滚。一个例子是银行转账:它涉及多个步骤,但它们必须 全部 成功或被还原,以避免资金从一个账户中扣除但未添加到另一个账户的情况。

背压

背压是阻碍数据流动的力。它确保客户端不会被比其处理能力更快的数据所淹没。

事务函数

事务函数是由 execute_readexecute_write 调用执行的回调。在服务器故障时,驱动程序会自动重新执行该回调。

驱动程序

一个 Driver 对象包含与 Neo4j 数据库建立连接所需的详细信息。

© . All rights reserved.