Build a Streamhouse with a Blueprint on Confluent Cloud

A Blueprint is a ready-made plan for one Streamhouse use case. Each Blueprint combines a Terraform template that builds the architecture with a form in Confluent Cloud Console that provisions and verifies the resources for you. Each Blueprint is based on a reference architecture, which is the diagram and guidance for the use case.

The Customer 360 Blueprint is the Blueprint for the Unify customer decisions use case. With it, Confluent Cloud Console provisions a pipeline from your PostgreSQL database to Iceberg tables and verifies that data arrives.

You find Blueprints on the Explore Streamhouse page in Confluent Cloud Console. The page shows four Streamhouse examples:

Unify customer decisions offers the Customer 360 Blueprint. Click Build with blueprint to start it.
Give AI agents live context offers a Terraform template. Click Download Terraform to get it.
Catch fraud before the payment clears and Send decisions where customers can act show reference architectures only.

This page shows how to build a Streamhouse with the Customer 360 Blueprint. The Blueprint captures changes from tables in your PostgreSQL database, keeps the latest state of every row with Confluent Cloud for Apache Flink, and publishes each table as an Iceberg table with Tableflow.

The resources that the Blueprint creates incur Confluent Cloud charges. To stop the charges, follow the steps in Delete the resources.

What the Customer 360 Blueprint builds

The Blueprint creates a new environment and all of its resources. Every resource name starts with the name that you give your Streamhouse, shown here as <name>.

Resource	Name	Description
Environment	`<name>`	Uses the Advanced Stream Governance package.
Kafka cluster	`<name>-cluster`	A single-zone Standard cluster with public networking.
Source connector	`<name>-postgres-cdc-source`	A PostgreSQL CDC Source V2 (Debezium) connector that writes Avro records to one topic per table, named `cdc.public.<table>`. The connector creates a publication and a replication slot in your database.
Schemas	One key and one value subject per topic	Schemas that the connector infers from your tables. Each value subject uses `FULL_TRANSITIVE` compatibility.
Flink compute pool	`<name>-flink-pool`	Has a maximum of 10 Confluent Units for Flink (CFUs).
Flink statements	One per table	Each statement creates a table named `<table>_current` that holds the latest state of every row.
Tableflow tables	One per `<table>_current` topic	Iceberg tables in Confluent-managed storage.
Connector service account	`<name>-postgres-cdc-connector`	Has access control lists (ACLs) to create and write topics that start with `cdc`.
Flink service account	`<name>-flink-runner`	Runs the Flink statements, with the EnvironmentAdmin role on the environment.

Each Flink statement resembles the following. The primary key is the table’s primary key.

CREATE TABLE IF NOT EXISTS `orders_current` (
  PRIMARY KEY (`order_id`) NOT ENFORCED
) DISTRIBUTED BY (`order_id`)
WITH ('changelog.mode' = 'upsert')
AS SELECT * FROM `cdc.public.orders`;

For more information, see PostgreSQL CDC Source Connector V2 (Debezium) for Confluent Cloud, Compute Pools in Confluent Cloud for Apache Flink, and Tableflow in Confluent Cloud.

Prerequisites

The OrganizationAdmin role in your Confluent Cloud organization. If you don’t have this role, the Explore Streamhouse page shows the examples without the Build with blueprint button.
A payment method on file. Until you add one, the Blueprint form is locked. If your organization is billed through a cloud marketplace, you can provision the Blueprint only on that marketplace’s cloud provider. For more information, see Manage Billing in Confluent Cloud.
A PostgreSQL database that meets the requirements in Step 1: Prepare your PostgreSQL database.

Step 1: Prepare your PostgreSQL database

The connector reads changes from your database by using logical replication. If the database isn’t set up for it, the Blueprint run fails, so check each of the following before you start.

Confirm that logical replication is on. The following query must return logical.
```
SHOW wal_level;
```
If it returns replica or minimal, set wal_level to logical and restart the database. On AWS RDS and Aurora, set rds.logical_replication to 1 in the database’s parameter group, and then reboot the database.
Create a database user for the connector. The user needs the REPLICATION attribute, the CREATE privilege on the database, and ownership of each table that you capture, directly or through a role. The connector needs CREATE and table ownership to create its publication.

