feat(fortuna): Support Postgres DB backend

apps/fortuna/.gitignore

@@ -4,3 +4,4 @@
 *private-key*
 .envrc
 fortuna.db*
+.env*

apps/fortuna/Cargo.toml

@@ -46,8 +46,16 @@ chrono = { version = "0.4.38", features = [
 backoff = { version = "0.4.0", features = ["futures", "tokio"] }
 thiserror = "1.0.61"
 futures-locks = "0.7.1"
-sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite", "chrono"] }
+sqlx = { version = "0.8", features = [
+  "runtime-tokio",
+  "tls-rustls",
+  "sqlite",
+  "any",
+  "postgres",
+  "chrono",
+] }
 num-traits = "0.2.19"
+dotenv = "0.15.0"
 
 [dev-dependencies]
 axum-test = "13.1.1"

apps/fortuna/README.md

@@ -10,35 +10,38 @@ Each blockchain is configured in `config.yaml`.
 
 ## Build & Test
 
-We use sqlx query macros to check the SQL queries at compile time. This requires
-a database to be available at build time. Create a `.env` file in the root of the project with the following content:
+Fortuna uses Cargo for building and dependency management.
+Simply run `cargo build` and `cargo test` to build and test the project.
+To run Fortuna locally, see the [Local Development](#local-development) section below.
 
+### Connect a database
+Fortuna stores request history in a SQL database and serves it from its explorer API.
+Any SQLite or Postgres database is supported. The database connection is sourced from the `DATABASE_URL` env var.
+Create a `.env` file in the root of the project with a DB connection string.
 ```
 DATABASE_URL="sqlite:fortuna.db?mode=rwc"
 ```
+If not provided, Fortuna will create and use a SQLite file-based database at `./fortuna.db`, as in the example above.
+
+### Database migrations
+Fortuna will automatically apply the schema migrations in the `./migrations` directory when connecting to the database.
+To manually administer the migrations, use the `sqlx` tool for cargo. The tool automatically uses the
+database connection in the `.env` file.
 
-Install sqlx for cargo with:
+Install `sqlx`:
 ```bash
 cargo install sqlx
 ```
 
-Next, you need to create the database and apply the schema migrations. You can do this by running:
-
+To create the database if needed and apply the migrations:
 ```bash
-cargo sqlx migrate run # automatically picks up the .env file
+cargo sqlx migrate run
 ```
-This will create a SQLite database file called `fortuna.db` in the root of the project and apply the schema migrations to it.
-This will allow `cargo check` to check the queries against the existing database.
-
-Fortuna uses Cargo for building and dependency management.
-Simply run `cargo build` and `cargo test` to build and test the project.
-
-If you have changed any queries in the code, you need to update the .sqlx folder with the new queries:
 
+To restore the database to a fresh state (drop, recreate, apply migrations):
 ```bash
-cargo sqlx prepare
+cargo sqlx database reset
 ```
-Please add the changed files in the `.sqlx` folder to your git commit.
 
 ## Command-Line Interface
 
@@ -124,7 +127,7 @@ To start an instance of the webserver for local testing, you first need to perfo
 1. Run `cargo run -- setup-provider` to register a randomness provider for this service. This command
    will update the on-chain contracts such that the configured provider key is a randomness provider,
    and its on-chain configuration matches `config.yaml`.
-
+1. Review the [Connect a database](#connect-a-database) section above. The default configuration will create a file-based DB.
 Once you've completed the setup, simply run the following command to start the service:
 
 ```bash

apps/fortuna/migrations/20250707000000_init.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS request;

apps/fortuna/migrations/20250707000000_init.up.sql

@@ -0,0 +1,36 @@
+CREATE TABLE request(
+    chain_id VARCHAR(20) NOT NULL,
+    network_id INTEGER NOT NULL,
+    provider VARCHAR(40) NOT NULL,
+    sequence INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    last_updated_at INTEGER NOT NULL,
+    state VARCHAR(10) NOT NULL,
+    request_block_number INTEGER NOT NULL,
+    request_tx_hash VARCHAR(64) NOT NULL,
+    user_random_number VARCHAR(64) NOT NULL,
+    sender VARCHAR(40) NOT NULL,
+    reveal_block_number INTEGER,
+    reveal_tx_hash VARCHAR(64),
+    provider_random_number VARCHAR(64),
+    info TEXT,
+    gas_used VARCHAR(100),
+    gas_limit VARCHAR(100) NOT NULL,
+    PRIMARY KEY (network_id, sequence, provider, request_tx_hash)
+);
+
+CREATE INDEX request__network_id__state__created_at ON request(network_id, state, created_at);
+CREATE INDEX request__network_id__created_at ON request(network_id, created_at);
+CREATE INDEX request__sender__network_id__state__created_at ON request(sender, network_id, state, created_at);
+CREATE INDEX request__sender__network_id__created_at ON request(sender, network_id, created_at);
+CREATE INDEX request__sender__state__created_at ON request(sender, state, created_at);
+CREATE INDEX request__sender__created_at ON request(sender, created_at);
+CREATE INDEX request__sequence__network_id__state__created_at ON request(sequence, network_id, state, created_at);
+CREATE INDEX request__sequence__network_id__created_at ON request(sequence, network_id, created_at);
+CREATE INDEX request__sequence__state__created_at ON request(sequence, state, created_at);
+CREATE INDEX request__sequence__created_at ON request(sequence, created_at);
+CREATE INDEX request__state__created_at ON request(state, created_at);
+CREATE INDEX request__created_at ON request(created_at);
+
+CREATE INDEX request__request_tx_hash ON request (request_tx_hash) WHERE request_tx_hash IS NOT NULL;
+CREATE INDEX request__reveal_tx_hash ON request (reveal_tx_hash) WHERE reveal_tx_hash IS NOT NULL;

apps/fortuna/src/api.rs

@@ -42,6 +42,16 @@ pub enum StateTag {
     Failed,
 }
 
+impl std::fmt::Display for StateTag {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            StateTag::Pending => write!(f, "Pending"),
+            StateTag::Completed => write!(f, "Completed"),
+            StateTag::Failed => write!(f, "Failed"),
+        }
+    }
+}
+
 #[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
 pub struct RequestLabel {
     pub value: String,

apps/fortuna/src/api/explorer.rs

@@ -110,7 +110,7 @@ pub struct ExplorerQueryParams {
 #[derive(Debug, serde::Serialize, utoipa::ToSchema)]
 pub struct ExplorerResponse {
     pub requests: Vec<RequestStatus>,
-    pub total_results: u64,
+    pub total_results: i64,
 }
 
 /// Returns the logs of all requests captured by the keeper.

apps/fortuna/src/command/run.rs

@@ -84,6 +84,8 @@ pub async fn run_api(
 }
 
 pub async fn run(opts: &RunOptions) -> Result<()> {
+    // Load environment variables from a .env file if present
+    let _ = dotenv::dotenv()?;
     let config = Config::load(&opts.config.config)?;
     let secret = config.provider.secret.load()?.ok_or(anyhow!(
         "Please specify a provider secret in the config file."