Schema-only branches

Neon supports creating schema-only branches, letting you create branches that replicate only the database schema from a source branch — without copying any of the actual data. This feature is ideal for working with confidential information. Instead of duplicating this sensitive data, you can now create a branch with just the database structure and populate it with randomized or anonymized data instead. This provides your team with a secure and compliant environment for developing and testing using Neon branches.

Creating schema-only branches

You can create schema-only branches in the Neon Console or using the Neon API, in much the same way you create any Neon branch. Support for the Neon CLI will come in a future release.

Neon ConsoleAPI

To create a schema-only branch from the Neon Console:

1. In the console, select your project.
2. Select Branches.
3. Click Create branch to open the branch creation dialog.
4. Under Include, Select the Schema-only option.
5. Provide a name for the branch.
6. In the From Branch field, select the source branch. The schema from the source branch will be copied to your new schema-only branch.
7. Click Create branch.

Schema-only branching example

To try out schema-only branches:

1. Start by creating an employees table on your Neon project's main branch and adding some dummy data. You can do this from the Neon SQL Editor or any SQL client by copying and pasting the following statements:

   CREATE TABLE employees (
       employee_id SERIAL PRIMARY KEY,
       first_name VARCHAR(50),
       last_name VARCHAR(50),
       email VARCHAR(100),
       phone_number VARCHAR(15),
       job_title VARCHAR(50),
       salary NUMERIC(10, 2),
       hire_date DATE
   );
   
   INSERT INTO employees (first_name, last_name, email, phone_number, job_title, salary, hire_date) VALUES
   ('John', 'Doe', 'john.doe@example.com', '123-456-7890', 'Software Engineer', 95000.00, '2020-01-15'),
   ('Jane', 'Smith', 'jane.smith@example.com', '987-654-3210', 'Product Manager', 110000.00, '2019-03-22'),
   ('Alice', 'Johnson', 'alice.johnson@example.com', '555-123-4567', 'HR Specialist', 65000.00, '2021-06-10'),
   ('Bob', 'Brown', 'bob.brown@example.com', '555-987-6543', 'Data Analyst', 78000.00, '2018-09-05'),
   ('Charlie', 'Davis', 'charlie.davis@example.com', '444-555-6666', 'Marketing Manager', 95000.00, '2017-11-14'),
   ('Diana', 'Miller', 'diana.miller@example.com', '333-444-5555', 'Sales Representative', 72000.00, '2022-04-18'),
   ('Edward', 'Wilson', 'edward.wilson@example.com', '222-333-4444', 'DevOps Engineer', 98000.00, '2020-12-03'),
   ('Fiona', 'Clark', 'fiona.clark@example.com', '111-222-3333', 'UI/UX Designer', 85000.00, '2016-08-29'),
   ('George', 'Harris', 'george.harris@example.com', '999-888-7777', 'Financial Analyst', 90000.00, '2021-01-11'),
   ('Hannah', 'Martin', 'hannah.martin@example.com', '888-777-6666', 'Backend Developer', 92000.00, '2019-07-23');

2. Navigate to the Tables page in the Neon Console, and select your main branch from the bread-crumb menu at the top of the console. Your employees table will have both schema and data, as shown here:

   

3. Create a schema-only branch following the instructions above. See Creating schema-only branches. In this example, we've named the branch employees_schema_only.

   

4. On the Tables page, select your newly created employees_schema_only branch from the bread-crumb menu at the top of the console. You can see that the schema-only branch contains the schema, but no data. The same will be true for any table in any database on the schema-only branch — only the schema will be present.

   

Connect to a schema-only branch

Connecting to a schema-only branch works the same way as connecting to any Neon branch. You'll connect via a compute associated with the branch. Follow these steps to connect using psql and a connection string obtained from the Neon Console.

1. In the Neon Console, select a project.

2. On the project Dashboard, under Connection Details, select your schema-only branch, the database, and the role you want to connect with.

3. Copy the connection string. A connection string includes your role name, the compute hostname, and the database name.

   postgresql://[user]:[password]@[neon_hostname]/[dbname]

What's different about schema-only branches?

Unlike other branches, schema-only branches do not have a parent branch, as you can see below. Both the main branch of the project and the schema-only branch have no parent, indicated by the dash in the Parent column (-) on the Branches page in your Neon project.

Schema-only branches are independent root branches, just like the main branch in your Neon project. When you create a schema-only branch, you’re creating a new root branch.

Key points about schema-only branches

• No parent branch: Schema-only branches are root branches. They do not have a parent branch.
• No shared history: Data added to a schema-only branch is independent and adds to your storage. There is no shared history with a parent.
• Reset from parent is not supported: With no parent branch, reset from parent operations are not supported.
• Restore is supported, but... performing a restore operation on a schema-only branch copies both schema and data from the source branch.
• Branch protection is supported: Like any other branch, you can enable branch protection for schema-only branches.

Schema-only branch allowances

There are certain allowances associated with schema-only branches:

• A schema-only branch is a root branch, and there is only a certain number of root branches permitted per Neon project, depending on your Neon plan.
• The main root branch created with each Neon project counts toward the root branch allowance per project, as do certain backup branches created by restore operations.
• There is a storage allowance for schema-only branches. The storage allowances do not apply when restoring data to a schema-only branch from another branch.

Limitations

Schema-only branches are not supported with experimental extensions that require enabling the neon.allow_unstable_extensions setting, such as the pg_mooncake extension. You can expect this limitation to be lifted in a future release.