Skip to main content

​
Getting Started

Connect Postgres databases to Blocks to enable agents to query, analyze, and work with your database schema and data. Agents can read schema information, execute queries, and help with database-related tasks.
Blocks supports read-only access to Postgres databases by default. Write access can be enabled but requires explicit configuration.

​
What Blocks Can Do

Blocks can help you with a variety of database tasks:
  • Schema Analysis: Examine table structures, relationships, and constraints
  • Query Execution: Run SELECT queries to retrieve data for analysis
  • Data Analysis: Analyze trends, generate reports, and answer data-related questions
  • Migration Planning: Review schema changes and suggest migration strategies
  • Query Optimization: Analyze slow queries and suggest improvements

​
Setting Up Postgres Integration

To connect a Postgres database to Blocks:
1

Navigate to Database Settings

Go to Settings > Database in the Blocks dashboard
2

Configure Connection String

Enter your Postgres connection string in the format:
postgresql://user:password@host:5432/database
Replace the values with your actual database credentials:
  • user: Database username
  • password: Database password
  • host: Your Postgres server hostname or IP address
  • 5432: Database port (default is 5432)
  • database: Database name
3

Configure Bastion (Optional)

If your database is behind a bastion host or requires SSH tunneling:
  1. Enable the “Connect with Bastion” toggle
  2. Provide the following SSH details:
    • SSH Private Key: Your private key for SSH authentication (required)
    • SSH Host: Bastion host address (required)
    • SSH User: SSH username (required, typically “ubuntu” or “ec2-user”)
    • SSH Password: SSH password if using password authentication (optional)
4

Save Configuration

Click “Save Changes” to store your database configuration securely
Always use dedicated read-only database users with minimal permissions for Blocks integrations. Never use admin or superuser credentials.

​
SSH Tunnel / Bastion Host Support

If your Postgres database is not publicly accessible and requires SSH tunneling through a bastion host, Blocks supports this configuration. When you enable “Connect with Bastion”, Blocks will establish an SSH tunnel to your bastion host before connecting to your database. This is useful when:
  • Your database is in a private VPC or subnet
  • You require an additional layer of security
  • Your infrastructure uses a jump server or bastion host pattern
When using bastion connections, ensure your SSH private key has the appropriate permissions and your bastion host is configured to allow connections to your database.

​
Using Postgres in Requests

Once connected, you can reference your database in requests: 
@blocks analyze the users table schema and explain the relationships

@blocks query the orders table for revenue trends over the last 30 days

@blocks check the slow query log and suggest optimization for the top 5 slowest queries
Session Context: All database queries are executed within the security context of the configured user. Blocks cannot access data or tables that the user doesn’t have permissions for.

​
Security Best Practices

  • Use Read-Only Users: Create dedicated database users with SELECT-only permissions
  • Limit Table Access: Grant access only to tables that agents need to query
  • Enable SSL: Use sslmode=require in your connection string for encrypted connections: 
    postgresql://user:password@host:5432/database?sslmode=require
  • Rotate Credentials: Regularly update database passwords and connection strings in Settings > Database
  • Monitor Queries: Review query logs to ensure agents are only accessing appropriate data
  • Network Security: Use bastion hosts, SSH tunneling, IP allowlisting, or VPN access for database connections
  • Secure Storage: All connection strings and SSH credentials are stored securely as sensitive environment variables

​
Common Use Cases

​
Database Documentation

Ask Blocks to generate documentation for your database schema: 
@blocks create documentation for all tables in the public schema, including column descriptions and relationships

​
Data Investigation

Use Blocks to investigate data issues or anomalies: 
@blocks find all orders with null customer_id and explain why this might be happening

​
Schema Migrations

Get help planning database changes: 
@blocks review this migration plan and suggest any missing indexes or constraints

​
Best Practices

  • Be Specific: Clearly specify which tables or schemas you want to work with
  • Provide Context: Include relevant business logic or constraints in your requests
  • Review Queries: Always review generated queries before executing them in production
  • Use Appropriate Access: Configure different database connections for dev, staging, and production environments

​
Next Steps

New to Blocks? Check out the Getting Started guide to learn the basics. Learn more about: