Skip to content
BoilStream

Send and query your first events

tutorial
TL;DR

Connect with psql to a provisioned streaming catalog, create a small table and insert two events. Query through the same connection to verify the result. You need table-creation permission and temporary database credentials. Streaming visibility follows the commit cycle, so an early empty result is not a reason to insert again.

Message sequenceCreate, write, then verify with the same SQL client
Create, write, then verify with the same SQL clientA PostgreSQL client connects to BoilStream, creates the example table, inserts rows and reads them back. The final SELECT verifies the rows visible through that connection.psql clientBoilStreamConnect to authorized catalogCREATE TABLEDDL resultINSERT example rowsSQL statement resultSELECT from the tableVisible rowsTime moves downward · dashed arrows are responsesCreate, write, then verify with the same SQL clientA PostgreSQL client connects to BoilStream, creates the example table, inserts rows and reads them back. The final SELECT verifies the rows visible through that connection.psql clientBoilStreamConnect to authorizedcatalogCREATE TABLEDDL resultINSERT example rowsSQL statement resultSELECT from the tableVisible rowsTime moves downward · dashed arrows are responses
Verify the query result before adding another producer, view or consumer to the workflow.

Prerequisites

Section titled “Prerequisites”
  • A running deployment and an authorized catalog named events__stream, provisioned by your administrator. Use your actual catalog name in the connection.
  • Catalog admin access to create the example table, and permission to insert and query.
  • psql, the server endpoint and trusted CA, and temporary database credentials.

This example creates main.activity. Use a test catalog where that name is unused. Catalog provisioning is covered in the administrator guide.

1. connect

Section titled “1. connect”

Use the host, port, user and database returned by the dashboard. Enter its temporary password when prompted:

Shell
psql "host=HOST port=PORT user=USER dbname=events__stream sslmode=verify-full sslrootcert=/path/to/ca.pem"

Use your client’s trusted-CA configuration for a public certificate. Do not replace the temporary database password with your dashboard password.

2. create a table

Section titled “2. create a table”
SQL
CREATE TABLE main.activity (
    event_id BIGINT,
    event_type VARCHAR,
    event_time TIMESTAMP
);

3. insert two events once

Section titled “3. insert two events once”
SQL
INSERT INTO main.activity VALUES
    (1, 'view', TIMESTAMP '2026-01-01 12:00:00'),
    (2, 'click', TIMESTAMP '2026-01-01 12:00:01');

If the connection is lost, retain these inputs and reconcile their outcome. An event_id column does not automatically deduplicate a repeated insert.

4. verify the result

Section titled “4. verify the result”
SQL
SELECT event_id, event_type, event_time
FROM main.activity
ORDER BY event_id;

Expected rows once the commit is visible:

event_id event_type event_time
1 view 2026-01-01 12:00:00
2 click 2026-01-01 12:00:01

If the result is initially empty, repeat only the SELECT for a bounded period appropriate to your deployment’s commit cycle. Stop and inspect completion and visibility if it does not become visible. A fixed sleep is not a readiness guarantee.

Troubleshooting

Section titled “Troubleshooting”
Symptom Action
Authentication failed Get fresh temporary credentials and check the returned catalog and endpoint.
CREATE denied Ask the catalog administrator for the required access or an existing test table.
Table already exists Inspect it or use a new table name; do not drop an unfamiliar table.
Empty result Repeat the read within a bounded deadline; check the catalog and commit progress.
More than two rows Reconcile prior inserts before sending more data.

Next step

Section titled “Next step”
ComparisonChoose the interface for the operation
Choose the interface for the operationIngestion, SQL queries and live consumption use different interfaces and credentials. This comparison groups them by the job the client needs to perform.Client jobInterfaceSend rowsContinuous inputHTTP Arrow or Kafka; Flighthas limitsRun SQLCreate, insert or queryPGWire; managed DuckDB;Flight SQL previewFollow eventsLive application updatesSSE with a stream-purposetokenChoose the interface for the operationIngestion, SQL queries and live consumption use different interfaces and credentials. This comparison groups them by the job the client needs to perform.Client jobInterfaceSend rowsContinuousinputHTTP Arrowor Kafka;Flight haslimitsRun SQLCreate,insert orqueryPGWire;managedDuckDB;Flight SQLpreviewFolloweventsLiveapplicationupdatesSSE with astream-purposetoken
Start with the operation, then check authentication, completion semantics and interface support.

Try HTTP Arrow ingestion or an example dataset. Use the separate native DuckDB guide if that is your preferred query client.