### Full server.yml Example (Teleport-relevant sections)

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

A comprehensive example of the `server.yml` configuration, highlighting sections relevant to Teleport integration, including database container, configs, and webhooks.

```yaml
databaseContainer: &db_container
  dockerImage: "postgresai/extended-postgres:16"
  containerConfig:
    "shm-size": 1gb
    volume: "/etc/dblab/certs:/var/lib/postgresql/cert:ro"

databaseConfigs: &db_configs
  configs:
    ssl: "on"
    ssl_cert_file: "/var/lib/postgresql/cert/server.crt"
    ssl_key_file: "/var/lib/postgresql/cert/server.key"
    ssl_ca_file: "/var/lib/postgresql/cert/teleport-ca.crt"

webhooks:
  hooks:
    - url: "http://host.docker.internal:9876/teleport-sync"
      secret: "your-webhook-secret"
      trigger:
        - clone_create
        - clone_delete
```

--------------------------------

### Next Steps Command Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example of concrete next steps commands after setup.

```bash
# Add server.yml snippets from step 7
# Restart DLE with -v pg_hba.conf:/home/dblab/standard/pg_hba.conf
# Trigger data refresh
# Start teleport agent
# Start sidecar with exact flags
```

--------------------------------

### pg_hba.conf Content Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example content for the pg_hba.conf file.

```text
# Managed by Database Lab Engine
local all all trust
hostssl all all cert
host all all md5
```

--------------------------------

### Teleport.yaml Configuration Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example configuration for teleport.yaml.

```yaml
proxy_server: "<teleport_proxy_addr>"
join_params:
  join_token: "<join_token>"
db_service:
  labels: {"dblab": "true"}
```

--------------------------------

### Install Docker (Linux Example)

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Provides commands to install Docker CE on a Linux system, including necessary dependencies.

```bash
# Install dependencies
sudo apt-get update && sudo apt-get install -y \
  apt-transport-https \
  ca-certificates \
  curl \
  gnupg-agent \
  software-properties-common
# Install Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) \
  stable"

sudo apt-get update && sudo apt-get install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io
```

--------------------------------

### Server.yml webhooks Snippet Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example snippet for server.yml to configure webhooks.

```yaml
webhooks:
  - url: "<webhook_url>"
    secret: "<webhook_secret>"
    triggers:
      - "*"
```

--------------------------------

### Install ZFS and Create Zpool (Linux Example)

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Commands to install ZFS and create a ZFS pool for storing Database Lab Engine data.

```bash
# Install ZFS
sudo apt-get install -y zfsutils-linux

sudo zpool create -f \
  -O compression=on \
  -O atime=off \
  -O recordsize=128k \
  -O logbias=throughput \
  -m /var/lib/dblab/dblab_pool \
  dblab_pool \
  "/dev/nvme1n1" # ! check your device or use an empty file here;
                 # empty file creation example: truncate --size 10GB ./pseudo-disk-for-zfs
```

--------------------------------

### SSL Certificate Generation Command Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example of generating SSL certificates using openssl.

```bash
openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key -subj "/CN=localhost"
chown 999:999 server.crt server.key
```

--------------------------------

### Server.yml databaseContainer Snippet Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example snippet for server.yml to configure database container volumes.

```yaml
databaseContainer:
  containerConfig:
    volume:
      - "/path/to/certs:/path/in/container/certs"
```

--------------------------------

### Running the Teleport Sidecar

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Command to start the DBLab Teleport sidecar, configuring its environment, proxy connection, identity, listen address, and DBLab integration.

```bash
dblab teleport serve \
  --environment-id production \
  --teleport-proxy teleport.example.com:3025 \
  --teleport-identity /etc/teleport/dblab-identity \
  --listen-addr 0.0.0.0:9876 \
  --dblab-url http://localhost:2345 \
  --dblab-token "$DBLAB_TOKEN" \
  --webhook-secret "$WEBHOOK_SECRET"
```

--------------------------------

### Teleport Role Creation Command Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example of how to ensure a Teleport role exists, creating it if it doesn't.

