Integrations

Database

Connect Conductor to PostgreSQL, MySQL, or SQLite. Covers connection strings, SSL, pooling, read-only users, multiple named connections, and all available tools.

PostgreSQL connection string

format

postgresql://username:password@hostname:5432/database_name?sslmode=require

field breakdown

postgresql://
  username       — the database role to authenticate as
  :password      — the role's password (URL-encode special chars)
  @hostname      — host or IP of the PostgreSQL server
  :5432          — default PostgreSQL port (omit if using default)
  /database_name — the database to connect to
  ?sslmode=      — SSL mode (see SSL section below)

Special characters in the password must be percent-encoded. For example p@ss#word becomes p%40ss%23word.

MySQL connection string

format

mysql://username:password@hostname:3306/database_name

Default port is 3306. Append ?ssl=true to enable SSL. MySQL uses ? placeholders rather than $1.

SQLite file path

format

sqlite:///absolute/path/to/database.db
# or relative (resolved from Conductor working directory)
sqlite://./local.db

SQLite does not support pooling, concurrent writes, or network connections. It is best suited for local development and read-heavy workloads.

SSL / TLS configuration

PostgreSQL exposes SSL behavior through the sslmode query parameter. Use verify-full for production to prevent MITM attacks.

sslmode	Behavior
disable	No SSL. Never use in production — credentials sent in plain text.
allow	Try non-SSL first, fall back to SSL. Not recommended.
prefer	Try SSL first, fall back to non-SSL. Default for many clients.
require	SSL required, but server certificate is not verified.
verify-ca	SSL required, server certificate verified against a trusted CA.
verify-full	SSL + server hostname must match the certificate. Most secure.

conductor.config.json — ssl certs

{
  "plugins": {
    "database": {
      "connections": {
        "primary": {
          "url": "postgresql://user:pass@host:5432/db?sslmode=verify-full",
          "ssl": {
            "ca": "/path/to/ca.crt",
            "cert": "/path/to/client.crt",
            "key": "/path/to/client.key"
          }
        }
      }
    }
  }
}

Read-only PostgreSQL user

For analysis workflows where writes should never happen, create a dedicated read-only user. The ALTER DEFAULT PRIVILEGES line ensures SELECT is granted on tables created in the future.

psql — read-only user setup

-- Create a read-only role
CREATE ROLE readonly_role NOLOGIN;

-- Grant CONNECT on the database
GRANT CONNECT ON DATABASE production TO readonly_role;

-- Grant USAGE on all schemas
GRANT USAGE ON SCHEMA public TO readonly_role;

-- Grant SELECT on all existing tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_role;

-- Auto-grant SELECT on future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO readonly_role;

-- Create login user and assign role
CREATE USER conductor_reader WITH PASSWORD 'your-password';
GRANT readonly_role TO conductor_reader;

Multiple connections

Name each connection under the connections key. When invoking tools, specify the connection by name using the connection parameter. The first connection listed is used by default when no name is given.

conductor.config.json — multiple connections

{
  "plugins": {
    "database": {
      "connections": {
        "primary": {
          "url": "postgresql://app_user:s3cr3t@db.example.com:5432/production?sslmode=require"
        },
        "analytics": {
          "url": "postgresql://readonly:s3cr3t@analytics.example.com:5432/warehouse?sslmode=verify-full"
        },
        "local": {
          "url": "sqlite:///Users/me/project/dev.db"
        }
      }
    }
  }
}

Connection pooling

Conductor maintains a connection pool per named connection. Tune pool.max to stay within your database's max_connections limit. A conservative default is 5–10 for most hobby plans; 20–50 for dedicated servers. If you use PgBouncer or RDS Proxy, you can safely increase this.

conductor.config.json — pooling

{
  "plugins": {
    "database": {
      "connections": {
        "primary": {
          "url": "postgresql://user:pass@host:5432/db",
          "pool": {
            "min": 2,
            "max": 10,
            "idleTimeoutMs": 30000,
            "connectionTimeoutMs": 5000
          }
        }
      }
    }
  }
}

Available tools

Tool	Description
db.query	Execute a SQL SELECT or DML statement on a named connection. Returns rows as JSON.
db.schema	Return full schema information: tables, columns, types, nullable, defaults.
db.tables	List all table names in the connected database and schema.
db.indexes	List indexes for a given table — name, columns, uniqueness, type.
db.explain	Run EXPLAIN ANALYZE on a query and return the execution plan.
db.transaction	Execute an array of statements atomically. Rolls back on any failure.

Parameterized queries

Always use parameterized queries when values come from user input or external data. Conductor passes parameters separately from the query string, preventing SQL injection.

parameterized query syntax

// Conductor passes parameterized queries automatically.
// Use $1, $2 placeholders in PostgreSQL:
SELECT * FROM orders WHERE user_id = $1 AND status = $2

// MySQL uses ? placeholders:
SELECT * FROM orders WHERE user_id = ? AND status = ?

Transaction handling

db.transaction example

// db.transaction wraps multiple statements in a single transaction.
// If any statement fails, the entire transaction is rolled back.
{
  "tool": "db.transaction",
  "connection": "primary",
  "statements": [
    "UPDATE accounts SET balance = balance - 100 WHERE id = 1",
    "UPDATE accounts SET balance = balance + 100 WHERE id = 2",
    "INSERT INTO transfers (from_id, to_id, amount) VALUES (1, 2, 100)"
  ]
}

PostgreSQL auth methods

Method	Description
trust	No password required. Only for local Unix socket connections in dev.
md5	MD5-hashed password. Common in older PostgreSQL installs. Less secure than scram.
scram-sha-256	Default since PostgreSQL 14. Strong challenge-response auth. Use this.
peer	OS username must match database role. Local Unix socket only.
cert	Client certificate authentication. Requires ssl.cert and ssl.key in config.

Common errors

Error	Cause	Fix
ECONNREFUSED	Nothing is listening on the specified host:port.	Verify the hostname and port. Check that the database server is running and reachable (firewall, VPC security groups).
authentication failed	Wrong username, password, or pg_hba.conf does not allow the connection.	Test with psql using the same credentials. Check pg_hba.conf for the auth method (md5 vs scram-sha-256 vs trust).
SSL required	The server requires SSL but sslmode=disable was used.	Add ?sslmode=require to the connection string.
too many clients	max_connections limit on the PostgreSQL server has been reached.	Reduce pool.max in config. Consider using PgBouncer as a connection pooler in front of PostgreSQL.
relation does not exist	The table or view name is wrong, or the search_path schema is incorrect.	Qualify the table with schema: schema.table_name. Check db.tables to confirm what exists.
permission denied for table	The database role lacks SELECT/INSERT/UPDATE/DELETE on the table.	Grant the appropriate privilege. For read-only use, follow the read-only user setup in this guide.
SSL SYSCALL error: EOF detected	SSL handshake failed — mismatched TLS version or certificate issue.	Verify CA cert path. Try sslmode=require instead of verify-full to isolate certificate vs. connection issue.

All integrations