Integration Guide

Prerequisites

• A Vericto account (sign up free)
• An API key (create one in Dashboard → API Keys)
• For TCP proxy (runtime protection): Docker or any container runtime to deploy the proxy in your infrastructure
• For the CLI (pre-commit & CI/CD): a shell, or a CI runner with Node/Docker
• For the validation API or the runtime API: the ability to make HTTP requests from your pipeline or application
• For MCP (AI agents): a coding agent that supports remote MCP servers over HTTP, such as Claude Code

Vericto offers five integration modes. Pick by environment; they combine with each other:

Step 1: Create workspace & database

1. Go to /register and create your account
2. Navigate to Dashboard → Databases → Add Database
3. Enter a name (e.g. prod-users-db) and select the dialect. PostgreSQL and MySQL can run through the transparent TCP proxy; Oracle, SQL Server and Snowflake are evaluated via the HTTP API, the CLI and MCP only (Snowflake has no TCP wire protocol, so there is no proxy).
4. Copy the Database ID. You'll need it for configuration
5. Go to Dashboard → API Keys and create a key with the rules:read and telemetry:write scopes (the only ones the proxy needs: it pulls its ruleset and reports telemetry). The proxy evaluates SQL locally, so it does not need the AST evaluation scope. Copy it securely.

That's all you need from the Vericto dashboard. No connection strings, no credentials.

TCP Proxy: Production database protection

The TCP proxy intercepts every SQL query at the wire protocol level, for both PostgreSQL and MySQL (choose with VERICTO_WIRE_PROTOCOL). Deploy it as a sidecar or standalone container in your infrastructure. Your app connects to the proxy with the same credentials it uses for the database directly.

# docker-compose.yml
services:
  vericto-proxy:
    image: ghcr.io/vericto/vericto-proxy:latest
    ports:
      - "5433:5433"
    environment:
      VERICTO_API_URL: "https://api.vericto.com"
      VERICTO_API_KEY: "${VERICTO_API_KEY}"
      VERICTO_DATABASE_ID: "${VERICTO_DATABASE_ID}"
      VERICTO_WIRE_PROTOCOL: "postgres"   # or "mysql"
      UPSTREAM_HOST: "your-db-host.rds.amazonaws.com"
      UPSTREAM_PORT: "5432"
      PROXY_LISTEN_PORT: "5433"
      # Remote DB (RDS): encrypt the proxy → database hop.
      UPSTREAM_SSLMODE: "require"   # or "verify-full" + UPSTREAM_SSLROOTCERT

  app:
    environment:
      # Point your app to the proxy — same user:pass as before
      DATABASE_URL: "postgres://user:pass@vericto-proxy:5433/mydb"
    depends_on:
      - vericto-proxy

# vericto-proxy-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vericto-proxy
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vericto-proxy
  template:
    metadata:
      labels:
        app: vericto-proxy
    spec:
      containers:
        - name: vericto-proxy
          image: ghcr.io/vericto/vericto-proxy:latest
          ports:
            - containerPort: 5433
          env:
            - name: VERICTO_API_URL
              value: "https://api.vericto.com"
            - name: VERICTO_API_KEY
              valueFrom:
                secretKeyRef:
                  name: vericto-secrets
                  key: api-key
            - name: VERICTO_DATABASE_ID
              value: "your-database-id"
            - name: VERICTO_WIRE_PROTOCOL
              value: "postgres"   # or "mysql"
            - name: UPSTREAM_HOST
              value: "postgres-service.default.svc.cluster.local"
            - name: UPSTREAM_PORT
              value: "5432"
            - name: PROXY_LISTEN_PORT
              value: "5433"
          resources:
            requests:
              cpu: "250m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: vericto-proxy
spec:
  selector:
    app: vericto-proxy
  ports:
    - port: 5433
      targetPort: 5433

{
  "family": "vericto-proxy",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions": [{
    "name": "vericto-proxy",
    "image": "ghcr.io/vericto/vericto-proxy:latest",
    "portMappings": [{"containerPort": 5433}],
    "environment": [
      {"name": "VERICTO_API_URL", "value": "https://api.vericto.com"},
      {"name": "VERICTO_DATABASE_ID", "value": "your-database-id"},
      {"name": "VERICTO_WIRE_PROTOCOL", "value": "postgres"},
      {"name": "UPSTREAM_HOST", "value": "your-rds.xxxxx.us-east-1.rds.amazonaws.com"},
      {"name": "UPSTREAM_PORT", "value": "5432"},
      {"name": "PROXY_LISTEN_PORT", "value": "5433"}
    ],
    "secrets": [
      {"name": "VERICTO_API_KEY", "valueFrom": "arn:aws:ssm:us-east-1:xxx:parameter/vericto/api-key"}
    ]
  }]
}

