Create a child instance

This page explains how to create a child instance from an existing Lakebase database instance.

What is a child instance?

A child instance is a copy-on-write clone of the original database instance. It can be created from the current point in time or from a historical point-in-time within the restore window. A restore window specifies the time range (2-35 days) from which you can perform point-in-time recovery. The restore window is defined when creating a database instance. You can create a child instance at any point within this restore window, without waiting for manual snapshots or full database exports.

After you create a child instance, it is available for query until it is deleted. There is no automatic expiration tied to the parent’s restore window. This ensures you always have access to the point-in-time data at which the child instance was created, even if the parent’s restore window has expired.

Child instances are isolated from the parent. Any reads or writes you perform on a child instance have no effect on the source instance. Modifications made on a child instance uses copy-on-write so the changes are stored as a “delta”. This keeps unmodified data shared and minimizes extra storage.

When should you create a child instance?

Creating a child instance is useful in the following scenarios:

• Accidental data loss recovery: If a critical table was dropped at 10:23 AM yesterday, you could spawn a child instance set to 10:22 AM to extract only the missing data and merge it back.
• Test and QA environments: Clone a production-like environment from any point in the last X days (as defined by your restore window) to validate schema changes or run integration tests.
• Compliance and auditing: Provision a child instance reflecting the database state at a past date for internal audits, financial reconciliations, or forensic analysis.

Create a child instance from a parent database instance

To create a child database instance from a parent, configure the restore window on the parent instance to define the available timeframe for data recovery. Then, you can create a child instance by specifying your preferred restore point.

Step 1: Configure the restore window on a parent database instance

Valid values for the restore window are between 2 to 35 days, inclusive. The default window is 7 days. You can specify the restore window on a database instance when you create the instance. See Create a database instance.

Use the UI or API to modify the restore window of a database instance:

UI

1. Click Compute in the workspace sidebar.
2. Click the Database instances tab.
3. Select the database instance you want to update.
4. Click Edit in the upper-right corner.
5. Under Restore window (days), set the number of days for the restore window.
6. Click Save.

curl

curl -s -X PATCH --header "Authorization: Bearer ${DATABRICKS_TOKEN}" $DBR_URL/database/instances/my-instance -d '{"retention_window_in_days": 14}'

Step 2: Create a child instance

A child instance’s roles and permissions are the same as the parent's at the chosen restore point. This might lead to users having privileges that don't match the currently granted privileges on parent instance. View Azure Databricks identity roles and revoke any outdated privileges on the child instance.

Create a child instance by enabling Create from parent during regular database instance creation. See Create and manage a database instance.

UI

With Create from parent enabled, there are two additional parameters to specify:

• Parent Instance Name: The name of the parent instance you want to create a child database from.
• Include data from parent up to: The specific historic point in time you want data from.
  • Current point-in-time: This creates a child instance with the most recent data from a database instance.
  • Specific date and time: This creates a child instance at a specific point in time within the restore window of a database instance. The child instance contains all the data at that particular point in time.
  • Specific Log Sequence Number: Creates a child instance from a particular write-ahead-log (WAL) log sequence number (LSN) in the restore window. PostgreSQL uses WAL to support recovery and assigns an LSN to each WAL record. The child instance contains all the data at that WAL LSN. For more about WALs, see WAL internals. To obtain the current LSN value, see Backup control functions.

curl

Create a child instance using the most recent data from a database instance.

curl -s -X POST --header "Authorization: Bearer ${DATABRICKS_TOKEN}" $DBR_URL/database/instances -d '{"name": "test", "capacity": "CU_2", "parent_instance_ref": {"name": "test-child"}}'

Create a child instance with data from a specific date and time, specified in UTC.

curl -s -X POST --header "Authorization: Bearer ${DATABRICKS_TOKEN}" $DBR_URL/database/instances -d '{"name": "test", "capacity": "CU_2", "parent_instance_ref": {"name": "test-child", "branch_timestamp":"2025-05-23T17:21:00Z"}}'

Create a child instance with data from a specific WAL LSN of a database instance.

curl -s -X POST --header "Authorization: Bearer ${DATABRICKS_TOKEN}" $DBR_URL/database/instances -d '{"name": "test", "capacity": "CU_2", "parent_instance_ref": {"name": "test-child", "lsn":"0/2A156E"}}'

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.database import DatabaseInstance

# Initialize the Workspace client
w = WorkspaceClient()

parent_instance_name = "test-child"
instance_name = "test"

# Create a child instance using the most recent data from a database instance.
instance = w.database.create_database_instance(
    DatabaseInstance(
        name="my-database-instance",
        capacity="CU_1",
        parent_instance_ref={
            "name": parent_instance_name
        }
    )
)

# Create a child instance with data from a specific date and time, specified in UTC.
instance = w.database.create_database_instance(
    DatabaseInstance(
        name=instance_name,
        capacity="CU_1",
        parent_instance_ref={
            "name": parent_instance_name,
            "branch_timestamp": "2025-05-23T17:21:00Z"
        }
    )
)

# Create a child instance with data from a specific WAL LSN of a database instance.
instance = w.database.create_database_instance(
    DatabaseInstance(
        name=instance_name,
        capacity="CU_1",
        parent_instance_ref={
            "name": parent_instance_name,
            "lsn": "0/2A156E"
        }
    )
)

CLI

# Create a database instance from the most recent data of a parent instance
databricks database create-database-instance my-database-instance \
  --capacity CU_1 \
  --parent-instance-ref '{"name": "my-parent-instance"}'

# Create a database instance from a specific date and time, specified in UTC
databricks database create-database-instance \
  --json '{
    "name": "my-database-instance",
    "capacity": "CU_2",
    "parent_instance_ref": {
      "name": "my-parent-instance",
      "branch_timestamp": "2025-05-23T17:21:00Z"
    }
  }'

# Create a database instance from a specific WAL LSN of a parent instance
databricks database create-database-instance \
  --json '{
    "name": "my-database-instance",
    "capacity": "CU_2",
    "parent_instance_ref": {
      "name": "my-parent-instance",
      "lsn": "0/2A156E"
    }
  }'

Limitations

• Only one child instance can be created at a time for a database instance.
• Parent instances cannot be deleted unless the child instance is deleted.
• Child instances are designed for short-term testing or recovery. Heavy modifications on the child or parent can cause the system to reduce data sharing and maintain a full copy for the child. Storage usage and cost can grow to match that of a standalone database instance.