Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.teesql.com/llms.txt

Use this file to discover all available pages before exploring further.

Connect to a TeeSQL cluster from a Python or TypeScript application, run a query, and (optionally) verify the database’s TDX attestation. This page is the happy path; deeper material lives in Connect and Security.
1

Prerequisites

  • A TeeSQL cluster. TeeSQL is in early access — request one on the waitlist. The operator returns a cluster host, a cluster secret, and a database name.
  • An Intel TDX environment for your application. Mutual RA-TLS requires your app to present its own TDX-attested client certificate. In production this means a dstack CVM, Phala Cloud, iExec, or another TDX host. For local development, run the dstack simulator.
  • An Intel Trust Authority API key. Free; register at portal.trustauthority.intel.com. Used to verify the database’s TDX quote.
  • A runtime. Node.js ≥ 18 with Prisma ≥ 5.10, or Python ≥ 3.10 with psycopg 3.
2

Create a database

During early access, the TeeSQL operator provisions your cluster and database after you join the waitlist. You receive:
  • A cluster host (e.g. your-cluster.teesql.com) backed by a signed TXT manifest at _teesql-leader.<cluster-uuid>.teesql.com
  • A database name
  • A cluster secret (32-byte hex) — your password for both teesql_readwrite and teesql_read roles
3

Get connection details

The canonical connection string:Set them in your environment:
DATABASE_URL=postgresql://teesql_readwrite:your-32-byte-hex-secret@your-cluster.teesql.com:5433/mydb
INTEL_TRUST_AUTHORITY_API_KEY=your-ita-key
4

Connect

Use a TeeSQL RA-TLS client. The client opens a localhost forwarder that terminates mutual RA-TLS to the cluster sidecar; your driver speaks plain Postgres to that forwarder.
from psycopg_ratls import connect
from ra_tls_verify import IntelApiVerifier
import os

verifier = IntelApiVerifier(api_key=os.environ["INTEL_TRUST_AUTHORITY_API_KEY"])

conn = connect(os.environ["DATABASE_URL"], verifier=verifier)
The mutual RA-TLS handshake happens once at process start — keep the connection long-lived, do not re-handshake per query.
5

Run a query

conn.execute("""
  CREATE TABLE IF NOT EXISTS notes (
    id    bigserial PRIMARY KEY,
    body  text NOT NULL,
    ts    timestamptz NOT NULL DEFAULT now()
  )
""")
conn.execute("INSERT INTO notes (body) VALUES (%s)", ("hello from a CVM",))
rows = conn.execute("SELECT id, body, ts FROM notes ORDER BY id DESC LIMIT 5").fetchall()
print(rows)
6

Verify attestation (optional)

The client you just used already verified the server’s TDX quote against Intel Trust Authority. To pin the exact CVM image you expect, pass an allowedMrTd allowlist of MRTD hex values:
const adapter = await withRaTls(process.env.DATABASE_URL!, {
  verifier: new IntelApiVerifier(),
  allowedMrTd: [process.env.EXPECTED_MRTD!],
  clientAttestation: true,
})
See Verify attestation for the full RTMR/MRTD model and how to pin measurements safely.

​
Next steps

Connection string

Roles, ports, the cluster secret, and the leader manifest.

Security overview

The trust model behind mutual RA-TLS.
Last modified on May 1, 2026