Configuration reference

All proxy configuration is passed via environment variables. Only UPSTREAM_HOST is required; the control-plane link turns on as soon as you set VERICTO_API_URL and VERICTO_API_KEY. Omit them and the proxy still evaluates with its built-in default ruleset (handy for dev or air-gapped setups).

Encrypting connections (TLS)

Proxy → database. When your database is remote (e.g. a managed RDS/Cloud SQL instance), encrypt the proxy → database hop with UPSTREAM_SSLMODE. The proxy performs the PostgreSQL SSLRequest negotiation and tunnels the session through TLS:

# Encryption only (does not verify the server certificate)
UPSTREAM_SSLMODE=require

# Encryption + verify the certificate chain and hostname
UPSTREAM_SSLMODE=verify-full
UPSTREAM_SSLROOTCERT=/etc/vericto/rds-ca.pem   # omit to use public CA roots

# Optional: mutual TLS — present a client cert so the proxy authenticates to a
# database configured with `cert` auth (one service identity for the proxy)
UPSTREAM_SSLCERT=/etc/vericto/proxy-client.crt
UPSTREAM_SSLKEY=/etc/vericto/proxy-client.key

Client → proxy. By default the proxy declines client TLS, because it is meant to run inside the same trusted boundary as your app (sidecar, same host, or private subnet) where that hop never leaves your network. To encrypt it natively, set PROXY_TLS_MODE=require with a server certificate and key. The proxy answers the SSLRequest with 'S' and terminates TLS as the server:

PROXY_TLS_MODE=require
PROXY_TLS_CERT=/etc/vericto/server.crt
PROXY_TLS_KEY=/etc/vericto/server.key

Vericto recommends terminating client TLS at the proxy when:

• The app → proxy hop crosses an untrusted network (different host, VPC, or AZ) instead of a sidecar / private subnet.
• Your driver enforces sslmode=require and you don't want to run a TLS-terminating load balancer (AWS NLB, HAProxy) in front.
• A compliance baseline mandates encryption in transit on every hop.

If the proxy already runs as a sidecar or in the same private subnet, leave it disabled. It isn't needed. This is server-side TLS (the client authenticates the proxy); the proxy relays auth end-to-end, so scram-sha-256, md5 and cloud token auth (IAM / Entra) work unchanged. SCRAM channel binding (SCRAM-SHA-256-PLUS) and per-end-client cert auth are not supported through a TLS-terminating proxy by design. Both exist to detect a proxy in the middle. Inspecting SQL requires decrypting at the proxy, so opaque end-to-end TLS is incompatible with enforcement.

Telemetry buffering: memory vs. disk

The proxy buffers evaluation events before sending them to the Vericto API. Two strategies are available:

Configuration via environment variables:

VERICTO_TELEMETRY_BUFFER=memory|disk        # default: memory
VERICTO_TELEMETRY_DISK_PATH=/var/lib/vericto/spool
VERICTO_TELEMETRY_MEMORY_CAPACITY=10000

Resource recommendations

The proxy is designed to be lightweight. The AST engine compiles to native code and evaluates queries in-process, with no network calls on the critical path.

Key factors: CPU scales with query complexity (queries with multiple JOINs require parsing more AST nodes). Memory scales with the number of connections (each TCP session holds ~4 KB of state). Disk is only needed for telemetry buffering in disk mode.

Latency target: P99 < 2ms for rule evaluation. The proxy adds negligible overhead compared to the network round-trip to your database.

Frameworks & ORMs

Once the proxy is running, point your app to it. The only change is the host, same credentials, same database name:

Runtime API: evaluate each query before running it

It is the TCP proxy, over HTTP. Your application sends each query, one per call, to POST /api/v1/proxy/query right before running it, with the database it targets, and runs it only if Vericto lets it through. Use it for Oracle and SQL Server, which have no TCP proxy, or when you cannot change the connection string. The evaluation is recorded in Queries and the Audit Trail with the HTTP source, and counts toward your monthly queries.

Authenticate with an API key that has the Runtime API scope (proxy:evaluate). The workspace comes from the key, so you only send the query, the database_id (in Dashboard → Databases) and the dialect:

