> ## Documentation Index
> Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-97.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata overview

> Stores and services engine metadata.

# Metadata service

The metadata service stores and serves engine metadata. It uses PostgreSQL as the backing database. Engines connect to it at startup and during operation so they can read the account and engine state they need to run queries.

**Experimental:** `spec.metadataNG: true` selects metadata-ng configuration and UID/GID, but does not select the metadata image. When `imagePullPolicy` is unset it also defaults the metadata container to `Always`, so a floating tag such as `pd-dev` is re-pulled instead of pinning a node to its first cached digest. Legacy behavior remains the default.

The two services read different configuration documents. The legacy service reads a `pensieve_lite` document; metadata-ng reads a `pensieve_duck` document carrying only the listen address and the PostgreSQL `host`, `port`, and `database`, and rejects any other key at startup. `spec.id` and `spec.metadata.postgres.schema` are not rendered for metadata-ng: the service is isolated by the configured database and lays its catalog out across its own schemas inside it, so a custom `schema` has no effect with `metadataNG: true`.

## External PostgreSQL TLS

To verify an external PostgreSQL server certificate and hostname, configure
`spec.metadata.postgres.tls`:

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
spec:
  metadata:
    postgres:
      host: postgres.example.com
      database: metadata
      credentialsSecretRef:
        name: postgres-credentials
      tls:
        mode: verify-full
        caSecretRef:
          name: postgres-ca
          key: ca.crt
```

Create the CA Secret in the FireboltInstance namespace. The Firebolt Operator
mounts only the selected key into the Metadata container. Updating the
credentials Secret or CA Secret rolls the Metadata pod.

## Rolling update parameters

### Metadata deployment

| Parameter        | Value                     | Rationale                                                                                             |
| ---------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `maxSurge`       | `0`                       | Never run two metadata pods concurrently. The metadata service assumes single-writer against Postgres |
| `maxUnavailable` | `1`                       | Old pod is terminated before the new one starts. Brief metadata-unavailable window during rollouts    |
| Replicas         | `1` (enforced by webhook) | Multi-replica metadata is not currently supported                                                     |