Component
core/datastore/timescaledb
A time-series database on the PostgreSQL engine: PostgreSQL with the TimescaleDB extension, which adds hypertables — tables partitioned by a time column — and a columnstore for analytical queries over time ranges. Wire here when data arrives ordered by time and is queried over spans of it — metrics, events, telemetry; core/datastore/postgres is the general-purpose relational store, and core/datastore/documentdb the document store on the same engine. It presents the standard PostgreSQL wire contract and exports its host, port, user, database and protocol, so any consumer that speaks PostgreSQL reaches it unchanged. Realized three ways, all self-hosted: a Helm Recipe synthesizing a StatefulSet, a Compose Recipe for local development, and a Helm Recipe emitting a Cluster custom resource for the CloudNativePG control plane. Reach for the synthesized Recipes where nothing is installed in the target cluster; reach for the controller-driven Recipe where that control plane is in place and the cluster can mount an image as a volume. Only that Recipe serves Prometheus metrics; the synthesized Recipes publish those keys empty. On Azure no realization is authored: Azure Database for PostgreSQL flexible server carries the extension's Apache-licensed edition, but nothing its API offers enables it in a database; only CREATE EXTENSION does. The managed path there is core/datastore/postgres on terraform/postgres-flexible-server, with infra.overrides.server_configuration setting azure.extensions to TIMESCALEDB and shared_preload_libraries to timescaledb, and the application running CREATE EXTENSION timescaledb in its database.
Походження
- Дайджест вмісту
- sha256:25477873aac1609a24de2f7c21f9120a82611f96e5310c74ef3e00fefaf449dd
- Опубліковано
- 2026-11-10T10:11:21Z
- Ідентичність підписувача
- https://token.actions.githubusercontent.com/https://github.com/aggrega-ai/aggrega-hub/.github/workflows/catalog-publish-sign.yml@refs/heads/main
Підпис
- Офіційнийapplication/vnd.dev.sigstore.bundle.v0.3+json
https://token.actions.githubusercontent.com/https://github.com/aggrega-ai/aggrega-hub/.github/workflows/catalog-publish-sign.yml@refs/heads/main
sha256:379cb74b07906f8f04cb9219c65ef8472b8ba66dff92776d78b383fff1a7241b
Посилання на цю версію
oci://hub.aggrega.ai/component/core/datastore/timescaledb:1.0.0Параметри розробника
Значення, які розробник задає в сутності Aggregate.
| Назва | Тип | Типове значення | Обов’язкове | Опис |
|---|---|---|---|---|
| database | string | appdb | ні | Logical database name created on startup (POSTGRES_DB). |
| user | string | appuser | ні | Bootstrap superuser role created on startup (POSTGRES_USER), owner of the initial database. |
| encoding | string | — | ні | Database encoding passed to initdb (e.g. UTF8). Omit to use the image default. |
| locale | string | — | ні | Database locale passed to initdb (e.g. en_US.utf8). Omit to use the image default. |
| custom_config | string | — | ні | Raw server configuration block (postgresql.conf format). Applied as the server's configuration file, so settings it omits keep their built-in defaults. One setting is not read from this block: the extension's library must be preloaded at server start or the server refuses to start, so the synthesized Recipes pass the preload list as a server option, which takes precedence over the configuration file. Name any further libraries in extra_preload_libraries rather than here. The controller-driven realization takes server configuration as named settings rather than as a file and halts the build when this is set, naming the key it offers instead. |
| extra_preload_libraries | string | — | ні | Additional shared libraries to preload at server start, as a comma-separated list (e.g. pg_stat_statements). The extension's own library is always preloaded and does not need naming here; entries given here are appended to it. Every realization honors this — the synthesized ones as a server option, the controller-driven one as the preload list on the Cluster custom resource. |
Розміри, задані оператором
Розміри інфраструктури, які оператор налаштовує для кожного середовища.
| Назва | Тип | Типове значення | Обов’язкове | Опис |
|---|---|---|---|---|
| port | integer (min 1024, max 65535) | 5432 | ні | Server listen port. Most operators should omit this and let the Recipe assign the default (5432). The controller-driven realization runs the server on 5432 and cannot move it, so it halts the build on any other value rather than handing a consumer a port the server does not answer on. |
| engine_version | string | 2.29.2-pg18-oss | ні | Server image tag the synthesized Recipes run. One compound coordinate carries three parts: the extension version, the PostgreSQL major version it is built against, and the edition suffix — so an operator supplies a value shaped like 2.29.2-pg18-oss rather than a bare major version. Dropping the -oss suffix selects the build that also carries the vendor-licensed shared objects. The controller-driven realization does not read this key: it runs a stock PostgreSQL server image and mounts the extension beside it as a second image, so its two coordinates are server_image and extension_image. |
| server_image | string | ghcr.io/cloudnative-pg/postgresql:18.6-minimal-trixie | ні | Full reference of the stock PostgreSQL server image the controller-driven realization runs. It carries no time-series extension of its own — the extension arrives as the separate image named in extension_image, which the controller mounts into this one. The two have to be built for the same PostgreSQL major version, operating-system distribution and processor architecture, or the extension's shared objects do not load, so the pair is chosen together. The default here is the build the default extension_image was itself built on: the CloudNativePG project builds its extension images on top of its own minimal PostgreSQL images, and the extension image records that base in its own metadata — PostgreSQL 18 on the Debian trixie base, the minimal build. So the reference has to name the minimal build specifically, not merely the right major version and base: a differently built image at the same major version and base presents a different set of shared libraries for the extension to link against. The default names a specific minor version rather than a tag that rolls, so the reference does not move under a Release. Set this key to move the pin — to another minor version, another base, or a digest reference — and move extension_image with it, since changing one side alone is what breaks the pairing. A build that sets this key empty halts naming it rather than emitting a Cluster with no server image. The synthesized Recipes ignore it and take their image from engine_version. |
| extension_image | string | ghcr.io/cloudnative-pg/timescaledb-oss:2.29.2-18-trixie | ні | Full reference of the image carrying the time-series extension, which the controller-driven realization mounts into server_image as a volume. The default names the Apache-licensed build the CloudNativePG project publishes at the extension version this component targets, for PostgreSQL 18 on the Debian trixie base — which is the pairing the default server_image already names, so the two defaults match without an operator choosing either. It is pinned by tag: an image mounted as a volume is resolved by the target cluster rather than by the build, so whether a digest reference resolves on that path is the operator's to check against their own cluster. Set this key to move the pin — to another extension version, another base, or a digest reference that cluster resolves — and move server_image with it. The synthesized Recipes ignore it. |
| compute | object | — | ні | — |
| storage | object | — | ні | — |
| overrides | object (open) | — | ні | Provider-specific overrides. Accepts any nested structure. Each Recipe documents which keys it reads. |
| control_plane_present | boolean | false | ні | Operator affirmation that the CloudNativePG control plane is installed in the target cluster. The controller-driven realization halts the build unless this is set true, so a Cluster custom resource is never emitted as an orphan into a cluster that cannot reconcile it. The synthesized realizations ignore this flag. |
| image_volumes_supported | boolean | false | ні | Operator affirmation that the target cluster can mount an image as a volume, which is how the controller-driven realization delivers the extension. Two things have to hold for it and neither implies the other: the cluster's ImageVolume feature, which is on by default from Kubernetes 1.35 and is enabled by hand on 1.33 and 1.34; and the container runtime the nodes run, which has to be containerd v2.1.0 or later, or CRI-O v1.31 or later. The runtime floor is a node-level one that no newer Kubernetes lifts, so check it against the nodes rather than reading it off the cluster version. The controller-driven realization halts the build unless this is set true, because an extension the cluster cannot mount leaves a server that starts without it. The synthesized realizations ignore this flag. |
| credentials | string (generated | supplied) | generated | ні | Who owns the database's credentials on the controller-driven realization. `generated` — the controller creates the Secret holding the owning role's password and owns it, which is what it does when nothing is supplied; the developer's `database` and `user` values are still honored, and no password reaches the rendered artifact. `supplied` — the controller reads that role's credentials from an existing Secret named in `credentials_secret` and generates none. The synthesized realizations ignore this key: they take the database password from the `password` credential slot. |
| credentials_secret | string | ні | Name of the existing Secret the controller-driven realization reads the database owner's credentials from when `credentials` is `supplied`. The Secret lives in the same namespace as the database, is of type `kubernetes.io/basic-auth`, and carries a `username` entry that must match `values.user` alongside a `password` entry holding that role's password. Leave it empty when `credentials` is `generated`; a controller-driven build halts if `supplied` is selected without it. |
Вихідний контракт
Значення, які цей компонент публікує для споживачів через топологію uses.
| Назва | Тип | Типове значення | Обов’язкове | Опис |
|---|---|---|---|---|
| host | string | — | так | Address a client opens its database connection to. On the in-cluster realizations it is the Service's DNS name. |
| port | integer | — | так | TCP port the server accepts connections on. It follows the port an operator set in the Release, so a consumer reads it rather than assuming 5432. |
| user | string | — | ні | Name of the login role a consumer authenticates as. The matching password arrives through the credential attached to the component, never through this contract. |
| database | string | — | ні | Name of the logical database created at startup. A consumer names it in its connection string to land in the right database rather than the server's default. |
| protocol | string | — | ні | Wire protocol the published address speaks — `postgres`, so a consumer reaches the time-series tables with an ordinary PostgreSQL driver. |
| metrics_pod_selector | string | — | ні | Kubernetes label selector matching every instance pod that serves the database's metrics, for a scraper that discovers those pods directly. Set by the controller-driven realization, beside `metrics_pod_port` and `metrics_path`; empty on the synthesized realizations, which serve no metrics. |
| metrics_pod_port | string | — | ні | Name of the container port on those pods that carries the metrics, `metrics`. Set and empty together with `metrics_pod_selector`. |
| metrics_path | string | — | ні | Path the metrics are served at on that port, `/metrics`. Set and empty together with `metrics_pod_selector`. |
Сокети uses
Сокети залежностей, через які під’єднується цей компонент. Ціль кожного з’єднання, прокладеного через сокет, має задовольняти його селектор міток, а кожне з’єднання може нести приєднання в слотах, які оголошує сокет. Обов’язковий слот має заповнити кожне з’єднання, яке сутність Aggregate або сутність Release прокладає через сокет.
Сокетів uses не оголошено.
Слоти приєднання
Іменовані точки прив’язки, у яких сутність Feature приєднується до цього компонента. Селектор слота обмежує, яка сутність Feature може його заповнити, а його список inject визначає, як можна доставити матеріал сутності Feature. Обов’язковий слот має бути прив’язаний у кожному екземплярі, приєднанням в екземплярі або в області вище за нього, а чутливий слот оголошено для роботи з секретним матеріалом. Сутність Feature також може приєднатися під назвою, яку не оголошує жоден слот.
| Слот | Селектор | Обов’язкове | Ін’єкція | Чутливий | Опис |
|---|---|---|---|---|---|
| password | feature.aggrega.ai/kind=secret | ні | env | так | Optional database password credential. When attached, supplies POSTGRES_PASSWORD via the credential subsystem. Unattached, compose/timescaledb and helm/timescaledb set POSTGRES_PASSWORD to the development literal `apppass`, which this catalog publishes, so every Release that leaves the slot unattached shares that password. The controller-driven realization owns the database's credentials through infra.credentials and halts the build when this slot is filled. |
Список дозволених самоін’єкцій
env
Зв’язки
Типізовані ребра до інших опублікованих сутностей і від них. Відсилання без опублікованої цілі відображається як розірване ребро, а не як посилання.
Використовує
Ця сутність не використовує нічого з каталогу.
Використовується в
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «queue»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «queue»
використовує сокет «backend»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «queue»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «queue»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «queue»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «state_store»
використовує сокет «checkpointer_db»
використовує сокет «checkpointer_db»
використовує сокет «backend»
використовує сокет «backend»
використовує сокет «backend»
використовує сокет «storage»
використовує сокет «metadata_store»
використовує сокет «target_datastore»
використовує сокет «backend»
використовує сокет «databases»
використовує сокет «etcd»
використовує сокет «backend»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «state_store»
використовує сокет «forward_target»
використовує сокет «backend»
використовує сокет «cache»
використовує сокет «chunk_cache»
використовує сокет «scrape_target»
використовує сокет «backend»
використовує сокет «backend»
використовує сокет «database»
застосовується до
застосовується до
застосовується до
реалізує
реалізує
реалізує