External Connection Source

What is an External Connection Source

An external connection source is a self-hosted HTTP endpoint that serves database connections in a standardized JSON format. Instead of manually adding each connection in Postview, you can create a service that dynamically provides a list of available connections.

This approach is particularly useful for:

Enterprise environments where database connections are managed centrally
Dynamic environments where database instances are created/destroyed frequently
Multi-tenant applications where different users need access to different databases
Development teams sharing standardized connection configurations

How to Set Up

Create an HTTP endpoint that returns a JSON array of connections
Ensure your endpoint is accessible from the Postview application
In Postview, click "Or add an external connection source" when adding a new connection
Enter your endpoint URL and give it a descriptive name
Postview will fetch and display all connections from your endpoint

Example Endpoint

You can see a working example at: https://example.postview.app/connections.json

Example Implementation

Here's a simple Node.js example of an external connection source:

const express = require("express");
const app = express();

app.get("/connections", (req, res) => {
	const connections = [
		{
			"id": "prod-db-001",
			"name": "Production Database",
			"uri":
				"postgresql://postgres:${password}@prod-db.company.com:5432/production",
			"color": "#ff0000",
		},
		{
			"id": "staging-db-001",
			"name": "Staging Database",
			"uri":
				"postgresql://postgres:${password}@staging-db.company.com:5432/staging",
			"color": "#ffaa00",
		},
		{
			"id": "dev-db-001",
			"name": "Development Database",
			"uri":
				"postgresql://postgres:${password}@dev-db.company.com:5432/development",
			"color": "#00ff00",
		},
	];

	res.json(connections);
});

app.listen(3000, () => {
	console.log("Connection source running on port 3000");
});

Example JSON Response

Your endpoint should return a JSON array like this:

[
	{
		"id": "prod-db-001",
		"name": "Production Database",
		"uri": "postgresql://postgres:${password}@prod-db.company.com:5432/production",
		"color": "#ff0000"
	},
	{
		"id": "staging-db-001",
		"name": "Staging Database",
		"uri": "postgresql://postgres:${password}@staging-db.company.com:5432/staging",
		"color": "#ffaa00"
	}
]

Security Note: Passwords can be omitted by using the ${password} placeholder. When establishing the connection in Postview, the user will be prompted to input the correct password. This keeps sensitive credentials out of your connection source endpoint.

Field Reference

Each connection object in your JSON response can contain the following fields:

Field	Type	Required	Description
`id`	string	✅	Unique identifier for the connection. Used for credential storage and connection management.
`name`	string	✅	Human-readable name displayed in Postview's connection sidebar.
`uri`	string	✅	Full database connection URI. Use `${password}` placeholder for secure password handling.
`color`	string	❌	Hex color code (e.g., `#ff0000`) for visual organization in the sidebar.
`connectionSourceUrl`	string	❌	URL to another connection source for nested/chained sources.

JSON Schema

For validation and reference, here's the complete JSON schema:

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type": "array",
	"items": {
		"type": "object",
		"properties": {
			"id": {
				"type": "string",
				"minLength": 1,
				"description": "An identifier for this connection that should be unique within the connection source. Used to reference the connection later and securely store credentials in the keyring."
			},
			"name": {
				"type": "string",
				"minLength": 1,
				"description": "A human-readable name for the connection (e.g., 'Production DB' or 'Local Postgres')."
			},
			"uri": {
				"type": "string",
				"format": "uri",
				"description": "The full connection URI. If the password is omitted, include `${password}` in its place to prompt the user at runtime. Example: `postgresql://postgres:${password}@127.0.0.1:5432/postgres`."
			},
			"color": {
				"type": "string",
				"pattern": "^#([0-9a-fA-F]{6})$",
				"description": "An optional hex color code (e.g., `#ff0000`). Useful for visually distinguishing between multiple connections."
			},
			"connectionSourceUrl": {
				"type": "string",
				"format": "uri",
				"description": "An optional URL pointing to another connection source. Allows nesting or chaining multiple connection sources."
			}
		},
		"required": ["id", "name", "uri"]
	},
	"description": "A list of database connections. Each connection must have a unique `id`, `name`, and `uri`. Optional fields (`color`, `connectionSourceUrl`) provide additional metadata and structure."
}

Best Practices

Security

Never include passwords in your connection URIs. Always use the ${password} placeholder.
Use HTTPS for your connection source endpoint to protect data in transit.
Implement authentication on your endpoint if it contains sensitive connection information.
Validate and sanitize connection URIs before serving them.

Performance

Cache responses when possible to reduce load on your endpoint.
Implement proper HTTP headers like Cache-Control for better performance.

Testing Your Endpoint

You can test your connection source endpoint using curl:

curl -X GET https://example.postview.app/connections.json \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

The response should be a valid JSON array of connection objects.

External Connection Source

External Connection Source

On this page