curl -X POST https://api.vericto.com/api/v1/proxy/query \
  -H "Authorization: Bearer $VERICTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "DELETE FROM users", "database_id": "<database-id>", "dialect": "oracle"}'

# 403 → {"decision": "BLOCKED", "rule_code": "VERICTO-001", "severity": "critical", ...}

Act on the status code:

• 200: run the query. decision is ALLOWED, FLAGGED or MONITORED; the last two are marked in the dashboard.
• 403: do not run it. decision is BLOCKED, with rule_code, severity and, when there is one, suggested_safe_query. It is also the answer when the engine is unavailable: the API fails closed.
• 429: the plan's monthly query quota is used up (Free and Builder only: Team and Enterprise never get a 429 for volume), or the key went over its per-minute safety limit (100 per second by default). Decide what to do then: the safe choice is not to run it (fail closed). The X-Quota-Remaining header on every response warns you before you get there.
• 400: the SQL could not be parsed in that dialect.

Sensitive columns. When the database has sensitive columns with the mask policy, the 200 response can carry rewritten_query: run that query instead of the original, and the masked columns come back already masked. sensitive_columns lists the tagged columns the query reads. The Runtime API cannot enforce it: an application that runs the original reads the real values. Only the TCP proxy enforces masking.

Want to check a whole migration file without running it? That is the validation API: batches of up to 500 queries, nothing runs.

CLI: shift-left in pre-commit & CI/CD

The vericto CLI validates SQL against your workspace's rules before it ever runs, in pre-commit hooks and CI pipelines. It's a thin client: it sends SQL to your workspace (POST /api/v1/ci/check-key) and mirrors the verdict as a process exit code. SQL is analyzed, never executed. Works with all four dialects (PostgreSQL, MySQL, Oracle, SQL Server) and is available on every plan, metered by a monthly checks allowance where each statement analyzed counts as one.

Install & authenticate

# Shell installer (Linux / macOS)
curl -fsSL https://github.com/vericto/vericto-cli/releases/latest/download/vericto-cli-installer.sh | sh

# npm / npx (CI runners already have Node)
npm install -g @vericto/vericto-cli
# or, zero-install in CI:
npx @vericto/vericto-cli check migrations/*.sql

# Docker (container step in CI)
docker run --rm -e VERICTO_API_KEY \
  ghcr.io/vericto/vericto-cli:latest check migrations/*.sql

# From source (Rust toolchain)
git clone https://github.com/vericto/vericto-cli && cargo install --path vericto-cli

# Prebuilt binaries for Linux (x86_64/aarch64), macOS (x86_64/aarch64) and
# Windows (x86_64) are published on every release, each with a SHA-256 checksum:
#   https://github.com/vericto/vericto-cli/releases
# Homebrew and Scoop are planned.

Authenticate once. On a laptop, vericto login opens your browser and mints a scoped 30-day key. Nothing is pasted. In CI, provide an API key via the VERICTO_API_KEY environment variable (or use OIDC, below):

vericto login                 # browser login (developer at a keyboard)
vericto doctor                # verify config, connectivity, auth & plan quota

# Check migrations locally — exit 1 if anything is blocked
VERICTO_API_KEY=vtro_... vericto check migrations/*.sql --dialect postgres

CI/CD pipelines

The CLI is a thin client that mirrors the verdict as a process exit code, so it works in any CI that can run a command. vericto init scaffolds a ready-to-commit template for GitHub Actions and GitLab CI; on CircleCI, Jenkins, and others you wire it by hand (same command, gated on the exit code). --changed checks only the *.sql files changed against the merge base, so PRs stay fast:

# GitHub Actions — .github/workflows/vericto.yml
name: Vericto SQL Check
on: pull_request
permissions:
  contents: read
  security-events: write   # required to upload SARIF to the Security tab
jobs:
  sql-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # --changed needs history for the merge base
      - run: npm install -g @vericto/vericto-cli
      - run: vericto check --changed --format sarif --output vericto.sarif
        env:
          VERICTO_API_KEY: ${{ secrets.VERICTO_API_KEY }}
      - uses: github/codeql-action/upload-sarif@v4   # inline PR annotations
        if: always()   # upload findings even when the check step exits non-zero
        with:
          sarif_file: vericto.sarif

# GitLab CI — .gitlab-ci.yml
vericto-check:
  stage: test
  image: node:20
  script:
    - npm install -g @vericto/vericto-cli
    - vericto check --changed --format gitlab-codequality --output gl-code-quality.json
  variables:
    VERICTO_API_KEY: $VERICTO_API_KEY
  artifacts:
    reports:
      codequality: gl-code-quality.json   # findings render inline on the MR
  rules:
    - changes: ["migrations/**/*.sql"]