```go
func ensureRole(ctx context.Context, runner cmd.Runner, name string, yamlContent string) error {
	_, err := runner.Run("tctl get role/" + name)
	if err == nil {
		// Role already exists, skip
		return nil
	}

	// Role does not exist, create it
	cmd := fmt.Sprintf("tctl create -f - <<EOF\n%s\nEOF", yamlContent)
	_, err = runner.Run(cmd)
	if err != nil {
		return fmt.Errorf("failed to create role %s: %w", name, err)
	}
	return nil
}
```

--------------------------------

### Server.yml databaseConfigs Snippet Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example snippet for server.yml to configure database connection with SSL.

```yaml
databaseConfigs:
  - name: "mydatabase"
    protocol: "postgres"
    uri: "<db_host>:<db_port>"
    ssl: true
    ssl_cert_file: "/path/to/server.crt"
    ssl_key_file: "/path/to/server.key"
    ssl_ca_file: "/path/to/teleport-ca.crt"
```

--------------------------------

### Connecting to a Database Clone via Teleport

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Demonstrates how to log in to Teleport, list available databases (clones), and connect to a specific clone using `tsh`.

```bash
# Login to Teleport
tsh login --proxy=teleport.example.com

# List available databases (clones appear automatically)
tsh db ls

# Connect to a clone
tsh db connect dblab-clone-production-<clone-id>-6000 --db-user postgres --db-name postgres

# Or use a local tunnel (works with any psql client)
tsh proxy db --tunnel dblab-clone-production-<clone-id>-6000
```

--------------------------------

### Teleport Join Token Generation Command Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example of generating a Teleport join token.

```bash
tctl tokens add --type=db --ttl=8760h --format=json
```

--------------------------------

### Start Colima and Set Up ZFS

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Starts Colima and then executes an init script within Colima to set up ZFS utilities and create a ZFS pool for DBLab.

```bash
colima start

# Copy and run the ZFS init script inside Colima
colima ssh < engine/scripts/init-zfs-colima.sh
```

--------------------------------

### Portman Setup and Collection Generation

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Instructions for installing Portman and generating a Postman collection file.

```bash
npm install -g @apideck/portman
```

```bash
portman --cliOptionsFile engine/api/postman/portman-cli.json
```

--------------------------------

### Teleport Bot Identity Generation Command Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example of how to ensure a bot identity exists, creating it if it doesn't.

```go
func ensureBotIdentity(ctx context.Context, runner cmd.Runner, cfg *Config) error {
	identityPath := filepath.Join(cfg.IdentityDir, "bot.pem")
	if _, err := os.Stat(identityPath); err == nil {
		// Identity file already exists, skip
		return nil
	}

	// Check if bot exists but identity is missing
	_, err := runner.Run("tctl bots ls --format=json")
	if err != nil && !strings.Contains(err.Error(), "bot exists but identity missing") {
		return fmt.Errorf("failed to check for bot identity: %w", err)
	}

	// Add bot and get token
	token, err := runner.Run("tctl bots add dblab-sidecar --roles=dblab-bot --format=json")
	if err != nil {
		return fmt.Errorf("failed to add bot: %w", err)
	}

	// Start tbot with the token
	_, err = runner.Run(fmt.Sprintf("tbot start --oneshot --token=%s", strings.TrimSpace(token)))
	if err != nil {
		return fmt.Errorf("failed to start tbot: %w", err)
	}

	return nil
}
```

--------------------------------

### Teleport CA Export Command Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Example of exporting the Teleport CA for database clients.

```bash
tctl auth export --type=db-client > teleport-ca.crt
chown 999:999 teleport-ca.crt
```

--------------------------------

### Start DBLab UI

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Starts the DBLab UI container, connecting it to the DBLab server.

```bash
docker run -d --name dblab-ce-ui \
  -e DLE_HOST=host.docker.internal \
  -e DLE_PORT=2345 \
  -p 2346:80 \
  --add-host=host.docker.internal:host-gateway \
  dblab-ce-ui:arm64
```

--------------------------------

### Start DBLab Server

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Starts the DBLab server container with necessary volume mounts and privileged access.