The following example creates a user named cdc_user and a role named cdc_owners that owns the tables. Replace <password>, your_database, current_table_owner, and the table names with your own values.
```
CREATE ROLE cdc_user WITH LOGIN REPLICATION PASSWORD '<password>';
GRANT CONNECT, CREATE ON DATABASE your_database TO cdc_user;
GRANT USAGE ON SCHEMA public TO cdc_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO cdc_user;

CREATE ROLE cdc_owners;
GRANT cdc_owners TO cdc_user, current_table_owner;
ALTER TABLE public.customers OWNER TO cdc_owners;
ALTER TABLE public.orders OWNER TO cdc_owners;
```
On AWS RDS and Aurora, omit REPLICATION from the CREATE ROLE statement and run GRANT rds_replication TO cdc_user; instead.
Check your tables. The Blueprint captures tables in the public schema only, and each table needs a primary key and at least one row.
Allow connections from Confluent Cloud. The database must accept connections over public networking from the egress IP addresses that Confluent Cloud uses for connectors in the region that you choose on the Blueprint form. The form lists these addresses for the selected region under Show IP addresses for <region>. Allow all of the listed addresses. For more information, see Public Egress IP Addresses for Confluent Cloud Connectors.

For more information about preparing PostgreSQL for change data capture, see PostgreSQL CDC Source V2 prerequisites.

Step 2: Open the Customer 360 Blueprint

Open the Blueprint form from the Explore Streamhouse page.

In Confluent Cloud Console, on the home page, click Explore Streamhouse.
On the Explore Streamhouse page, the Unify customer decisions example is selected. Review the reference architecture, and then click Build with blueprint.

The Build with blueprint page opens, with the Blueprint tab selected.

Step 3: Enter your Streamhouse details

On the Blueprint form, name your Streamhouse, choose the cloud provider and region where it runs, and enter the details that the connector uses to connect to your PostgreSQL database.

In Name your Streamhouse, keep the generated name or enter your own. The Blueprint uses this name as a prefix for every resource it creates. Use up to 40 lowercase letters, numbers, and hyphens, starting and ending with a letter or number.
In Select cloud provider and region, select the cloud provider, and in Region, select the region where your database runs, or the region closest to it.
Click Show IP addresses for <region>, review the egress IP addresses, and confirm that your database allows connections from all of them.
Enter the connection details for your database:
- Database hostname: The hostname only, without http://, a port, or a path. For example, db.example.com.
- Database port: The default is 5432.
- Database username and Database password: The connector user that you created when you prepared your PostgreSQL database.
- Database name: The database that contains your tables.
- Table name(s): A comma-separated list of tables in the public schema, for example, customers,orders.

The Blueprint form doesn’t save the values that you enter, including your password. If you start the Blueprint again, you enter them again. The connector that the Blueprint creates keeps the connection details in its configuration, like any connector that you create.

Step 4: Provision and verify the resources

Click Provision resources.

The Blueprint creates the resources in order and shows the status of each step. To see each API step and any errors, click Show steps.

Important

Provisioning runs in your browser tab. You can move to other pages in Confluent Cloud Console, but if you close or reload the tab, or leave Confluent Cloud Console, provisioning stops. To clean up after an interrupted run, see Delete the resources.
Wait for verification. After it creates the resources, the Blueprint checks that rows from your tables are reaching Tableflow. This check usually takes 5 to 20 minutes, and the run fails if no rows arrive within 25 minutes.

When the check passes, the page shows Provisioning complete, and you receive an email. The Blueprint summary has a link to each resource that the Blueprint created.

Step 5: Query your tables

Your PostgreSQL tables are now available as Iceberg tables that stay current as your data changes. From the Provisioning complete banner, you can:

Click Add catalog integration to publish the tables to a data catalog. For more information, see Integrate Catalogs with Tableflow in Confluent Cloud.
Click View query engine guide to read the tables from a query engine. For more information, see Use Query Engines with Tableflow in Confluent Cloud.