# CircleCI — .circleci/config.yml
version: 2.1
jobs:
  vericto-check:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm install -g @vericto/vericto-cli
      # exit code 1 fails the job; --changed needs full history
      - run: vericto check --changed --format sarif --output vericto.sarif
      - store_artifacts:
          path: vericto.sarif
workflows:
  sql-check:
    jobs:
      - vericto-check:
          context: vericto        # holds VERICTO_API_KEY

// Jenkins — Jenkinsfile (declarative pipeline)
pipeline {
  agent { docker { image 'node:20' } }
  environment { VERICTO_API_KEY = credentials('vericto-api-key') }
  stages {
    stage('Vericto SQL Check') {
      steps {
        sh 'npm install -g @vericto/vericto-cli'
        // Non-zero exit code fails the stage
        sh 'vericto check --changed --format sarif --output vericto.sarif'
      }
      post {
        always { archiveArtifacts artifacts: 'vericto.sarif', allowEmptyArchive: true }
      }
    }
  }
}

Exit codes let CI tell a real block from an outage: 0 clean · 1 a finding at/above --fail-on (default block) · 2 usage error · 3 auth/config error · 4 backend/network error. Use --monitor to report findings but always exit 0 during initial rollout.

Pre-commit hook & baseline

Catch unsafe SQL before it's even committed. vericto init --hook installs the hook; adopting the CLI on a repo with pre-existing SQL won't turn the build red on day one. Record a baseline so only new findings fail:

vericto init --hook                                  # install the pre-commit hook