```bash
docker run -d --name dblab-server \
  --privileged \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/dblab:/var/lib/dblab:rshared \
  -v /var/lib/docker:/var/lib/docker \
  -v /var/lib/dblab/configs:/home/dblab/configs \
  -e HOSTNAME=dblab-server \
  -p 2345:2345 \
  dblab_server:local
```

--------------------------------

### Platform UI Development Setup

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Steps to set up environment variables for Platform UI development.

```bash
cd ui/packages/platform
cp .env_example_dev .env
```

--------------------------------

### Install all dependencies

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/ui/README.md

Command to install all project dependencies.

```shell
pnpm install
```

--------------------------------

### UI Package Management

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Commands for installing dependencies, building all packages, and starting UI development servers.

```bash
pnpm install
```

```bash
npm run build -ws
```

```bash
npm run start -w @postgres.ai/platform
```

```bash
npm run start -w @postgres.ai/ce
```

--------------------------------

### Step execution flow

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Illustrates the sequence of operations performed by the `setupAction` function, from parsing flags to ensuring Teleport components and configurations are in place.

```go
setupAction(c *cli.Context)
├── parse flags → SetupConfig
├── checkTools(tctl, tbot, openssl)
├── [1/8] ensureRole("dblab-bot", dblabBotRoleYAML)
├── [2/8] ensureRole("dblab-user", dblabUserRoleYAML)
├── [3/8] ensureBotIdentity(cfg)
├── [4/8] ensureSSLCerts(cfg.CertDir)
├── [5/8] ensureTeleportCA(cfg.CertDir)
├── [6/8] ensurePgHba(cfg.PgHbaPath)
├── [7/8] printServerYmlSnippets(cfg)    // prints, does not edit
├── [8/8] ensureTeleportYaml(cfg)
└── printNextSteps(cfg)
```

--------------------------------

### Default pg_hba.conf for Certificate Authentication

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Shows the default `pg_hba.conf` rule that enables Teleport certificate authentication for SSL connections.

```text
local all all trust
hostssl all all 0.0.0.0/0 cert
host all all 0.0.0.0/0 md5
```

--------------------------------

### Start the development server with a custom proxy target

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/ui/README.md

Example of overriding the default proxy target for the development server using an environment variable.

```shell
VITE_DEV_PROXY_TARGET=https://demo.dblab.dev:446 pnpm --filter @postgres.ai/ce start
```

--------------------------------

### Start Development Server

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/ui/packages/platform/README.md

Specify REST API server URL with REACT_APP_API_SERVER environment variable.

```bash
npm install
npm run build
npm run start
```

--------------------------------

### Configure Webhook URL in server.yml

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Sets up the webhook URL in `server.yml` for DLE to send notifications to the Teleport sync endpoint.

```yaml
webhooks:
  hooks:
    - url: "http://host.docker.internal:9876/teleport-sync"
      secret: "your-webhook-secret"
      trigger:
        - clone_create
        - clone_delete
```

--------------------------------

### Self-hosted Teleport Bot Identity Generation

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Commands to add a bot and sign its identity for self-hosted Teleport instances.

```bash
tctl bots add dblab-sidecar --roles=dblab-bot
tctl auth sign --format=tls --user=bot-dblab-sidecar -o /etc/teleport/dblab-identity
```

--------------------------------

### SetupConfig struct

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Defines the configuration structure for the Teleport setup command, holding various parameters required for setting up Teleport and related components.

```go
type SetupConfig struct {
    TeleportProxy string
    CertDir       string
    PgHbaPath     string
    TeleportYaml  string
    IdentityDir   string
    EnvironmentID string
    WebhookAddr   string
    DblabURL      string
    DblabToken    string
    WebhookSecret string
}
```

--------------------------------

### Teleport Database Agent Configuration

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

YAML configuration for the Teleport agent to enable the db_service and specify dynamic resource matching for DBLab.

```yaml
# /etc/teleport.yaml (on the DBLab host)
db_service:
  enabled: true
  resources:
  - labels:
      dblab: "true"
```

--------------------------------

### Generate Self-Signed SSL/TLS Certificates for Postgres Clones

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Commands to generate self-signed SSL/TLS certificates required for DBLab clones to establish secure connections with Teleport.

```bash
openssl req -new -x509 -days 3650 -nodes \
  -out /etc/dblab/certs/server.crt \
  -keyout /etc/dblab/certs/server.key \
  -subj "/CN=dblab-clone"
```

--------------------------------

### Building Specific Components

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Examples of building specific components of the Database Lab Engine using Makefile targets.

```bash
# Build the CLI for all supported platforms
make build-client

# Build the Server in debug mode
make build-debug

# Build and run DLE locally
make run-dle
```

--------------------------------

### Minimal DBLab Server Configuration

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

A minimal example configuration file for DBLab Engine.

```yaml
server:
  verificationToken: "your_token_here"
  host: "0.0.0.0"
  port: 2345

embeddedUI:
  enabled: false  # We'll run UI separately for ARM64

global:
  engine: postgres
  debug: true
  database:
    username: postgres
    dbname: postgres

poolManager:
  mountDir: /var/lib/dblab/dblab_pool
  dataSubDir: ""
  clonesMountSubDir: clones
  socketSubDir: sockets
  observerSubDir: observer
  preSnapshotSuffix: "_pre"
  selectedPool: "dataset_1"

databaseContainer:
  dockerImage: "dblab-postgres:17-arm64"
  containerConfig:
    "shm-size": 256mb

provision:
  portPool:
    from: 6000
    to: 6010
  useSudo: false
  keepUserPasswords: true
  cloneAccessAddresses: "127.0.0.1"

retrieval:
  refresh:
    timetable: ""
  jobs:
    - physicalSnapshot
  spec:
    physicalSnapshot:
      options:
        skipStartSnapshot: false
        promotion:
          enabled: false

cloning:
  accessHost: "localhost"
  maxIdleMinutes: 60

platform:
  enableTelemetry: false
```

--------------------------------

### Teleport Cloud Bot Identity Generation

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Commands to add a bot and generate its identity for Teleport Cloud, using a token and the tbot utility.

```bash
tctl bots add dblab-sidecar --roles=dblab-bot
tbot start --oneshot \
  --token=<TOKEN> \
  --proxy-server=yourcluster.teleport.sh:443 \
  --join-method=token \
  --data-dir=/etc/teleport/bot-data \
  --destination-dir=/etc/teleport/bot-dest
# The identity file is at /etc/teleport/bot-dest/identity
```

--------------------------------

### Volume Mounting for Certificates in server.yml

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Configures the volume mount for SSL certificates within the `server.yml` file, mapping host certificates to the container's expected path.

```yaml
databaseContainer:
  dockerImage: "postgresai/extended-postgres:16"
  containerConfig:
    "shm-size": 1gb
    volume: "/etc/dblab/certs:/var/lib/postgresql/cert:ro"
```

--------------------------------

### Pre-commit Hooks Installation

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Commands to install pre-commit and its hooks for secret detection.

```bash
pip install pre-commit
# or: brew install pre-commit

pre-commit install
```

--------------------------------

### Add SSL Configuration to server.yml

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Configures SSL settings in the `server.yml` file, specifying the paths for the server certificate, private key, and the Teleport CA certificate.

```yaml
databaseConfigs:
  configs:
    ssl: "on"
    ssl_cert_file: "/var/lib/postgresql/cert/server.crt"
    ssl_key_file: "/var/lib/postgresql/cert/server.key"
    ssl_ca_file: "/var/lib/postgresql/cert/teleport-ca.crt"
```

--------------------------------

### Import Organization Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CLAUDE.md

Example of correct import organization in Go code.

```go
import (
    "context"
    "fmt"
    "net/http"

    "github.com/docker/docker/api/types"
    "github.com/gorilla/mux"

    "gitlab.com/postgres-ai/database-lab/v3/pkg/util/branching"
)
```

--------------------------------

### Progress Indication Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Demonstrates the recommended sequence for indicating progress in CLI output, including an in-progress message and a success message.

```bash
Creating clone...
Clone "test-clone" created successfully.
```

--------------------------------

### Tagging a commit for UI deployment

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/ui/README.md

