Create a child instance

Preview

This feature is in Public Preview in the following regions: us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-southeast-2, eu-central-1, us-east-2, ap-south-1.

This page explains how to create a child instance from an existing Lakebase database 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 retention window.

A retention window specifies the time range for which you can perform point-in-time recovery. You can create a child instance at any point within this retention window, without waiting for manual snapshots or full database exports. The child instance contains the data as it existed at the specified point in time.

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 retention 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.

Step 1: Configure the retention window on a database instance

The valid values for the retention window are between two and 35 days, inclusive. The default window is seven days. You can specify the retention window on a database instance during the instance creation. See Create a database instance.

You can modify a database instance's retention window by updating the database instance. Use the UI or API to perform the following steps:

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 retention window.
6. Click Save.

curl

Bash

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

You can create a child instance from an existing database instance. You can manage a child instance as you would a regular database instance. See Create and manage a database instance.

UI

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

• 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 retention 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 retention 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. See Postgres documentation.

curl

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

Bash

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.

Bash

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.

Bash

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_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.