# Baseline existing findings, then fail only on new ones
vericto baseline migrations/*.sql                    # writes .vericto-baseline.json
vericto check migrations/*.sql --baseline .vericto-baseline.json

Suppress a single finding inline. A reason is required, so it stays accountable:

DELETE FROM users; -- vericto:ignore[VERICTO-001] one-off backfill, tracked in JIRA-42

Validation API: check batches of SQL without running them

Prefer to call Vericto from your own tooling instead of the CLI? Evaluate SQL over REST at POST /api/v1/ci/check-key, authenticated with an API key (scope ci_dryrun:execute). Queries are analyzed but never executed. This is the same endpoint the CLI uses. Reach for it only when the CLI doesn't fit your workflow.

Unlike the runtime API, here you send a batch (all the queries of a migration file, say), nothing runs and no registered database is needed. It uses the checks allowance, shared with the CLI and MCP: one check per statement. If the batch needs more checks than are left, it is rejected whole with 429 QUOTA_EXCEEDED, with nothing evaluated, and the response carries remaining (what is left) and requested (what the batch needed).

Send a batch of up to 500 queries, each tagged with its source line. The response returns a per-query verdict and an exit_code (1 if anything was blocked):

Code examples

# curl — evaluate one or more queries
curl -s -X POST https://api.vericto.com/api/v1/ci/check-key \
  -H "X-API-Key: $VERICTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialect": "postgres",
    "file_name": "0001_init.sql",
    "queries": [
      { "line": 1, "sql": "ALTER TABLE users DROP COLUMN email;" }
    ]
  }'

# Response:
# {
#   "summary": { "total": 1, "blocked": 1, "allowed": 0, "ruleset_version": "…" },
#   "queries": [
#     { "line": 1, "status": "BLOCKED", "rule_code": "VERICTO-014",
#       "severity": "high", "ast_node_path": "…", "suggested_fix": "…" }
#   ],
#   "exit_code": 1
# }

// Node.js — validate a query before applying a migration
const res = await fetch('https://api.vericto.com/api/v1/ci/check-key', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VERICTO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialect: 'postgres',
    queries: [{ line: 1, sql: sqlToValidate }],
  }),
}).then(r => r.json());

if (res.exit_code === 1) {
  const blocked = res.queries.find(q => q.status === 'BLOCKED');
  throw new Error(`Blocked by ${blocked.rule_code}: ${blocked.ast_node_path}`);
}

# Python — pre-deploy migration check
import requests, sys, glob, os

queries, files = [], []
for i, path in enumerate(sorted(glob.glob("migrations/*.sql")), start=1):
    with open(path) as f:
        queries.append({"line": i, "sql": f.read()})
        files.append(path)

r = requests.post(
    "https://api.vericto.com/api/v1/ci/check-key",
    headers={"X-API-Key": os.environ["VERICTO_API_KEY"]},
    json={"dialect": "postgres", "queries": queries},
).json()

if r["exit_code"] == 1:
    for q in r["queries"]:
        if q["status"] == "BLOCKED":
            print(f"BLOCKED: {files[q['line']-1]} — {q['rule_code']}")
    sys.exit(1)
print("All migrations safe ✓")

// Java — validate a query before applying a migration
import java.net.http.*;
import java.net.URI;

var body = """
    { "dialect": "postgres",
      "queries": [{ "line": 1, "sql": "ALTER TABLE users DROP COLUMN email;" }] }
    """;

var req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.vericto.com/api/v1/ci/check-key"))
    .header("X-API-Key", System.getenv("VERICTO_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());

// The endpoint returns 200; the verdict is in the body (parse exit_code).
if (res.body().contains("\"exit_code\":1")) {
    System.err.println("Blocked: " + res.body());
    System.exit(1);
}

// Go — validate a query before applying a migration
package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"dialect": "postgres",
		"queries": []map[string]any{
			{"line": 1, "sql": "ALTER TABLE users DROP COLUMN email;"},
		},
	})

	req, _ := http.NewRequest("POST",
		"https://api.vericto.com/api/v1/ci/check-key", bytes.NewReader(body))
	req.Header.Set("X-API-Key", os.Getenv("VERICTO_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		os.Exit(4) // backend/network error
	}
	defer resp.Body.Close()

	var out struct {
		ExitCode int `json:"exit_code"`
		Queries  []struct {
			Status   string `json:"status"`
			RuleCode string `json:"rule_code"`
		} `json:"queries"`
	}
	json.NewDecoder(resp.Body).Decode(&out)

	if out.ExitCode == 1 {
		os.Exit(1) // something was blocked → fail the build
	}
}

// .NET (C#) — validate a query before applying a migration
using System.Net.Http.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Add(
    "X-API-Key", Environment.GetEnvironmentVariable("VERICTO_API_KEY"));

var payload = new {
    dialect = "postgres",
    queries = new[] { new { line = 1, sql = "ALTER TABLE users DROP COLUMN email;" } },
};

var res = await http.PostAsJsonAsync(
    "https://api.vericto.com/api/v1/ci/check-key", payload);
var result = await res.Content.ReadFromJsonAsync<CheckResult>();

if (result?.exit_code == 1)
{
    Console.Error.WriteLine("Blocked by a security rule");
    Environment.Exit(1);
}

record Query(int line, string status, string? rule_code);
record CheckResult(int exit_code, Query[] queries);

For most pipelines the vericto CLI is simpler. It handles batching, --changed detection, baselines, and SARIF/Code-Quality output for you.

MCP: check SQL from your AI agent

Connect your coding agent to Vericto's remote MCP server (https://mcp.vericto.com/mcp) and check every migration or query against your workspace rules while the agent writes it. It uses the same API key (scope ci_dryrun:execute) and the same monthly quota as the CLI.

With the key exported as VERICTO_API_KEY, connect Claude Code with one command. The single quotes keep the key out of the saved configuration:

claude mcp add --scope user --transport http vericto https://mcp.vericto.com/mcp \
  --header 'Authorization: Bearer ${VERICTO_API_KEY}'

From then on, the agent calls check_sql with the whole file and gets a verdict per statement, with its line. Each statement costs one check, the same as through the CLI.

Other clients, the six tools, quota and troubleshooting: AI agents (MCP).

Verify & monitor

Once integrated, verify the setup is working:

• TCP Proxy: Go to Dashboard → Databases and click "Verify connection". The proxy will report its status within seconds.
• CLI: Run vericto doctor to confirm config, connectivity, auth, and your remaining monthly quota in one command.
• Runtime API: send DELETE FROM users: it should answer 403 with VERICTO-001 and show up in Queries with the HTTP source.
• Validation API: send a test batch and check the response. A 200 with "exit_code": 0 and "status": "ALLOWED" confirms the integration works.
• MCP: in Claude Code, /mcp should list vericto as connected with 6 tools. Ask the agent to check DELETE FROM users: the answer should be BLOCKED with VERICTO-001.
• Dashboard: Navigate to the Queries page to see real-time evaluation events flowing in, and the SQL checks page for the history of checks from the CLI, the API and agents (MCP).

Enable Observe Mode during initial rollout. It logs all decisions without blocking anything, so you can validate your ruleset before enforcing it.