<a id="streamhouse-blueprints"></a>

# 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](#streamhouse-blueprints-delete).

<a id="streamhouse-blueprints-what-it-builds"></a>

## 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<br/>records to one topic per table, named `cdc.public.<table>`. The<br/>connector creates a publication and a replication slot in your<br/>database. |
| Schemas                   | One key and one value subject per topic | Schemas that the connector infers from your tables. Each value<br/>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<br/>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<br/>with `cdc`.                                                                                                                                 |
| Flink service account     | `<name>-flink-runner`                   | Runs the Flink statements, with the EnvironmentAdmin role on the<br/>environment.                                                                                                                                     |

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

```sql
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](../connectors/cc-postgresql-cdc-source-v2-debezium/index.md#cc-postgresql-cdc-source-v2-debezium),
[Compute Pools in Confluent Cloud for Apache Flink](../flink/concepts/compute-pools.md#flink-sql-compute-pools), and [Tableflow in Confluent Cloud](../topics/tableflow/overview.md#cloud-tableflow).

<a id="streamhouse-blueprints-prerequisites"></a>

## Prerequisites

- The [OrganizationAdmin](../security/access-control/rbac/predefined-rbac-roles.md#organizationadmin-role) 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](../billing/overview.md#cloud-billing).
- A PostgreSQL database that meets the requirements in
  [Step 1: Prepare your PostgreSQL database](#streamhouse-blueprints-step-1).

<a id="streamhouse-blueprints-step-1"></a>

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

1. Confirm that logical replication is on. The following query must return
   `logical`.
   ```sql
   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.
2. 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.
   ```sql
   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.
3. Check your tables. The Blueprint captures tables in the `public` schema
   only, and each table needs a primary key and at least one row.
4. 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](../connectors/static-egress-ip.md#cc-static-egress-ips).

For more information about preparing PostgreSQL for change data capture, see
[PostgreSQL CDC Source V2 prerequisites](../connectors/cc-postgresql-cdc-source-v2-debezium/cc-postgresql-cdc-source-v2-debezium.md#cc-postgresql-cdc-source-v2-debezium-prereqs).

<a id="streamhouse-blueprints-step-2"></a>

## Step 2: Open the Customer 360 Blueprint

Open the Blueprint form from the **Explore Streamhouse** page.

1. In Confluent Cloud Console, on the home page, click **Explore Streamhouse**.
2. 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.

<a id="streamhouse-blueprints-step-3"></a>

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

1. 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.
2. 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.
3. Click **Show IP addresses for <region>**, review the egress IP addresses,
   and confirm that your database allows connections from all of them.
4. 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.

<a id="streamhouse-blueprints-step-4"></a>

## Step 4: Provision and verify the resources

1. 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](#streamhouse-blueprints-delete).
2. 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.

<a id="streamhouse-blueprints-step-5"></a>

## 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](../topics/tableflow/how-to-guides/catalog-integration/overview.md#cloud-tableflow-how-to-guides-catalog-integration).
- 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](../topics/tableflow/how-to-guides/query-engines/overview.md#cloud-tableflow-how-to-guides-query-engines).

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](query-surface.md#streamhouse-query-choose-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.

<a id="streamhouse-blueprints-troubleshoot"></a>

## 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](../connectors/cc-postgresql-cdc-source-v2-debezium/index.md#cc-postgresql-cdc-source-v2-debezium).

<a id="streamhouse-blueprints-delete"></a>

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

1. 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.
2. 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](../security/access-control/hierarchy/cloud-environments.md#cloud-environment-delete).
3. 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:
   ```sql
   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:
   ```sql
   SELECT slot_name, active FROM pg_replication_slots;
   SELECT pubname FROM pg_publication;
   ```

<a id="streamhouse-blueprints-terraform"></a>

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

<a id="streamhouse-blueprints-limitations"></a>

## 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](../get-started/regions.md#providers-regions). To use another
  region, use the Terraform template.

<a id="streamhouse-blueprints-cost"></a>

## 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](../billing/overview.md#cloud-billing) and [Manage Stream Governance Packages in Confluent Cloud](../stream-governance/packages.md#stream-gov-packages).

## Related content

- [Build a Streamhouse on Confluent Cloud](overview.md#streamhouse-overview)
- [Synchronize a change everywhere it is used](capture.md#streamhouse-synchronize)
- [Start here: the always-current table](query-surface.md#streamhouse-query-start-here)
- [Quick Start: Build a Streamhouse on Confluent Cloud](quick-start.md#streamhouse-quick-start)
- [PostgreSQL CDC Source Connector V2 (Debezium) for Confluent Cloud](../connectors/cc-postgresql-cdc-source-v2-debezium/index.md#cc-postgresql-cdc-source-v2-debezium)


#### NOTE
This website includes content developed at the [Apache Software Foundation](https://www.apache.org/)
under the terms of the [Apache License v2](https://www.apache.org/licenses/LICENSE-2.0.html).