You can also query the <table>_current tables with Flink, in the SQL workspace of the environment that the Blueprint created. For more ways to read current state from a Streamhouse, see Choose a query surface.

To see the runs you started, click the History tab. You can run the Blueprint more than once, and each run creates its own set of resources.

Troubleshoot a failed run

If a run fails, the page shows Unable to provision resources. The Blueprint doesn’t delete the resources it created, and it doesn’t retry a run. To find the failed step, click Show steps.

Check for these common causes:

The connector fails or doesn’t start: Check the connector user’s password, the REPLICATION attribute, the CREATE privilege and table ownership, the wal_level setting, and the egress IP addresses. The Blueprint restarts a failed connector several times before it reports the failure, so an error such as a wrong password can take about 10 minutes to appear.
No rows reach Tableflow: Check that each table has a primary key and at least one row, and that the connector is running.

To try again, delete the resources from the failed run, fix the problem, and start a new run. For more information about connector errors, see PostgreSQL CDC Source Connector V2 (Debezium) for Confluent Cloud.

Delete the resources

Deleting a Blueprint run deletes all of the Confluent Cloud resources that the run created. It doesn’t change your PostgreSQL database, so you remove the replication slot and the publication yourself.

On the Blueprint page, click Delete and start over. To delete an earlier run, click the History tab, and then click Delete resources for the run.
Enter Delete all to confirm. Then click Delete and start over to delete the resources and open a new form, or Delete and close to delete them only.

If a resource can’t be deleted, the page lists it. Delete each listed resource manually in Confluent Cloud Console. To delete everything at once, delete the environment. For more information, see Delete an environment.
In your database, drop the replication slot and the publication that the connector created. Until you drop the slot, PostgreSQL keeps write-ahead log (WAL) files for it, and they consume disk space on your database server.

Both names come from your Streamhouse name, with hyphens replaced by underscores. For example, for a Streamhouse named acme-cdc, run:
```
SELECT pg_drop_replication_slot('acme_cdc_slot');
DROP PUBLICATION IF EXISTS pub_acme_cdc;
```
Run these statements after the connector is deleted. While the connector is still connected, the slot is active and pg_drop_replication_slot fails. If the slot is still active, wait a minute and try again.

To list the slots and publications on your database, run:
```
SELECT slot_name, active FROM pg_replication_slots;
SELECT pubname FROM pg_publication;
```

Build the Blueprint with Terraform

To build the same architecture with Terraform, click Download Terraform on the Blueprint page or on the Explore Streamhouse page. The download is a zip file that contains the Terraform configuration and a README.

The template is the same for everyone. It never contains the values that you entered in the form, and you supply your own values in terraform/terraform.tfvars. To run it, you need Terraform 1.5 or later and a Confluent Cloud API key for a principal with the OrganizationAdmin role.

Unlike deploying the Customer 360 Blueprint in Confluent Cloud Console, the Terraform template:

Can use an existing environment, which must have Stream Governance enabled.
Accepts any region, and lets you capture tables from a schema other than public.
Lets you set the topic prefix, the publication and slot names, and the maximum CFUs for the compute pool.
Creates API keys for the resources that it manages.
Doesn’t run the verification check.

For the full steps, including how to tear down the deployment, see the README.md file in the download.

Limitations

The Customer 360 Blueprint has the following limitations:

The source is PostgreSQL only, with username and password authentication.
The database must be reachable over public networking. Private networking isn’t supported.
The Blueprint always creates a new environment and cluster, and you can’t change a deployed Blueprint. To customize the architecture, use the Terraform template.
The Blueprint captures only tables in the public schema. To capture another schema, use the Terraform template.
The Blueprint supports only certain regions. For the list, see the Customer 360 Blueprint row in Confluent Cloud Regions and Availability by Cloud Provider. To use another region, use the Terraform template.

Cost

Blueprints themselves are free. You pay the standard rates for the resources that a Blueprint creates: the Standard cluster, the connector, Flink compute, Tableflow, and the Advanced Stream Governance package on the new environment. Resources keep incurring charges until you delete them. For more information, see Manage Billing in Confluent Cloud and Manage Stream Governance Packages in Confluent Cloud.