Add PostgreSQL storage backend

Add a PostgresStore implementation behind the "postgres" feature
flag, mirroring the existing SqliteStore. Uses tokio-postgres
(async-native) with an internal tokio runtime for the sync
KVStoreSync trait, following the VssStore pattern.

Includes unit tests, integration tests (channel full cycle and
node restart), and a CI workflow that runs both against a
PostgreSQL service container.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: benthecarman

.github/workflows/postgres-integration.yml

@@ -0,0 +1,65 @@
+name: CI Checks - PostgreSQL Integration Tests
+
+on: [ push, pull_request ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:latest
+        ports:
+          - 5432:5432
+        env:
+          POSTGRES_DB: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+      - name: Install Rust stable toolchain
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile=minimal --default-toolchain stable
+      - name: Enable caching for bitcoind
+        id: cache-bitcoind
+        uses: actions/cache@v4
+        with:
+          path: bin/bitcoind-${{ runner.os }}-${{ runner.arch }}
+          key: bitcoind-27_2-${{ runner.os }}-${{ runner.arch }}
+      - name: Enable caching for electrs
+        id: cache-electrs
+        uses: actions/cache@v4
+        with:
+          path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
+          key: electrs-esplora_a33e97e1-${{ runner.os }}-${{ runner.arch }}
+      - name: Download bitcoind/electrs
+        if: "steps.cache-bitcoind.outputs.cache-hit != 'true' || steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./scripts/download_bitcoind_electrs.sh
+          mkdir -p bin
+          mv "$BITCOIND_EXE" bin/bitcoind-${{ runner.os }}-${{ runner.arch }}
+          mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
+      - name: Set bitcoind/electrs environment variables
+        run: |
+          echo "BITCOIND_EXE=$( pwd )/bin/bitcoind-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
+          echo "ELECTRS_EXE=$( pwd )/bin/electrs-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
+      - name: Run PostgreSQL store tests
+        env:
+          TEST_POSTGRES_URL: "host=localhost user=postgres password=postgres"
+        run: cargo test --features postgres io::postgres_store
+      - name: Run PostgreSQL integration tests
+        env:
+          TEST_POSTGRES_URL: "host=localhost user=postgres password=postgres"
+        run: |
+          RUSTFLAGS="--cfg no_download --cfg cycle_tests" cargo test --features postgres --test integration_tests_postgres

Cargo.toml

@@ -25,6 +25,7 @@ panic = 'abort'     # Abort on panic
 
 [features]
 default = []
+postgres = ["dep:tokio-postgres", "dep:native-tls", "dep:postgres-native-tls"]
 
 [dependencies]
 #lightning = { version = "0.2.0", features = ["std"] }
@@ -78,6 +79,9 @@ serde_json = { version = "1.0.128", default-features = false, features = ["std"]
 log = { version = "0.4.22", default-features = false, features = ["std"]}
 
 async-trait = { version = "0.1", default-features = false }
+tokio-postgres = { version = "0.7", default-features = false, features = ["runtime"], optional = true }
+native-tls = { version = "0.2", default-features = false, optional = true }
+postgres-native-tls = { version = "0.5", default-features = false, features = ["runtime"], optional = true }
 vss-client = { package = "vss-client-ng", version = "0.5" }
 prost = { version = "0.11.6", default-features = false}
 #bitcoin-payment-instructions = { version = "0.6" }

bindings/ldk_node.udl

@@ -64,6 +64,8 @@ interface Builder {
 	[Throws=BuildError]
 	Node build(NodeEntropy node_entropy);
 	[Throws=BuildError]
+	Node build_with_postgres_store(NodeEntropy node_entropy, string connection_string, string? db_name, string? kv_table_name, PostgresTlsConfig? tls_config);
+	[Throws=BuildError]
 	Node build_with_fs_store(NodeEntropy node_entropy);
 	[Throws=BuildError]
 	Node build_with_vss_store(NodeEntropy node_entropy, string vss_url, string store_id, record<string, string> fixed_headers);
@@ -267,6 +269,11 @@ dictionary RouteParametersConfig {
 	u8 max_channel_saturation_power_of_half;
 };
 
+[Remote]
+dictionary PostgresTlsConfig {
+	string? certificate_pem;
+};
+
 [Remote]
 dictionary LSPS1OrderStatus {
 	LSPS1OrderId order_id;

src/builder.rs

@@ -640,6 +640,44 @@ impl NodeBuilder {
 		self.build_with_store(node_entropy, kv_store)
 	}
 
+	/// Builds a [`Node`] instance with a [PostgreSQL] backend and according to the options
+	/// previously configured.
+	///
+	/// Connects to the PostgreSQL database at the given `connection_string`, e.g.,
+	/// `"postgres://user:password@localhost/ldk_db"`.
+	///
+	/// The given `db_name` will be used or default to
+	/// [`DEFAULT_DB_NAME`](io::postgres_store::DEFAULT_DB_NAME). The `connection_string` must
+	/// not include a `dbname` when `db_name` is set, providing both is an error. The database
+	/// will be created automatically if it doesn't already exist. The initial connection is
+	/// made to the target database, and if it fails we fall back to the default `postgres`
+	/// database to create it.
+	///
+	/// The given `kv_table_name` will be used or default to
+	/// [`DEFAULT_KV_TABLE_NAME`](io::postgres_store::DEFAULT_KV_TABLE_NAME).
+	///
+	/// If `tls_config` is `Some`, TLS will be used for database connections. A custom CA
+	/// certificate can be provided via
+	/// [`PostgresTlsConfig::certificate_pem`](io::postgres_store::PostgresTlsConfig::certificate_pem),
+	/// which will be added to the system's default root certificates (not replace them).
+	/// If `tls_config` is `None`, connections will be unencrypted.
+	///
+	/// [PostgreSQL]: https://www.postgresql.org
+	#[cfg(feature = "postgres")]
+	pub fn build_with_postgres_store(
+		&self, node_entropy: NodeEntropy, connection_string: String, db_name: Option<String>,
+		kv_table_name: Option<String>, tls_config: Option<io::postgres_store::PostgresTlsConfig>,
+	) -> Result<Node, BuildError> {
+		let kv_store = io::postgres_store::PostgresStore::new(
+			connection_string,
+			db_name,
+			kv_table_name,
+			tls_config,
+		)
+		.map_err(|_| BuildError::KVStoreSetupFailed)?;
+		self.build_with_store(node_entropy, kv_store)
+	}
+
 	/// Builds a [`Node`] instance with a [`FilesystemStore`] backend and according to the options
 	/// previously configured.
 	pub fn build_with_fs_store(&self, node_entropy: NodeEntropy) -> Result<Node, BuildError> {
@@ -1102,6 +1140,60 @@ impl ArcedNodeBuilder {
 		self.inner.read().expect("lock").build(*node_entropy).map(Arc::new)
 	}
 
+	/// Builds a [`Node`] instance with a [PostgreSQL] backend and according to the options
+	/// previously configured.
+	///
+	/// Connects to the PostgreSQL database at the given `connection_string`, e.g.,
+	/// `"postgres://user:password@localhost/ldk_db"`.
+	///
+	/// The given `db_name` will be used or default to
+	/// [`DEFAULT_DB_NAME`](io::postgres_store::DEFAULT_DB_NAME). The `connection_string` must
+	/// not include a `dbname` when `db_name` is set, providing both is an error. The database
+	/// will be created automatically if it doesn't already exist. The initial connection is
+	/// made to the target database, and if it fails we fall back to the default `postgres`
+	/// database to create it.
+	///
+	/// The given `kv_table_name` will be used or default to
+	/// [`DEFAULT_KV_TABLE_NAME`](io::postgres_store::DEFAULT_KV_TABLE_NAME).
+	///
+	/// If `tls_config` is `Some`, TLS will be used for database connections. A custom CA
+	/// certificate can be provided via
+	/// [`PostgresTlsConfig::certificate_pem`](io::postgres_store::PostgresTlsConfig::certificate_pem),
+	/// which will be added to the system's default root certificates (not replace them).
+	/// If `tls_config` is `None`, connections will be unencrypted.
+	///
+	/// [PostgreSQL]: https://www.postgresql.org
+	#[cfg(feature = "postgres")]
+	pub fn build_with_postgres_store(
+		&self, node_entropy: Arc<NodeEntropy>, connection_string: String, db_name: Option<String>,
+		kv_table_name: Option<String>, tls_config: Option<io::postgres_store::PostgresTlsConfig>,
+	) -> Result<Arc<Node>, BuildError> {
+		self.inner
+			.read()
+			.unwrap()
+			.build_with_postgres_store(
+				*node_entropy,
+				connection_string,
+				db_name,
+				kv_table_name,
+				tls_config,
+			)
+			.map(Arc::new)
+	}
+
+	/// Builds a [`Node`] instance with a [PostgreSQL] backend and according to the options
+	/// previously configured.
+	///
+	/// This requires the `postgres` crate feature.
+	#[cfg(not(feature = "postgres"))]
+	pub fn build_with_postgres_store(
+		&self, _node_entropy: Arc<NodeEntropy>, _connection_string: String,
+		_db_name: Option<String>, _kv_table_name: Option<String>,
+		_tls_config: Option<io::PostgresTlsConfig>,
+	) -> Result<Arc<Node>, BuildError> {
+		Err(BuildError::KVStoreSetupFailed)
+	}
+
 	/// Builds a [`Node`] instance with a [`FilesystemStore`] backend and according to the options
 	/// previously configured.
 	pub fn build_with_fs_store(

src/ffi/types.rs

@@ -46,6 +46,9 @@ pub use lightning_liquidity::lsps1::msgs::{
 };
 pub use lightning_types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
 pub use lightning_types::string::UntrustedString;
+
+pub use crate::io::PostgresTlsConfig;
+
 use vss_client::headers::{
 	VssHeaderProvider as VssClientHeaderProvider,
 	VssHeaderProviderError as VssClientHeaderProviderError,

src/io/mod.rs

@@ -7,6 +7,8 @@
 
 //! Objects and traits for data persistence.
 
+#[cfg(feature = "postgres")]
+pub mod postgres_store;
 pub mod sqlite_store;
 #[cfg(test)]
 pub(crate) mod test_utils;
@@ -82,3 +84,13 @@ pub(crate) const STATIC_INVOICE_STORE_PRIMARY_NAMESPACE: &str = "static_invoices
 /// The pending payment information will be persisted under this prefix.
 pub(crate) const PENDING_PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE: &str = "pending_payments";
 pub(crate) const PENDING_PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
+
+/// TLS configuration for PostgreSQL connections.
+#[cfg(any(feature = "postgres", feature = "uniffi"))]
+#[derive(Debug, Clone)]
+pub struct PostgresTlsConfig {
+	/// PEM-encoded CA certificate. When set, the certificate is added to the system's default
+	/// root certificates — it does not replace them. If `None`, only the system's default root
+	/// certificates are used.
+	pub certificate_pem: Option<String>,
+}

src/io/postgres_store/migrations.rs

@@ -0,0 +1,21 @@
+// This file is Copyright its original authors, visible in version control history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
+// http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
+// accordance with one or both of these licenses.
+
+use lightning::io;
+use tokio_postgres::Client;
+
+pub(super) async fn migrate_schema(
+	_client: &Client, _kv_table_name: &str, from_version: u16, to_version: u16,
+) -> io::Result<()> {
+	assert!(from_version < to_version);
+	// Future migrations go here, e.g.:
+	// if from_version == 1 && to_version >= 2 {
+	//     migrate_v1_to_v2(client, kv_table_name).await?;
+	//     from_version = 2;
+	// }
+	Ok(())
+}