def open(prefix_name: str, open_mode: str = "rw", **kwargs)

Opens a data partition, known as a prefix, and sets it as the current working context.

This function is the primary way to access a specific dataset within the dbzero environment. After a prefix is opened, all subsequent object creations and lookups by default (that don't specify another prefix) will occur within it.

Parameters

• prefix_name str
  The unique name for the data partition you want to open.

• open_mode {"rw", "r"}, default "rw" : str
  The mode for opening the prefix. Defaults to "rw".

  • "rw": Read-write mode. Allows both reading and modifying objects within the prefix.
  • "r": Read-only mode. Prevents any changes to the data. This is useful for preventing accidental modifications or for client applications that only need to consume data.

• **kwargs dict
  Additional keyword arguments to configure the prefix's behavior:

  • autocommit (bool): Set to False to disable automatic commits for this specific prefix. By default, it uses the global autocommit setting configured during dbzero.init().
  • restricted (bool): Restrict memo reflection access for this prefix. Defaults to the workspace setting from db0.init(..., restricted=...). Introduced in dbzero 0.4.1.
  • restricted_context (ContextVar): Dynamically restrict memo reflection access for this prefix based on a context variable's current value. Defaults to the workspace setting from db0.init(..., restricted_context=...). Introduced in dbzero 0.4.2.
  • slab_size (int): Specifies the size (in bytes) of the memory slab to allocate for this prefix's data. Useful for performance tuning.
  • meta_io_step_size (int): Configures the chunk size for metadata I/O operations, which can impact performance for certain workloads.
  • lock_flags (dict): Configure locking behavior when opening the prefix in read-write mode.

Returns

This method does not return any value.

Examples

Basic Usage

Open a prefix in the default read-write mode. This becomes the current active prefix.

# Initialize dbzero first
db0.init("app-data")
 
# Open a prefix for read-write access
db0.open("user-profiles")
 
# Now you can work with objects in the "user-profiles" prefix
user = UserProfile(name="Alex")

Opening in Read-Only Mode

Open a prefix for safe, read-only access. This is ideal for analytics or recovery operations.

# Open the same prefix, but only for reading
db0.open("user-profiles", "r")
 
# This will succeed
alex = next(iter(db0.find(UserProfile, "Alex")))
 
# This will raise an error because the prefix is read-only
alex.last_login = datetime.now()
db0.commit()

Customizing Prefix Settings

You can override global configurations on a per-prefix basis. Here, we disable autocommit for a specific prefix that requires manual transaction control.

# Open a prefix and disable autocommit just for it
db0.open("transaction-logs", autocommit=False)
 
# Changes made here won't be saved until you manually call db0.commit()
log_entry = Log(message="User action")
 
# No autocommit happens here
time.sleep(1)
 
# Manually commit the changes
db0.commit()

Opening a Restricted Prefix

Restricted mode is available in the standard dbzero package starting with 0.4.1. It is useful when a prefix is used by AI agents, plugins, or other code that should interact with memo objects through public fields and public methods without reflecting on metadata such as __class__, __dict__, method __self__, or method __globals__.

db0.init("app-data")
 
# The agent can read and write normal memo fields on this writable prefix,
# but memo reflection access is restricted.
db0.open("agent-memory", "rw", restricted=True)
 
assert db0.get_prefix_stats("agent-memory")["restricted"] is True

Restriction is scoped to the opened prefix. If the workspace default was set with db0.init(..., restricted=True), pass restricted=False to keep a specific prefix unrestricted:

db0.init("app-data", restricted=True)
db0.open("host-admin-data", "rw", restricted=False)

You can also combine restricted mode with read-only access:

db0.open("shared-knowledge", "r", restricted=True)

Opening a Dynamically Restricted Prefix

Starting with dbzero 0.4.2, pass restricted_context when a prefix should be restricted only in selected execution contexts:

from contextvars import ContextVar
import dbzero as db0
 
agent_restricted = ContextVar("agent_restricted", default=False)
 
db0.init("app-data")
db0.open("agent-memory", "rw", restricted_context=agent_restricted)
 
# False or unset context values leave memo reflection unrestricted.
assert agent_restricted.get() is False
 
token = agent_restricted.set(True)
try:
    # Memo reflection access is restricted while this value is truthy.
    run_agent_tool()
finally:
    agent_restricted.reset(token)

A prefix-level restricted_context overrides a workspace-level restricted context for that prefix. Restriction changes are monotonic for an already-open prefix: unrestricted can become dynamically restricted, and dynamically restricted can become statically restricted. Static restricted mode cannot be converted to context-controlled mode or weakened.