# KB Restore / Replication Runbook

This runbook is for proving Living IP KB/database redundancy on GCP.

The standby target already exists:

- project: `teleo-501523`
- instance: `teleo-pgvector-standby`
- database: `teleo_kb`
- region: `europe-west6`
- network: `teleo-staging-net`
- private IP: `10.61.0.3`
- admin password secret: `gcp-teleo-pgvector-standby-postgres-password`

Do not call this redundancy complete until source data has been restored or replicated and queried from GCP.

## Required Proof

A successful restore or replication canary must retain:

- source dataset identity:
  - source host or dump artifact;
  - dump timestamp or replication slot timestamp;
  - source schema/database name.
- transfer proof:
  - dump object path in a versioned bucket, or logical replication subscription details;
  - row/table counts before import where available.
- target proof:
  - `teleo-pgvector-standby` readback;
  - `teleo_kb` database readback;
  - extension readback for `vector` if the restored schema needs pgvector;
  - representative query readback for core KB tables.
- failure boundary:
  - exact missing secret, source access, schema incompatibility, extension issue, or import error.

## One-Shot Dump / Restore Path

Use this when the canonical DB remains outside GCP and we need a restore drill.

1. Export from source with a least-privilege read-only source credential.
2. Upload the dump to a versioned GCS bucket such as `gs://teleo-501523-prod-backups/kb-dumps/`.
3. Import into Cloud SQL:

```bash
gcloud sql import sql teleo-pgvector-standby \
  gs://teleo-501523-prod-backups/kb-dumps/<dump-file>.sql.gz \
  --project=teleo-501523 \
  --database=teleo_kb
```

4. From a trusted VPC runtime or Cloud SQL connector path, run readbacks:

```sql
select current_database();
select extname, extversion from pg_extension where extname = 'vector';
select schemaname, tablename from pg_tables where schemaname not in ('pg_catalog', 'information_schema') order by 1, 2 limit 50;
```

5. Retain the dump object generation, import operation, query output, and row-count sample.

## Logical Replication Path

Use this only after the source database owner approves replication permissions.

Required source privileges:

- replication-capable source user;
- publication over the intended schemas/tables;
- network path from GCP to source, or source-to-GCP path through an approved proxy/tunnel.

Required target steps:

```sql
create extension if not exists vector;
create subscription <subscription_name>
connection '<redacted source connection string>'
publication <publication_name>;
```

Retain only redacted connection metadata. Do not commit or paste credentials.

## Current Blocker

As of this run, GCP has the standby target but does not have an approved source KB/Postgres dump, source database credential, SSH tunnel credential, or logical replication credential. That is why the readiness checker still reports:

- `kb_source_restore_access = blocked`
- `kb_restore_or_replication = blocked`

The next real canary is:

source KB dump or replication credential -> import/replicate into `teleo_kb` -> run representative KB queries on GCP -> retain proof.