Example of how to tag a commit with a 'ui/' prefix and push it for UI changes deployment.

```shell
git tag ui/1.0.12
git push origin ui/1.0.12
```

--------------------------------

### OpenTelemetry Collector Configuration Example

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/PROMETHEUS.md

Example configuration snippet for the OpenTelemetry Collector, showing how to set the OTLP exporter endpoint and headers.

```yaml
exporters:
  otlp:
    endpoint: "your-otlp-endpoint:4317"
    headers:
      Authorization: "Bearer <your-token>"
```

--------------------------------

### Command Runner Interface

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260319-teleport-setup-command.md

Defines an interface for executing external commands, allowing for mocking in tests.

```go
type cmdRunner interface {
	Run(ctx context.Context, name string, args ...string) ([]byte, error)
}
```

--------------------------------

### Run the Community Edition UI locally in development mode

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/ui/README.md

Command to start the development server for the Community Edition UI.

```shell
pnpm --filter @postgres.ai/ce start
```

--------------------------------

### Example Commit Message Structure

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/CONTRIBUTING.md

Illustrates the recommended structure for Git commit messages, including a subject line and a detailed body.

```git
fix: correct null pointer dereference

When the user is not authorized, the code used to panic. This commit
reverts the change that caused this behavior and adds a check for
authorization.

Closes #123
```

--------------------------------

### Quick Start Configuration and Execution

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/rds-refresh/README.md

This snippet shows how to configure the rds-refresh tool using a YAML file and then run it with Docker, including a dry-run option.

```yaml
source:
  type: rds                    # or "aurora-cluster"
  identifier: my-prod-db
  dbName: postgres
  username: postgres
  password: ${DB_PASSWORD}

clone:
  instanceClass: db.t3.medium
  securityGroups: [sg-xxx]     # must allow DBLab inbound

dblab:
  apiEndpoint: https://dblab:2345
  token: ${DBLAB_TOKEN}

aws:
  region: us-east-1
```

```bash
# 1. Configure
cat > config.yaml << 'EOF' 
# ... (yaml content above) ...
EOF

# 2. Test
docker run --rm \
  -v $PWD/config.yaml:/config.yaml \
  -e DB_PASSWORD -e DBLAB_TOKEN -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  postgresai/rds-refresh -config /config.yaml -dry-run

# 3. Run
docker run --rm \
  -v $PWD/config.yaml:/config.yaml \
  -e DB_PASSWORD -e DBLAB_TOKEN -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  postgresai/rds-refresh -config /config.yaml
```

--------------------------------

### Build and Initialize DBLab CLI

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Builds the DBLab client and initializes the CLI to connect to the DBLab server.

```bash
cd engine && make build-client

dblab init \
  --url http://localhost:2345 \
  --token your_token_here \
  --environment-id local
```

--------------------------------

### Initialize PostgreSQL Data on ZFS

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Runs a PostgreSQL container to initialize data on the ZFS dataset and then creates an initial ZFS snapshot.

```bash
docker run -d --name pg-init \
  -e POSTGRES_PASSWORD=postgres \
  -v /var/lib/dblab/dblab_pool/dataset_1:/var/lib/postgresql/data \
  postgres:17-bookworm

# Wait for initialization to complete
docker logs -f pg-init
# Press Ctrl+C once you see "database system is ready to accept connections"

# Stop and remove the init container
docker stop pg-init && docker rm pg-init

# Create the initial snapshot
colima ssh -- sudo zfs snapshot dblab_pool/dataset_1@initial_data
```

--------------------------------

### User Role for Database Access

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

This YAML defines a role for Teleport users, granting them access to DBLab-managed databases based on specific labels.

```yaml
kind: role
version: v7
metadata:
  name: dblab-user
spec:
  allow:
    db_labels:
      dblab: "true"
    db_names: ['*']
    db_users: ['*']
```

--------------------------------

### Go Unit Tests

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260402-dependency-upgrades-cve-fixes.md

Run Go unit tests.

```bash
cd engine && make test
```

--------------------------------

### Teleport Bot Role Permissions

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

This YAML defines the necessary permissions for the bot role, allowing it to manage database and application resources within Teleport.

