def copy_prefix(file_name: str, prefix: Optional[str], page_io_step_size: Optional[int])

The copy_prefix function creates a consistent snapshot copy of a dbzero prefix to a file. This is useful for creating backups or migrating data. If the copy suceeds the result file can be used to restore the contents of the prefix by simply replacing the original file with the copy.

Parameters

• file_name str
  The destination file path where the prefix copy will be saved. The file will be created if it doesn't exist.

• prefix str, optional
  The name of the prefix to copy. If omitted, copies the current prefix. If provided, the prefix doesn't need to be opened first, but it must exist in the dbzero repository (i.e. inside the dbzero_root directory).

• page_io_step_size int, optional
  The size (in bytes) of data chunks used during the copy operation. The default value is 4MiB.

Returns

This method does not return any value.

Raises

• RuntimeError
  Raised when no prefix is currently open and no prefix parameter is provided.

Examples

Basic Usage

Copy the currently open prefix to a file.

import dbzero as db0 as db0
 
# Initialize and open a prefix
db0.init("/path/to/db")
db0.open("my_prefix", "rw")
 
# Create and modify some data
root = MySingleton([])
for i in range(100):
    root.items.append(MyObject(f"data_{i}"))
db0.commit()
 
# Create a backup copy
db0.copy_prefix("/my_backup_dir/backup.db0")

Copy a Specific Prefix Without Opening It

Copy any existing prefix by name without needing to open it first.

import dbzero as db0 as db0
 
# Initialize database
db0.init("/path/to/db")
 
# Copy a specific prefix without opening it
db0.copy_prefix("./archive.db0", prefix="old_data")

Restore from a Copy

Replace the original prefix file with a copy to recover from a backup.

import dbzero as db0 as db0
import os
 
# Get the current prefix info
px_name = db0.get_current_prefix().name
px_path = os.path.join("/path/to/db", px_name + ".db0")
 
# Create a copy
db0.copy_prefix("/my_backup_dir/backup.db0")
db0.close()
 
# Replace original with the copy
os.remove(px_path)
os.rename("/my_backup_dir/backup.db0", px_path)
 
# Reopen the restored prefix
db0.init("/path/to/db", prefix=px_name, read_write=False)
root = db0.fetch(MySingleton)
# Data is now restored from the backup

Use Cases

• Backup and Recovery: Create point-in-time backups of your database that can be restored later
• Data Migration: Export prefix data to move between systems or environments
• Testing: Create copies of production data for testing purposes
• Replication: Distribute copies to multiple systems

Notes

• The copy operation creates a consistent snapshot, even if the prefix is being modified concurrently
• The copied file can be used as a standalone prefix by renaming it appropriately and opening it with db0.init()
• Modified copies can be further copied, maintaining data consistency
• The operation is safe for concurrent reading and writing scenarios