The connection string method allows you to connect virtually any PostgreSQL database to Tembo, including:

  • Self-hosted PostgreSQL servers
  • Cloud databases without dedicated integrations
  • PostgreSQL-compatible databases (like CockroachDB, YugabyteDB)
  • Development and testing databases

Connection String Format

PostgreSQL connection strings follow this format:

postgresql://[username]:[password]@[host]:[port]/[database]?[parameters]

Example:

postgresql://dbuser:<use-a-secure-generated-password>@localhost:5432/mydb?sslmode=require

Prerequisites

Before connecting your database, ensure:

  • Your database is accessible from the internet or through a secure tunnel
  • You have valid database credentials with appropriate permissions
  • The PostgreSQL port (typically 5432) is open in your firewall/security group
  • SSL/TLS is properly configured if required

Setup Instructions

1. Create a Database User for Tembo

For security, create a dedicated user for Tembo with appropriate permissions:

-- Create a dedicated user with a strong password
CREATE USER tembo_user WITH PASSWORD '<use-a-secure-generated-password>';

-- Grant minimum necessary permissions
GRANT CONNECT ON DATABASE your_database TO tembo_user;
GRANT USAGE ON SCHEMA public TO tembo_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO tembo_user;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO tembo_user;

-- For monitoring statistics
GRANT pg_monitor TO tembo_user;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO tembo_user;

2. Configure Connection Parameters

Common connection parameters include:

ParameterDescriptionRecommended Value
sslmodeSSL connection requirementrequire (or verify-full)
connect_timeoutConnection timeout in seconds10
application_nameIdentifies the application in logstembo_monitor
target_session_attrsSession characteristicsread-only (if applicable)

3. Build Your Connection String

Combine your database details and parameters into a connection string:

postgresql://tembo_user:<use-a-secure-generated-password>@db.example.com:5432/your_database?sslmode=require&application_name=tembo_monitor

4. Add the Connection in Tembo

  1. Log in to your Tembo account
  2. Navigate to Connections > Add Connection
  3. Select Connection String as the connection type
  4. Paste your connection string into the field
  5. Give your connection a descriptive name
  6. Click Test Connection to verify
  7. Click Create Connection to save

Troubleshooting

Connection Errors

If you experience connection issues:

  • Connection refused: Check that your database is accessible and the port is open
  • Authentication failed: Verify username and password are correct
  • SSL required: Ensure SSL parameters match your database configuration
  • Timeout: Check network connectivity and firewall rules

Viewing Connection Details

To check your current PostgreSQL server connections:

SELECT * FROM pg_stat_activity
WHERE application_name = 'tembo_monitor';

Common SSL/TLS Issues

If you’re having SSL/TLS issues:

  • Certificate validation: Use sslmode=verify-ca or verify-full with proper CA certificates
  • SSL not available: Ensure PostgreSQL was compiled with SSL support
  • Certificate mismatch: Verify the hostname matches the certificate

Advanced Configuration

Connection Pooling

For high-traffic databases, consider using connection pooling:

postgresql://tembo_user:<use-a-secure-generated-password>@pgbouncer.example.com:6432/your_database?pool=true

Read-Only Connections

To ensure Tembo never modifies data, use the read-only parameter:

postgresql://tembo_user:<use-a-secure-generated-password>@db.example.com:5432/your_database?target_session_attrs=read-only

Multiple Schemas

If your database uses multiple schemas, grant permissions appropriately:

GRANT USAGE ON SCHEMA schema1, schema2 TO tembo_user;
GRANT SELECT ON ALL TABLES IN SCHEMA schema1, schema2 TO tembo_user;

Security Best Practices

  • Rotate the Tembo user password regularly
  • Use SSL/TLS with certificate validation
  • Grant only the minimum required permissions
  • Consider IP-based restrictions for additional security
  • Monitor all connections from Tembo in your database logs

Next Steps

After connecting your database: