def init(dbzero_root: str, **kwargs)

Initializes the dbzero environment in a specified directory and applies global configurations.

This function must be called once per process before interacting with any data. If you need to switch to a different database directory, you should first call dbzero.close() and then dbzero.init() again with the new path.

Parameters

• dbzero_root str
  The path to dbzero data files directory. If the directory doesn't exist, it will be created.

• **kwargs dict
  Additional keyword arguments:

  • prefix (str): Shortcut to open a prefix after initialization.
  • read_write (bool): Set the open mode for the prefix. Defaults to True.

  Configure global dbzero behavior:

  • restricted (bool): Restrict memo reflection access for future opened prefixes. Defaults to False. Introduced in dbzero 0.4.1.
  • restricted_context (ContextVar): Dynamically restrict memo reflection access for future opened prefixes based on a context variable's current value. Introduced in dbzero 0.4.2.
  • autocommit (bool): Enable automatic commits. Defaults to True.
  • autocommit_interval (int): Commit interval in milliseconds. Defaults to 250.
  • cache_size (int): Main object cache size in bytes. Defaults to 2 GiB.
  • lang_cache_size (int): Language model data cache size. Defaults to 1024.
  • lock_flags (dict): Configure locking behavior when opening the prefix in read-write mode.
  • data_masking (dict): dbzero-procommercial edition Activate protected-field data masking for memo classes declared with protect_fields=True.
  • data_filter (dict): dbzero-procommercial edition Activate data filtering predicates for memo classes declared with access_control=True.

  Lock flags (dict):

  • blocking (bool): Wait when trying to acquire the lock. Defaults to False.
  • timeout (int): Maximum waiting time in seconds when blocking wait is enabled.
  • force_unlock (bool): Force unlocking of existing lock. Defaults to False.

Returns

This method does not return any value.

Examples

Basic Initialization

This is the simplest way to get started. Dbzero will use the default configuration.

import dbzero as db0
import shutil
 
DB0_DIR = "/tmp/my-app-db"
 
# Clean up previous runs for the example
shutil.rmtree(DB0_DIR, ignore_errors=True)
 
# Initialize the dbzero environment in the specified directory
db0.init(DB0_DIR)
 
print(f"dbzero initialized in {DB0_DIR}")
# Now you can open a prefix and use the database
# ...
db0.close()

Initialization with Custom Configuration

You can tune performance by providing a config dictionary. Here, we disable autocommit and increase the interval.

import dbzero as db0
import shutil
 
DB0_DIR = "/tmp/my-app-db"
shutil.rmtree(DB0_DIR, ignore_errors=True)
 
# Define custom configuration
my_config = {
    "autocommit": False,
    "autocommit_interval": 1000, # 1 second
    "cache_size": 1 << 30 # 1 GiB
}
 
# Initialize with the custom config
db0.init(DB0_DIR, config=my_config)
 
# Verify the config was applied
cfg = db0.get_config()
assert cfg['autocommit'] is False
assert cfg['autocommit_interval'] == 1000
 
print("dbzero initialized with custom settings.")
# ...
db0.close()

Restricted Mode for Agent Workspaces

Restricted mode is available in the standard dbzero package starting with 0.4.1. It is designed for sandboxing code that should work with memo objects through their normal public API without reflecting on dbzero or Python metadata.

Passing restricted=True to db0.init() makes restricted mode the default for prefixes opened later, including prefixes auto-opened by dbzero in read-only mode. You can inspect this default with db0.get_config()["restricted"].

import dbzero as db0
 
db0.init("/var/lib/my-agent/dbzero", prefix="agent-memory", restricted=True)
 
assert db0.get_config()["restricted"] is True
assert db0.get_prefix_stats("agent-memory")["restricted"] is True

If one prefix in the same process must remain unrestricted, open it explicitly with restricted=False:

db0.open("host-admin-data", "rw", restricted=False)
assert db0.get_prefix_stats("host-admin-data")["restricted"] is False

Starting with dbzero 0.4.2, pass restricted_context when restricted mode should be controlled dynamically by a contextvars.ContextVar:

from contextvars import ContextVar
import dbzero as db0
 
agent_restricted = ContextVar("agent_restricted", default=False)
 
db0.init("/var/lib/my-agent/dbzero", restricted_context=agent_restricted)
db0.open("agent-memory")
 
# False means normal memo reflection access is available.
assert agent_restricted.get() is False
 
token = agent_restricted.set(True)
try:
    # Memo reflection access is restricted in this context.
    run_agent_tool()
finally:
    agent_restricted.reset(token)

db0.get_config()["restricted"] reports the static restricted=True default. It does not report the current value of a dynamic restricted context.

See Security for a practical AI-agent sandboxing guide.

Activating Protected-Field Data Masking

Protected memo fields require data masking to be initialized for the process. Pass a data_masking mapping to db0.init():

from contextvars import ContextVar
import dbzero as db0
 
account_id = ContextVar("account_id")
 
db0.init(
    "/tmp/my-secure-db",
    prefix="main",
    data_masking={
        "context_var": account_id,
        "prefix": "main",
        "missing_value_placeholder": None,
    },
)

The data_masking mapping accepts context_var, optional prefix, optional missing_value_placeholder, and optional mode. See Security for the protected-field workflow.

Activating Data Filtering Predicates

Access-controlled memo objects require data filtering to be initialized for the process. Pass a data_filter mapping to db0.init():

from contextvars import ContextVar
import dbzero as db0
 
filter_predicate = ContextVar("filter_predicate")
 
db0.init(
    "/tmp/my-secure-db",
    prefix="main",
    data_filter={
        "context_var": filter_predicate,
        "prefix": "main",
    },
)

The data_filter mapping accepts context_var, optional prefix, and optional mode. Set the context variable to a db0.predicate(...) before accessing data protected by @db0.memo(access_control=True). See Security for row-level security examples.