🔗 Connect with Local Databases

This guide explains how to connect databases running locally to the QueryPie AI service. It covers proper DSN (Data Source Name) string generation and security tunnel setup for remote access.

Overview

When working in a local development environment, you may need to connect databases running on your local machine to QueryPie AI Hub.

To connect to a local database, please prepare the following items:

1. Local database instance (e.g., PostgreSQL, MySQL, Redis, etc.)
2. Tunnel service to make the local database accessible via the internet
3. Proper DSN string configuration

Tunnel Service Options

You can use tunnel services like ngrok, Cloudflare Tunnel, etc.

ngrok

A popular tunneling solution that provides additional features.

brew install ngrok

ngrok tcp 5432

The DSN string can be entered as follows:

postgresql://username:password@X.tcp.ngrok.io:XXXXX/dbname

Cloudflare Tunnel

Cloudflare Tunnel is a free and stable tunneling service.

brew install cloudflared

cloudflared tunnel --url tcp://localhost:5432

Complete Setup Example

Let’s look at a complete setup process using PostgreSQL and ngrok:

1. Start Local PostgreSQL Server

Ensure PostgreSQL is running on the default port 5432.

brew services start postgresql

2. Create ngrok Tunnel

Create a named tunnel.

ngrok tcp 5432

When the tunnel is created, you’ll see output like this:

Session Status                online
Account                       your-account (Plan: Free)
Version                       3.x.x
Region                        United States (us)
Latency                       -
Web Interface                 http://127.0.0.1:4040
Forwarding                    tcp://0.tcp.ngrok.io:12345 -> localhost:5432

3. Configure DSN String in QueryPie AI

Use the information provided in the ngrok output above to generate the DSN string:

postgresql://username:password@0.tcp.ngrok.io:12345/dbname

You can use this DSN string to add a database in QueryPie AI Hub.

Security Considerations

When exposing local databases to the internet, always follow these guidelines:

• 🔒 Use strong passwords and usernames.
• 🌐 Allow connections only from known IP ranges.
• 🔐 Use SSL encrypted connections. QueryPie AI Hub also supports SSL connections.
• 📊 Maintain and monitor database connection logs.
• ⏱️ Use temporary tunnels during development and terminate them immediately after use.

Troubleshooting

Here are common issues and solutions when using tunneling connections:

1. Connection Timeout

• Verify that the tunnel is running.
• Check if the local database allows external connections.
• Ensure firewall rules allow the connection.

2. Authentication Errors

• Verify database credentials.
• Check if the database user has appropriate permissions.
• Ensure the DSN string format is correct.

3. SSL/TLS Issues

• Configure SSL certificates if necessary.
• Add sslmode=require to the DSN string for secure connections.

4. Port Conflicts

• Check if other services are using the same port.
• Change to a different port if necessary.

Roadmap: Tunneling

Tunneling functionality will be added to the local proxy in the future (planned for Q3 2025).
Through the tunneling functionality built into the local proxy, QueryPie AI Hub and user networks will be able to connect.
This will enable the following:

• Connect and use MCP Servers running on user networks
• If using QueryPie, safer DB, Server, Kubernetes access through QueryPie
• Even if not using QueryPie, support for DB, Server, Kubernetes access

Additional Resources

• ngrok Official Documentation 
• Cloudflare Tunnel Documentation