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,66 @@
+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
+    timeout-minutes: 60
+
+    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, string? certificate_pem);
+	[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);

src/builder.rs

@@ -644,6 +644,49 @@ impl NodeBuilder {
 		self.build_with_store_and_logger(node_entropy, kv_store, logger)
 	}
 
+	/// 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 `certificate_pem` is `Some`, TLS will be used for database connections and the
+	/// provided PEM-encoded CA certificate will be added to the system's default root
+	/// certificates (it does not replace them). If `certificate_pem` 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>, certificate_pem: Option<String>,
+	) -> Result<Node, BuildError> {
+		let logger = setup_logger(&self.log_writer_config, &self.config)?;
+		let runtime = self.setup_runtime(&logger)?;
+		let kv_store = runtime
+			.block_on(io::postgres_store::PostgresStore::new(
+				connection_string,
+				db_name,
+				kv_table_name,
+				certificate_pem,
+			))
+			.map_err(|e| {
+				log_error!(logger, "Failed to set up Postgres store: {e}");
+				BuildError::KVStoreSetupFailed
+			})?;
+		self.build_with_store_runtime_and_logger(node_entropy, kv_store, runtime, logger)
+	}
+
 	/// Builds a [`Node`] instance with a [`FilesystemStoreV2`] backend and according to the options
 	/// previously configured.
 	///
@@ -789,18 +832,27 @@ impl NodeBuilder {
 		self.build_with_store_and_logger(node_entropy, kv_store, logger)
 	}
 
-	fn build_with_store_and_logger<S: SyncAndAsyncKVStore + Send + Sync + 'static>(
-		&self, node_entropy: NodeEntropy, kv_store: S, logger: Arc<Logger>,
-	) -> Result<Node, BuildError> {
-		let runtime = if let Some(handle) = self.runtime_handle.as_ref() {
-			Arc::new(Runtime::with_handle(handle.clone(), Arc::clone(&logger)))
+	fn setup_runtime(&self, logger: &Arc<Logger>) -> Result<Arc<Runtime>, BuildError> {
+		if let Some(handle) = self.runtime_handle.as_ref() {
+			Ok(Arc::new(Runtime::with_handle(handle.clone(), Arc::clone(logger))))
 		} else {
-			Arc::new(Runtime::new(Arc::clone(&logger)).map_err(|e| {
+			Ok(Arc::new(Runtime::new(Arc::clone(logger)).map_err(|e| {
 				log_error!(logger, "Failed to setup tokio runtime: {}", e);
 				BuildError::RuntimeSetupFailed
-			})?)
-		};
+			})?))
+		}
+	}
+
+	fn build_with_store_and_logger<S: SyncAndAsyncKVStore + Send + Sync + 'static>(
+		&self, node_entropy: NodeEntropy, kv_store: S, logger: Arc<Logger>,
+	) -> Result<Node, BuildError> {
+		let runtime = self.setup_runtime(&logger)?;
+		self.build_with_store_runtime_and_logger(node_entropy, kv_store, runtime, logger)
+	}
 
+	fn build_with_store_runtime_and_logger<S: SyncAndAsyncKVStore + Send + Sync + 'static>(
+		&self, node_entropy: NodeEntropy, kv_store: S, runtime: Arc<Runtime>, logger: Arc<Logger>,
+	) -> Result<Node, BuildError> {
 		let seed_bytes = node_entropy.to_seed_bytes();
 		let config = Arc::new(self.config.clone());
 
@@ -1116,6 +1168,58 @@ 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 `certificate_pem` is `Some`, TLS will be used for database connections and the
+	/// provided PEM-encoded CA certificate will be added to the system's default root
+	/// certificates (it does not replace them). If `certificate_pem` 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>, certificate_pem: Option<String>,
+	) -> Result<Arc<Node>, BuildError> {
+		self.inner
+			.read()
+			.unwrap()
+			.build_with_postgres_store(
+				*node_entropy,
+				connection_string,
+				db_name,
+				kv_table_name,
+				certificate_pem,
+			)
+			.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>, _certificate_pem: Option<String>,
+	) -> Result<Arc<Node>, BuildError> {
+		Err(BuildError::KVStoreSetupFailed)
+	}
+
 	/// Builds a [`Node`] instance with a [`FilesystemStoreV2`] backend and according to the options
 	/// previously configured.
 	pub fn build_with_fs_store(

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;

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(())
+}