CockroachDB speaks Postgres wire closely enough that `drivers.store.sql` stays
`postgres`. Multi-region and distributed transactions are Cockroach's concern beneath
that protocol.

<Callout title="The one rule">
  Use the Cloud Console **Connect** dialog and keep `sslmode=verify-full` with the downloaded CA —
  `sslmode=require` alone is rejected for secure clusters.
</Callout>

## Find credentials (current console)

1. Open [CockroachDB Cloud](https://cockroachlabs.cloud) → your **cluster**.
2. Click **Connect** (cluster overview / top right).
3. Open the **Connection string** tab (or **General connection string**).
4. Expand **Download CA Cert** — run the provided command so `root.crt` lands in the
   default Postgres cert directory (or note the path).
5. Copy the `postgresql://…` string; paste the password when prompted (shown once for
   new SQL users — reset under **SQL Users** if lost).

```bash title="process env"
DATABASE_URL=postgresql://user:password@….cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=/path/to/root.crt
```

Default SQL port is **26257**, not 5432.

## Production guidance

| Topic   | Guidance                                                                                |
| ------- | --------------------------------------------------------------------------------------- |
| TLS     | `verify-full` + `sslrootcert` — required for Cloud                                      |
| Pooling | Prefer Cockroach's guidance / built-in limits; do not assume Neon-style `-pooler` hosts |
| Regions | Configure survivability in the Console — opaque to the `postgres` driver                |

CockroachDB Software License (since Nov 2024): Core open-source discontinued; free for
orgs under $10M ARR with community support; paid tiers add dedicated support. Not OSI
open source.

## Query performance

<Callout title="Unsupported">
  CockroachDB does not expose `pg_stat_statements`. Store → **Performance** returns
  `PgStatStatementsUnsupported`. oke does not shim `statement_statistics`.
</Callout>

| Step    | What you do                                      |
| ------- | ------------------------------------------------ |
| Preload | Not applicable                                   |
| Create  | Not applicable                                   |
| Console | Structured unavailable — use Cockroach's console |

## Real gotcha — CA cert path

Copying the connection string without downloading the CA yields TLS verify failures
even when the password is correct. The Connect dialog's download command and
`sslrootcert=` must agree on the same file path in the environment that runs the app.

## Troubleshooting

<Accordions>
<Accordion title="certificate verify failed / SSL connection error">

Missing or wrong `sslrootcert`. Re-download from **Connect → Download CA Cert**, point
`sslrootcert` at that file, keep `sslmode=verify-full`. Using `require` without verify
is not accepted for Cloud's default secure posture.

</Accordion>
<Accordion title="password authentication failed for user">

Password is shown once at user creation. Reset under the cluster **SQL Users** page,
then update `DATABASE_URL`.

</Accordion>
</Accordions>

## Learn more

- [YugabyteDB](/docs/providers/yugabytedb) — Apache 2.0 distributed alternative
- [CockroachDB (self-hosted)](/docs/recipes/cockroachdb) — single-node Docker recipe
- [Postgres (image)](/docs/recipes/postgres) — driver this backs
- [Store · SQL](/docs/elements/store#sql) — schema workflows

## Next

<Cards>
  <Card
    title="YugabyteDB"
    description="Apache-2.0 licensed alternative."
    href="/docs/providers/yugabytedb"
  />
  <Card title="Neon" description="Serverless single-region option." href="/docs/providers/neon" />
  <Card title="PgDog" description="Self-hosted pooling." href="/docs/recipes/pgdog" />
</Cards>