NebulaGraph Python Client

3.8.3 verified Sat May 09 auth: no python

Python client library for NebulaGraph v3.x graph database. Current version 3.8.3 on PyPI, but the 5.x series (v5.2.2) is the new generation with async-native client, connection/session pools, and ORM. The v3.x line is stable and still maintained for legacy NebulaGraph v3 deployments.

pip install nebula3-python

Common errors

error nebula3.gclient.net.ConnectionPool.init() takes 2 positional arguments but 3 were given ↓

cause Passing config as a separate argument instead of as keyword argument.

fix

Use: pool.init(addresses, config) where config is a Config object, not a dict.

error AttributeError: module 'nebula3' has no attribute 'ConnectionPool' ↓

cause Incorrect import path. This is typically because one uses 'import nebula3' instead of 'from nebula3.gclient.net import ConnectionPool'.

fix

Use: from nebula3.gclient.net import ConnectionPool

error nebula3.common.AuthError: Authentication failed ↓

cause Incorrect username or password, or using root with a password when no password is set.

fix

Set NEBULA_USER and NEBULA_PASSWORD environment variables, or use default (root/nebula). Verify credentials in NebulaGraph.

Warnings

breaking NebulaGraph v5.x is not compatible with nebula3-python. Use nebula3-python>=5.0.0 for v5.x and nebula3-python<5 for v3.x. ↓

fix Match client major version to server major version: v3 client for v3 server, v5 client for v5 server.

gotcha The 'SessionPool' class was introduced in v3.8.0 but is only stable when using TLS (v3.8.2+). Without TLS, connections may leak. Use 'ConnectionPool' with explicit session management as a safe fallback. ↓

fix Upgrade to v3.8.2 or later, or avoid SessionPool and manage sessions manually with ConnectionPool.

gotcha The 'Node.tags()' method returns a list of tag names, not a list of tag values. This changed in v3.8.0; prior versions returned tag values. If you depend on tag values, use 'Node.properties()' or 'Node.values()'. ↓

fix Use 'node.properties()' or 'node.values()' to get actual data instead of tag names.

deprecated The 'nebula3.gclient.net.Session.execute_json()' method is deprecated in v3.8.3. Use 'session.execute()' and parse the ResultSet instead. ↓

fix Replace session.execute_json(query) with session.execute(query) and handle ResultSet as_dict() or as_primitive().

Install

pip install 'nebula3-python>=5.0.0'

Imports

ConnectionPool

wrong

from nebula3_python import ConnectionPool

correct

from nebula3.gclient.net import ConnectionPool

The package is imported as 'nebula3' not 'nebula3_python'

Session

wrong

from nebula3_python import Session

correct

from nebula3.gclient.net import Session

Session is in the gclient.net submodule

AuthResult

wrong

from nebula3_python.common import AuthResult

correct

from nebula3.common import AuthResult

Correct module path uses 'common' not 'gclient'

SSLContext
wrong
```
from nebula3.settings import SSLContext
```
correct
```
from nebula3.gclient.net import SSLContext
```
SSL support is only available in v3.8.2+ and imported from gclient.net

Quickstart

Initialize a connection pool, get a session, execute a simple query, and release resources.

import os
from nebula3.gclient.net import ConnectionPool
from nebula3.Config import Config

config = Config()
config.max_connection_pool_size = 10

pool = ConnectionPool()
addresses = [("127.0.0.1", 9669)]
user = os.environ.get('NEBULA_USER', 'root')
password = os.environ.get('NEBULA_PASSWORD', 'nebula')

if not pool.init(addresses, config):
    raise Exception("Connection pool initialization failed")

session = pool.get_session(user, password)
result = session.execute('SHOW SPACES;')
print(result)
session.release()
pool.close()