Sign up

Python Client — Quickstart

Open inAnthropic

This guide uses Python. Also available in TypeScript · Rust

Prerequisites

If you haven't run the curl quickstart yet, do that first — it takes 5 minutes and introduces the branch/diff/merge concepts this guide builds on.

TerminusDB must be running

This guide assumes TerminusDB is running on localhost:6363. If you have trouble connecting, see Troubleshooting Connection Failures and Authentication Errors.

Install the client

Example: Bash
pip install terminusdb-client

Create a file called quickstart.py. You will build it up step by step below.

Connect to TerminusDB

PYTHON
Run locally
import os
from terminusdb_client import Client

client = Client(os.environ.get("TERMINUSDB_URL", "http://localhost:6363"))
client.connect(
    team=os.environ.get("TERMINUSDB_USER", "admin"),
    key=os.environ.get("TERMINUSDB_KEY", "root"),
)

info = client.info()
print("Connected to TerminusDB", info)

What you should see: A dict with server version and storage details. If you see a connection error, check that Docker is running and TerminusDB is on port 6363.

Create a database and insert a document

No schema needed — insert any dict with raw_json=True and give it a human-readable ID:

PYTHON
Run locally
client.create_database(db, label=db, description="Python quickstart", include_schema=False)

result = client.insert_document(
    {"@id": "terminusdb:///data/jane", "name": "Jane Smith", "email": "jane@example.com", "age": 30},
    raw_json=True,
    commit_msg="Add Jane Smith",
)

print("Document created:", result)
Run the setup example above first to create the database

What you should see: A list containing "terminusdb:///data/jane". The @id gives the document a stable, human-readable identifier. Schema comes later when you are ready.

Create a branch

Just like git branch, this creates an isolated copy of your data:

PYTHON
Run locally
# Create a new branch from the current branch (main)
client.create_branch("feature")

# Switch to it
client.branch = "feature"

print("Now on branch:", client.branch)

What you should see: Now on branch: feature

Everything you do now happens on feature — main is untouched.

Edit the document on the branch

PYTHON
Run locally
# Get the document we inserted earlier
person = client.get_document("terminusdb:///data/jane", raw_json=True)
print("Current document:", person)

# Update the email on this branch
client.replace_document(
    {"@id": "terminusdb:///data/jane", "name": "Jane Smith", "email": "jane.smith@company.com", "age": 30},
    raw_json=True,
    commit_msg="Updated Jane's email",
)

print("Document updated on feature branch")

What you should see: The document retrieved, then confirmation of the update. The change only exists on feature — main still has the original email.

See the diff

This is the moment. TerminusDB can show you exactly what changed between branches — structurally, field by field:

PYTHON
Run locally
# Compare main to feature — what changed?
diff = client.diff_version("main", "feature")

print("Changes between main and feature:")
print(json.dumps(diff, indent=2))

What you should see:

Example: JSON
[
  {
    "@id": "terminusdb:///data/jane",
    "email": { "@op": "SwapValue", "@before": "jane@example.com", "@after": "jane.smith@company.com" }
  }
]

What just happened? TerminusDB computed a structural diff — not a line-by-line text diff, but a semantic operation (SwapValue) that knows exactly which field changed, what the old value was, and what the new value is. This patch can be applied, reversed, or composed with other patches.

Merge the branch

Bring the changes back to main:

PYTHON
Run locally
# Switch back to main
client.branch = "main"

# Merge feature into main (like git merge)
client.rebase(
    rebase_source=f"{team}/{db}/local/branch/feature",
    message="Merge feature: updated Jane's email",
)

print("Merged feature into main")

What you should see: Merged feature into main

Verify the merge

Confirm the changes are now on main:

PYTHON
Run locally
updated = client.get_document("terminusdb:///data/jane", raw_json=True)
print("Person on main after merge:", updated)

What you should see: Jane Smith with jane.smith@company.com — the changes from the feature branch are now on main.

What just happened?

You just used your database like a git repository:

  1. Branched — created an isolated workspace (feature) without copying data
  2. Edited — made changes that only exist on that branch
  3. Diffed — asked TerminusDB to show exactly what changed, field by field
  4. Merged — brought changes back to main cleanly

Troubleshooting

Error: Connection refused

You see:

Example: Text
requests.exceptions.ConnectionError: ... Connection refused

Cause: TerminusDB is not running, or another process is using port 6363.

Fix:

Example: Bash
# Check if the container is running
docker ps | grep terminusdb

# If not running, start it
docker start terminusdb

# If it doesn't exist, create it
docker run -d --name terminusdb -p 127.0.0.1:6363:6363 \
  -v terminusdb_storage:/app/terminusdb/storage \
  terminusdb/terminusdb-server

Troubleshooting Connection Failures →

Error: 401 Unauthorized

You see:

Example: Text
Exception: 401

or

Example: Text
DatabaseError: Unauthorized

Cause: Wrong username or password. The default local credentials are admin / root.

Fix:

# Verify credentials work
curl -u admin:root http://localhost:6363/api/info

If you set a custom password via TERMINUSDB_ADMIN_PASS when creating the container, use that value instead of root.

Troubleshooting Authentication Errors →

Error: Database does not exist (404)

You see:

Example: Text
Exception: 404 - {"@type":"api:ErrorResponse","api:error":{"@type":"api:UnresolvableAbsoluteDescriptor"}}

Cause: You are trying to read/write a database that has not been created yet, or the path is wrong.

Fix:

# List existing databases
curl -u admin:root http://localhost:6363/api/db

# Create the database if missing
curl -u admin:root -X POST "http://localhost:6363/api/db/admin/MyDatabase" \
  -H "Content-Type: application/json" \
  -d '{"label": "MyDatabase", "comment": "My database"}'

Error: ModuleNotFoundError

You see:

Example: Text
ModuleNotFoundError: No module named 'terminusdb_client'

Cause: The package is not installed, or you are using a different Python environment than the one you installed it in.

Fix:

Example: Bash
# Install the package
pip install terminusdb-client

# If you have multiple Python versions, ensure you use the right pip
python3 -m pip install terminusdb-client

# Verify it is installed
python3 -c "import terminusdb_client; print(terminusdb_client.__version__)"

Error: SSL certificate verify failed

You see:

Example: Text
requests.exceptions.SSLError: ... certificate verify failed

Cause: Your Python environment cannot verify the server's SSL certificate. This only affects cloud connections, not localhost.

Fix:

Example: Bash
# Update certificates (macOS)
pip install --upgrade certifi

Certificate Issues →

Error: Database already exists

You see:

Example: Text
Exception: Error 400 - Database already exists

Cause: You ran this quickstart before and the database still exists.

Fix:

Example: Python
client.delete_database("MyDatabase")

Next steps

If you've already run this quickstart, delete the database before running again:

Example: Python
client.delete_database("MyDatabase")
Open inAnthropic
Report issue

Was this helpful?