```yaml
kind: role
version: v7
metadata:
  name: dblab-bot
spec:
  allow:
    db_labels:
      '*': '*'
    db_names: ['*']
    db_users: ['*']
    rules:
    - resources: [db, db_server]
      verbs: [list, create, read, update, delete]
    - resources: [app, app_server]
      verbs: [list, create, read, update, delete]
```

--------------------------------

### Copy Configuration to Colima VM

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Copies the server configuration file into the Colima virtual machine.

```bash
colima ssh -- mkdir -p /var/lib/dblab/configs
colima ssh -- tee /var/lib/dblab/configs/server.yml < configs/server.yml > /dev/null
```

--------------------------------

### Go Linter

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260402-dependency-upgrades-cve-fixes.md

Run Go linter.

```bash
cd engine && make run-lint
```

--------------------------------

### Set Permissions for Server Certificates

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Ensures that the server certificate and key files are owned by the postgres user (UID 999) and have restricted permissions for the private key.

```bash
chown 999:999 /etc/dblab/certs/server.crt /etc/dblab/certs/server.key
chmod 600 /etc/dblab/certs/server.key
```

--------------------------------

### Initialize Supabase Postgres Instance

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Docker command to run a Supabase-managed PostgreSQL instance for DBLab data initialization.

```bash
docker run -d --name supabase-pg-init \
  -e POSTGRES_PASSWORD=postgres \
  -v /var/lib/dblab/dblab_pool/dataset_1:/var/lib/postgresql/data \
  -p 5433:5432 \
  public.ecr.aws/supabase/postgres:17.6.1.064
```

--------------------------------

### Export and Set Permissions for Teleport DB CA Certificate

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/cli/commands/teleport/SETUP.md

Exports the Teleport DB CA certificate and sets its ownership to the postgres user, which is necessary for PostgreSQL to verify client certificates.

```bash
tctl auth export --type=db-client > /etc/dblab/certs/teleport-ca.crt
chown 999:999 /etc/dblab/certs/teleport-ca.crt
```

--------------------------------

### UI Build Verification

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260402-dependency-upgrades-cve-fixes.md

Build the UI.

```bash
cd ui && pnpm install && pnpm --filter @postgres.ai/ce build
```

--------------------------------

### Go Integration Tests

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/plans/20260402-dependency-upgrades-cve-fixes.md

Run Go integration tests.

```bash
cd engine && make test-ci-integration
```

--------------------------------

### Clones by Status Query

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/PROMETHEUS.md

PromQL query to get clone counts categorized by their status.

```promql
dblab_clones_by_status
```

--------------------------------

### Build ARM64 PostgreSQL Docker Image

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Builds the ARM64 PostgreSQL Docker image using the custom Dockerfile.

```bash
docker build -f Dockerfile.dblab-postgres-arm64 \
  --platform linux/arm64 \
  -t dblab-postgres:17-arm64 .
```

--------------------------------

### Scheduling with Cron

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/engine/cmd/rds-refresh/README.md

Example of how to schedule the RDS/Aurora refresh task using a cron job.

```bash
# Cron (weekly, Sunday 2 AM)
0 2 * * 0 docker run --rm -v /etc/dblab/config.yaml:/config.yaml \
  --env-file /etc/dblab/env postgresai/rds-refresh -config /config.yaml
```

--------------------------------

### Number of Active Clones Query

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/PROMETHEUS.md

PromQL query to get the total number of active clones.

```promql
dblab_clones_total
```

--------------------------------

### Build ARM64 DBLab CE UI Image

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Builds the DBLab CE UI Docker image for ARM64 architecture.

```bash
docker build -f ui/packages/ce/Dockerfile \
  --platform linux/arm64 \
  -t dblab-ce-ui:arm64 .
```

--------------------------------

### Build ARM64 DBLab Server Image

Source: https://github.com/postgres-ai/database-lab-engine/blob/master/docs/colima-supabase-setup.md

Builds the DBLab server binary for ARM64 and creates a Docker image tagged 'dblab_server:local'.

```bash
cd engine
GOOS=linux GOARCH=arm64 make build
make build-image
```