# KingbaseES V8 in Docker

Specific notes for running KingbaseES V8 (人大金仓) in Docker containers.

## Image

```bash
docker pull gaofenglongshao/kingbasev8:0429
```

May be private — check Docker Hub visibility settings if pull fails. User had to change from Private to Public in Docker Hub repo Settings.

## Environment Variables

The entrypoint script uses these (NOT `KINGBASE_USER`/`KINGBASE_PASSWORD`):

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_USER` | `system` | Database superuser |
| `DB_PASSWORD` | (base64 encoded) | User password |
| `PASSWORD` | (base64 encoded) | Fallback if `DB_PASSWORD` not set |
| `DATA_DIR` | `/home/kingbase/userdata/data` | Data directory |
| `DB_MODE` | `oracle` | Compatibility mode (`oracle` or `pg`) |
| `ENCODING` | `UTF-8` | Database encoding |
| `ENABLE_CI` | `yes` | Case-insensitive mode |

Default password decoded: `12345678abk` (from `MTIzNDU2NzhhYgo=` base64).

## Running

```bash
docker run -d \
  --name kingbasev8 \
  --user kingbase \
  -p 54321:54321 \
  -e DB_USER=ywkuser \
  -e DB_PASSWORD=123 \
  gaofenglongshao/kingbasev8:0429
```

**Do NOT use `--user root`** — `initdb` refuses to run as root.
**Do NOT use `--privileged` with `--user root`** — same reason.

## sudo PAM Errors

The entrypoint script uses `sudo` for cron/logrotate setup. These errors are **non-critical**:
```
sudo: pam_open_session: Permission denied
sudo: policy plugin failed session initialization
```

The database starts fine despite these. Only the cron job for auto-restart is affected.

## Tools (inside container)

Source `/etc/profile` before running any tool:

```bash
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/ksql -U username -d dbname -c "SQL"'
```

| Tool | Path | Purpose |
|------|------|---------|
| `ksql` | `/home/kingbase/install/kingbase/bin/ksql` | SQL client (like psql) |
| `sys_restore` | `/home/kingbase/install/kingbase/bin/sys_restore` | Restore .dmp backups |
| `sys_dump` | `/home/kingbase/install/kingbase/bin/sys_dump` | Create backups |
| `sys_ctl` | `/home/kingbase/install/kingbase/bin/sys_ctl` | Start/stop database |
| `initdb` | `/home/kingbase/install/kingbase/bin/initdb` | Initialize database |

## Restoring .dmp Files

KingbaseES uses a proprietary binary dump format (header: `KEMDP`).

### Preview dump contents before restoring

```bash
# List all objects in the dump (schemas, tables, functions, etc.)
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/sys_restore -l /tmp/DB.dmp | head -60'
```

This shows TOC entries: schema names, table counts, function names — useful to verify the dump contains what you expect before restoring.

### Full restore

```bash
# Copy into container
docker cp DB_2026-04-28.dmp kingbasev8:/tmp/DB.dmp

# Restore (use --no-owner to avoid role issues)
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/sys_restore -U ywkuser -d yfywk --no-owner /tmp/DB.dmp'
```

### Schema-only restore (skip data, only create DDL objects)

```bash
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/sys_restore -U ywkuser -d yfywk --schema-only --no-owner --no-privileges -v /tmp/DB.dmp'
```

Useful when target DB already has data and you only need to add missing table structures, views, and functions. Objects that already exist will produce "already exists" errors (non-fatal with `-v`), while new objects are created normally. Combine with `-v` for verbose output to see which objects are created vs skipped.

If objects already exist, drop and recreate the database first:
```bash
# Terminate connections
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/ksql -U ywkuser -d test -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '"'"'yfywk'"'"' AND pid <> pg_backend_pid();"'

# Drop and recreate
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/ksql -U ywkuser -d test -c "DROP DATABASE yfywk;"'
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/ksql -U ywkuser -d test -c "CREATE DATABASE yfywk;"'

# Restore again
docker exec kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/sys_restore -U ywkuser -d yfywk --no-owner /tmp/DB.dmp'
```

## Default Port

KingbaseES default port: **54321** (not 5432 like PostgreSQL)

## Connection

```bash
# From host
ksql -h 127.0.0.1 -p 54321 -U ywkuser -d yfywk

# From container
docker exec -it kingbasev8 bash -c 'source /etc/profile && /home/kingbase/install/kingbase/bin/ksql -U ywkuser -d yfywk'
```

## Version Info

From this session:
```
KingbaseES V008R006C009B0014 on x86_64-pc-linux-gnu
```