diff --git a/.gitignore b/.gitignore
index b7c1baed..0aa9dfff 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,5 @@ tests/emulator/emulator.exe
 SECURITY_AUDIT_REPORT.md
 
 *.exe
+
+docs/
diff --git a/tests/.env.test b/tests/.env.test
index 0e2b1a5c..5692e7fe 100644
--- a/tests/.env.test
+++ b/tests/.env.test
@@ -8,8 +8,9 @@ EVENTS_QUEUE_ENDPOINT=http://localhost:8000/v1/events
 EVENTS_QUEUE_USER_API_KEY=system-user-api-key
 EVENTS_QUEUE_USER_ID=system-user-id
 FCM_ENDPOINT=http://wiremock:8080
-DATABASE_URL=postgresql://dbusername:dbpassword@postgres:5432/httpsms
-DATABASE_URL_DEDICATED=postgresql://dbusername:dbpassword@postgres:5432/httpsms
+DATABASE_URL=postgresql://root@cockroachdb:26257/httpsms?sslmode=disable
+DATABASE_URL_DEDICATED=postgresql://root@cockroachdb:26257/httpsms?sslmode=disable
+DATABASE_MIGRATION_CONSTRAINT_FIX=1
 REDIS_URL=redis://@redis:6379
 APP_PORT=8000
 APP_NAME=httpSMS
diff --git a/tests/README.md b/tests/README.md
index c914982d..a37653e5 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -20,21 +20,21 @@ End-to-end integration tests for the httpSMS API. These tests validate the compl
                               └──────────────┘
                                      │
                               ┌──────┴───────┐
-                              │  PostgreSQL  │   │    Redis    │
-                              │  Port 5435   │   │  Port 6379  │
+                              │ CockroachDB  │   │    Redis    │
+                              │  Port 26257  │   │  Port 6379  │
                               └──────────────┘   └─────────────┘
 ```
 
 ### Components
 
-| Component       | Description                                             |
-| --------------- | ------------------------------------------------------- |
-| **API**         | The httpSMS Go API server running in Docker             |
-| **Emulator**    | A Fiber v3 Go service that simulates an Android phone   |
-| **PostgreSQL**  | Database for the API                                    |
-| **Redis**       | Cache and queue backend                                 |
-| **Seed**        | One-shot container that seeds test data into PostgreSQL |
-| **Test Runner** | Go test binary that runs on the host machine            |
+| Component       | Description                                              |
+| --------------- | -------------------------------------------------------- |
+| **API**         | The httpSMS Go API server running in Docker              |
+| **Emulator**    | A Fiber v3 Go service that simulates an Android phone    |
+| **CockroachDB** | Database for the API (single-node, insecure mode)        |
+| **Redis**       | Cache and queue backend                                  |
+| **Seed**        | One-shot container that seeds test data into CockroachDB |
+| **Test Runner** | Go test binary that runs on the host machine             |
 
 ### How It Works
 
@@ -86,7 +86,7 @@ export FIREBASE_CREDENTIALS=$(jq -c . firebase-credentials.json)
 docker compose up -d --build --wait
 ```
 
-This starts PostgreSQL, Redis, the API, and the emulator. The `--wait` flag blocks until all health checks pass.
+This starts CockroachDB, Redis, the API, and the emulator. The `--wait` flag blocks until all health checks pass.
 
 ### 4. Wait for Seeding
 
@@ -95,7 +95,7 @@ docker compose wait seed
 sleep 2
 ```
 
-The seed container inserts test users, phones, and API keys into PostgreSQL after the API has run its GORM migrations.
+The seed container inserts test users, phones, and API keys into CockroachDB after the API has run its GORM migrations.
 
 ### 5. Run Tests
 
@@ -181,7 +181,7 @@ docker compose logs api
 Common issues:
 
 - `FIREBASE_CREDENTIALS` env var not set or malformed
-- PostgreSQL not ready (increase `start_period` in healthcheck)
+- CockroachDB not ready (increase `start_period` in healthcheck)
 
 ### Tests timeout waiting for `delivered` status
 
diff --git a/tests/docker-compose.yml b/tests/docker-compose.yml
index 515b6298..3d82d47c 100644
--- a/tests/docker-compose.yml
+++ b/tests/docker-compose.yml
@@ -1,18 +1,39 @@
 services:
-  postgres:
-    image: postgres:alpine
-    environment:
-      POSTGRES_DB: httpsms
-      POSTGRES_PASSWORD: dbpassword
-      POSTGRES_USER: dbusername
+  cockroachdb:
+    image: cockroachdb/cockroach:latest
+    command: start-single-node --insecure --store=type=mem,size=640MiB
     ports:
-      - "5435:5432"
+      - "26257:26257"
+      - "8081:8080"
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U dbusername -d httpsms"]
+      test:
+        [
+          "CMD",
+          "cockroach",
+          "sql",
+          "--insecure",
+          "--host=localhost",
+          "--execute=SELECT 1;",
+        ]
       interval: 5s
       timeout: 5s
       retries: 10
-      start_period: 5s
+      start_period: 10s
+
+  cockroachdb-init:
+    image: cockroachdb/cockroach:latest
+    depends_on:
+      cockroachdb:
+        condition: service_healthy
+    entrypoint:
+      [
+        "cockroach",
+        "sql",
+        "--insecure",
+        "--host=cockroachdb",
+        "--execute=CREATE DATABASE IF NOT EXISTS httpsms;",
+      ]
+    restart: "no"
 
   redis:
     image: redis:latest
@@ -61,8 +82,8 @@ services:
     ports:
       - "8000:8000"
     depends_on:
-      postgres:
-        condition: service_healthy
+      cockroachdb-init:
+        condition: service_completed_successfully
       redis:
         condition: service_healthy
       wiremock:
@@ -81,24 +102,19 @@ services:
       start_period: 30s
 
   seed:
-    image: postgres:alpine
+    image: cockroachdb/cockroach:latest
     depends_on:
       api:
         condition: service_healthy
-    environment:
-      PGPASSWORD: dbpassword
     volumes:
       - ./seed.sql:/seed.sql:ro
     entrypoint:
       [
-        "psql",
-        "-h",
-        "postgres",
-        "-U",
-        "dbusername",
-        "-d",
-        "httpsms",
-        "-f",
-        "/seed.sql",
+        "cockroach",
+        "sql",
+        "--insecure",
+        "--host=cockroachdb",
+        "--database=httpsms",
+        "--file=/seed.sql",
       ]
     restart: "no"