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:

  • 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()

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.