Getting Started with Materialize Cloud

​

Prerequisites

• A valid email address for account creation
• A web browser (Chrome, Firefox, Safari, or Edge)
• A PostgreSQL client (e.g., psql) for connecting to your environment

​

Step 1: Sign Up for Materialize Cloud

1. Visit Materialize Cloud Console
2. Click Sign Up to create a new account
3. Complete the registration form:
   • Enter your email address
   • Create a secure password
   • Provide your organization name
4. Verify your email address by clicking the link sent to your inbox

​

Single Sign-On (SSO)

• Okta
• Google Workspace
• Azure AD
• Custom SAML 2.0 providers

​

Step 2: Create Your First Environment

1. Click Create Environment in the dashboard
2. Configure your environment:
   • Environment name: Choose a descriptive name (e.g., “production”, “staging”)
   • Region: Select the geographic region closest to your data sources
   • Version: Select the Materialize version (latest recommended)
3. Click Create to provision your environment

​

Step 3: Connect to Your Environment

​

Get Connection Details

1. Navigate to your environment in the Console
2. Click Connect to view connection details
3. Note the following information:
   • SQL endpoint: <environment-id>.materialize.cloud:6875
   • HTTP endpoint: https://<environment-id>.materialize.cloud
   • Username: Your Materialize account email
   • Password: Your account password or app-specific password

​

Connect Using psql

psql "postgres://<username>:<password>@<environment-id>.materialize.cloud:6875/materialize?sslmode=require"

• <username>: Your Materialize account email
• <password>: Your account password (URL-encoded if it contains special characters)
• <environment-id>: Your environment’s unique identifier

psql "postgres://user%40example.com:mypassword@12345678-abcd-1234-abcd-123456789012.materialize.cloud:6875/materialize?sslmode=require"

​

Connect Using Application Code

import psycopg2

conn = psycopg2.connect(
    host="<environment-id>.materialize.cloud",
    port=6875,
    user="<username>",
    password="<password>",
    database="materialize",
    sslmode="require"
)

cur = conn.cursor()
cur.execute("SELECT mz_version()")
print(cur.fetchone())

​

Step 4: Create Your First Cluster

-- Create a cluster with 2 replicas for high availability
CREATE CLUSTER my_cluster (
  SIZE = '100cc',
  REPLICATION FACTOR = 2
);

-- Set it as the default cluster for your session
SET CLUSTER = my_cluster;

​

Cluster Sizing Guidelines

• 25cc-50cc: Development and testing
• 100cc-200cc: Small production workloads
• 400cc-800cc: Medium production workloads
• 1600cc+: Large-scale production workloads

​

Step 5: Create a Data Source

-- Create a connection to your Kafka cluster
CREATE CONNECTION kafka_connection TO KAFKA (
  BROKER 'kafka.example.com:9092',
  SECURITY PROTOCOL = 'SASL_SSL',
  SASL MECHANISMS = 'PLAIN',
  SASL USERNAME = SECRET kafka_username,
  SASL PASSWORD = SECRET kafka_password
);

-- Create a source from a Kafka topic
CREATE SOURCE events
FROM KAFKA CONNECTION kafka_connection (TOPIC 'user-events')
FORMAT JSON;

• Kafka: Stream data from Apache Kafka
• PostgreSQL: CDC from PostgreSQL databases
• MySQL: CDC from MySQL databases
• S3: Batch data from Amazon S3
• Webhook: Real-time webhook ingestion

​

Step 6: Create a Materialized View

-- Create a materialized view for real-time analytics
CREATE MATERIALIZED VIEW event_counts AS
SELECT
  user_id,
  event_type,
  COUNT(*) as event_count,
  MAX(timestamp) as last_event_time
FROM events
GROUP BY user_id, event_type;

-- Query the materialized view
SELECT * FROM event_counts
WHERE user_id = '12345';

​

Step 7: Monitor Your Environment

1. Overview Dashboard: View cluster status, resource usage, and query performance
2. Metrics: Track CPU, memory, and disk usage over time
3. Query History: Review executed queries and their performance
4. Alerts: Configure alerts for resource thresholds and errors

​

Next Steps

​

Troubleshooting

​

Connection Issues

• Verify SSL/TLS is enabled (sslmode=require)
• Check that your credentials are correct
• Ensure your IP is not blocked by network policies
• Confirm the environment is running in the Console

​

Performance Issues

• Check cluster resource utilization in the Console
• Consider increasing cluster size
• Review query execution plans using EXPLAIN
• Add indexes to improve query performance

​

Support

• Documentation: Comprehensive guides at materialize.com/docs
• Community Slack: Join discussions with other users
• Support Portal: Submit tickets for technical assistance
• Email: [email protected]