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,42 @@
+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@v3
+      - 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: 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"]
 
 [dependencies]
 #lightning = { version = "0.2.0", features = ["std"] }
@@ -76,6 +77,7 @@ 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 }
 vss-client = { package = "vss-client-ng", version = "0.5" }
 prost = { version = "0.11.6", default-features = false}
 #bitcoin-payment-instructions = { version = "0.6" }

src/builder.rs

@@ -629,6 +629,24 @@ 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`.
+	/// The given `kv_table_name` will be used or default to
+	/// [`DEFAULT_KV_TABLE_NAME`](crate::io::postgres_store::DEFAULT_KV_TABLE_NAME).
+	///
+	/// [PostgreSQL]: https://www.postgresql.org
+	#[cfg(feature = "postgres")]
+	pub fn build_with_postgres_store(
+		&self, node_entropy: NodeEntropy, connection_string: &str, kv_table_name: Option<String>,
+	) -> Result<Node, BuildError> {
+		let kv_store =
+			crate::io::postgres_store::PostgresStore::new(connection_string, kv_table_name)
+				.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> {
@@ -1087,6 +1105,22 @@ impl ArcedNodeBuilder {
 		self.inner.read().unwrap().build(*node_entropy).map(Arc::new)
 	}
 
+	/// Builds a [`Node`] instance with a [PostgreSQL] backend and according to the options
+	/// previously configured.
+	///
+	/// [PostgreSQL]: https://www.postgresql.org
+	#[cfg(feature = "postgres")]
+	pub fn build_with_postgres_store(
+		&self, node_entropy: Arc<NodeEntropy>, connection_string: String,
+		kv_table_name: Option<String>,
+	) -> Result<Arc<Node>, BuildError> {
+		self.inner
+			.read()
+			.unwrap()
+			.build_with_postgres_store(*node_entropy, &connection_string, kv_table_name)
+			.map(Arc::new)
+	}
+
 	/// Builds a [`Node`] instance with a [`FilesystemStore`] 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(())
+}