etcd_fdw

Foreign data wrapper for etcd

Overview

PackageVersionCategoryLicenseLanguage
etcd_fdw0.0.0FDWMITRust
IDExtensionBinLibLoadCreateTrustRelocSchema
8660etcd_fdwNoYesNoYesNoNo-
Relatedwrappers redis_fdw kafka_fdw postgres_fdw mysql_fdw mongo_fdw

Version

TypeRepoVersionPG VerPackageDeps
EXTPIGSTY0.0.01817161514etcd_fdw-
RPMPIGSTY0.0.01817161514etcd_fdw_$v-
DEBPIGSTY0.0.01817161514postgresql-$v-etcd-fdw-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64
el8.aarch64
el9.x86_64
el9.aarch64
el10.x86_64
el10.aarch64
d12.x86_64
d12.aarch64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
d13.x86_64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
d13.aarch64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
u22.x86_64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
u22.aarch64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
u24.x86_64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
u24.aarch64
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0
PIGSTY 0.0.0

Build

You can build the RPM / DEB packages for etcd_fdw using pig build:

pig build pkg etcd_fdw         # build RPM / DEB packages

Install

You can install etcd_fdw directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install etcd_fdw;          # Install for current active PG version
pig ext install -y etcd_fdw -v 18  # PG 18
pig ext install -y etcd_fdw -v 17  # PG 17
pig ext install -y etcd_fdw -v 16  # PG 16
pig ext install -y etcd_fdw -v 15  # PG 15
pig ext install -y etcd_fdw -v 14  # PG 14
dnf install -y etcd_fdw_18       # PG 18
dnf install -y etcd_fdw_17       # PG 17
dnf install -y etcd_fdw_16       # PG 16
dnf install -y etcd_fdw_15       # PG 15
dnf install -y etcd_fdw_14       # PG 14
apt install -y postgresql-18-etcd-fdw   # PG 18
apt install -y postgresql-17-etcd-fdw   # PG 17
apt install -y postgresql-16-etcd-fdw   # PG 16
apt install -y postgresql-15-etcd-fdw   # PG 15
apt install -y postgresql-14-etcd-fdw   # PG 14

Create Extension:

CREATE EXTENSION etcd_fdw;

Usage


Quick Start

1. Enable Extension

CREATE EXTENSION etcd_fdw;

2. Create Foreign Data Wrapper

CREATE FOREIGN DATA WRAPPER etcd_fdw
  HANDLER etcd_fdw_handler
  VALIDATOR etcd_fdw_validator;

3. Create Server

-- Basic connection
CREATE SERVER etcd_plain
  FOREIGN DATA WRAPPER etcd_fdw
  OPTIONS (connstr '127.0.0.1:2379');

-- Production etcd with authentication and SSL
CREATE SERVER etcd FOREIGN DATA WRAPPER etcd_fdw OPTIONS (
    connstr '127.0.0.1:2379',
    username 'root',
    password 'Etcd.Root',
    ssl_ca '/pg/cert/ca.crt',
    ssl_cert '/pg/cert/server.crt',
    ssl_key '/pg/cert/server.key'
);

4. Create Foreign Table

-- Basic table mapping all keys
CREATE FOREIGN TABLE etcd_kv (key TEXT, value TEXT) SERVER etcd OPTIONS (rowid_column 'key');

-- Table with prefix filter (only keys starting with '/config/')
CREATE FOREIGN TABLE etcd_config (key TEXT, value TEXT)
  SERVER etcd OPTIONS (rowid_column 'key', prefix '/config/');

5. Query Data

-- Read all keys
SELECT * FROM etcd_kv;

-- Filter by key pattern (pushdown supported)
SELECT * FROM etcd_kv WHERE key LIKE '/app/%';

-- Range query
SELECT * FROM etcd_kv WHERE key >= '/a' AND key < '/b';

-- Insert new key
INSERT INTO etcd_kv (key, value) VALUES ('/mykey', 'myvalue');

-- Delete key
DELETE FROM etcd_kv WHERE key = '/mykey';

6. Real-time Sync with etcd

Changes made outside PostgreSQL are immediately visible:

# Insert via etcdctl
etcdctl put '/config/db_pool_size' '20'
-- Instantly visible in PostgreSQL
SELECT * FROM etcd_config;
     key               | value
-----------------------+-------
 /config/db_pool_size  | 20
(1 row)

Reference

Server Options

OptionRequiredDescription
connstrYesetcd endpoint (e.g., 127.0.0.1:2379)
usernameNoAuthentication username
passwordNoAuthentication password
ssl_caNoCA certificate file path
ssl_certNoClient certificate file path
ssl_keyNoClient private key file path
ssl_servernameNoDomain name for TLS verification
connect_timeoutNoConnection timeout (default: 10s)
request_timeoutNoRequest timeout (default: 30s)

Foreign Table Options

OptionDefaultDescription
rowid_columnRequiredColumn used as unique row identifier
prefixNoneRestrict to keys with this prefix
keys_onlyfalseFetch only keys, skip values
revision0Read at specific etcd revision
key\0Starting key for range scan
range_endNoneExclusive end key for range scan
consistencyll (linearizable) or s (serializable)

Query Pushdown

The following operations are pushed down to etcd for better performance:

  • WHERE: =, >=, >, <=, <, BETWEEN, LIKE 'prefix%'
  • ORDER BY: Remote sorting
  • LIMIT/OFFSET: Remote pagination

Limitations

  • UPDATE on key column is not supported. Workaround: INSERT new key, then DELETE old key.
  • Requires etcd v3 API.

Last Modified 2026-03-12: add pg extension catalog (95749bf)