feat: support standard postgres env vars for db connection (#674)

Support `DATABASE_URL`, `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`,
`PGDATABASE` env vars for configuring the database connection with
highest priority.

we use bpaf(env()) for the cli, and support loading the db config
from_env for the lsp.

These env var names follow the standard [libpq environment
variables](https://www.postgresql.org/docs/current/libpq-envars.html)
(`PG*`) and the widely adopted `DATABASE_URL` convention used by tools
like `sqlx`, `diesel`, `prisma`, and `dotenv`.

### Example

```sh
DATABASE_URL=postgres://user:pass@localhost:5432/mydb postgres-language-server check file.sql
# or individual vars
PGHOST=localhost PGPORT=5432 PGUSER=user PGPASSWORD=pass PGDATABASE=mydb postgres-language-server check file.sql
```

### Precedence (highest to lowest)

1. Environment variables
2. CLI args / LSP client settings
3. Config file
4. Defaults

Closes #302

Author: psteinroe

.github/workflows/publish.yml

@@ -97,6 +97,8 @@ jobs:
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2.17"
 
       - name: Install dependencies
         run: bun install

.github/workflows/pull_request.yml

@@ -49,6 +49,8 @@ jobs:
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2.17"
 
       - name: Install JS dependencies
         run: bun install
@@ -140,6 +142,8 @@ jobs:
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2.17"
 
       - name: Install JS dependencies
         run: bun install
@@ -239,6 +243,8 @@ jobs:
         run: cargo build -p pgls_cli --release
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2.17"
       - name: Install JS dependencies
         run: bun install
 

bun.lock

@@ -196,14 +196,10 @@ pub enum PgLSCommand {
     /// Writes to stdout by default, or to a file if --output is specified.
     #[bpaf(command("schema-export"))]
     SchemaExport {
-        /// PostgreSQL connection string (e.g., postgres://user:pass@host/db)
-        #[bpaf(
-            env("DATABASE_URL"),
-            long("connection-string"),
-            short('c'),
-            argument("URL")
-        )]
-        connection_string: String,
+        /// PostgreSQL connection string (e.g., postgres://user:pass@host/db).
+        /// Can also be set via the `DATABASE_URL` environment variable.
+        #[bpaf(long("connection-string"), short('c'), argument("URL"), optional)]
+        connection_string: Option<String>,
 
         /// Output file path for the JSON schema (defaults to stdout if not specified)
         #[bpaf(long("output"), short('o'), argument("PATH"))]

crates/pgls_cli/src/commands/mod.rs

@@ -144,6 +144,14 @@ impl<'app> CliSession<'app> {
                 connection_string,
                 output,
             } => {
+                let connection_string = connection_string
+                    .or_else(|| std::env::var("DATABASE_URL").ok())
+                    .ok_or_else(|| {
+                        CliDiagnostic::missing_argument(
+                            "--connection-string (or DATABASE_URL env var)",
+                            "schema-export",
+                        )
+                    })?;
                 let runtime = tokio::runtime::Runtime::new().map_err(CliDiagnostic::io_error)?;
                 runtime.block_on(commands::schema_export::run_schema_export(
                     &connection_string,
@@ -193,6 +201,17 @@ impl<'app> CliSession<'app> {
         }
 
         let mut configuration = loaded_configuration.configuration;
+
+        // Env vars override config file but are overridden by explicit CLI args.
+        if let Some(env_db) = pgls_configuration::database::PartialDatabaseConfiguration::from_env()
+        {
+            let env_config = PartialConfiguration {
+                db: Some(env_db),
+                ..Default::default()
+            };
+            configuration.merge_with(env_config);
+        }
+
         if let Some(cli_config) = cli_configuration {
             configuration.merge_with(cli_config);
         }

crates/pgls_cli/src/lib.rs

@@ -4,35 +4,41 @@ use bpaf::Bpaf;
 use serde::{Deserialize, Serialize};
 
 /// The configuration of the database connection.
-#[derive(Clone, Debug, Deserialize, Eq, Partial, PartialEq, Serialize)]
+#[derive(Clone, Deserialize, Eq, Partial, PartialEq, Serialize)]
 #[partial(derive(Bpaf, Clone, Eq, PartialEq, Merge))]
 #[partial(cfg_attr(feature = "schema", derive(schemars::JsonSchema)))]
 #[partial(serde(rename_all = "camelCase", default, deny_unknown_fields))]
 pub struct DatabaseConfiguration {
     /// A connection string that encodes the full connection setup.
     /// When provided, it takes precedence over the individual fields.
+    /// Can also be set via the `DATABASE_URL` environment variable.
     #[partial(bpaf(long("connection-string")))]
     pub connection_string: Option<String>,
 
     /// The host of the database.
     /// Required if you want database-related features.
     /// All else falls back to sensible defaults.
+    /// Can also be set via the `PGHOST` environment variable.
     #[partial(bpaf(long("host")))]
     pub host: String,
 
     /// The port of the database.
+    /// Can also be set via the `PGPORT` environment variable.
     #[partial(bpaf(long("port")))]
     pub port: u16,
 
     /// The username to connect to the database.
+    /// Can also be set via the `PGUSER` environment variable.
     #[partial(bpaf(long("username")))]
     pub username: String,
 
     /// The password to connect to the database.
+    /// Can also be set via the `PGPASSWORD` environment variable.
     #[partial(bpaf(long("password")))]
     pub password: String,
 
     /// The name of the database.
+    /// Can also be set via the `PGDATABASE` environment variable.
     #[partial(bpaf(long("database")))]
     pub database: String,
 
@@ -49,6 +55,28 @@ pub struct DatabaseConfiguration {
     pub disable_connection: bool,
 }
 
+impl std::fmt::Debug for DatabaseConfiguration {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("DatabaseConfiguration")
+            .field(
+                "connection_string",
+                &self.connection_string.as_ref().map(|_| "[redacted]"),
+            )
+            .field("host", &self.host)
+            .field("port", &self.port)
+            .field("username", &self.username)
+            .field("password", &"[redacted]")
+            .field("database", &self.database)
+            .field(
+                "allow_statement_executions_against",
+                &self.allow_statement_executions_against,
+            )
+            .field("conn_timeout_secs", &self.conn_timeout_secs)
+            .field("disable_connection", &self.disable_connection)
+            .finish()
+    }
+}
+
 impl Default for DatabaseConfiguration {
     fn default() -> Self {
         Self {
@@ -64,3 +92,39 @@ impl Default for DatabaseConfiguration {
         }
     }
 }
+
+impl PartialDatabaseConfiguration {
+    /// Creates a partial configuration from standard Postgres environment variables.
+    ///
+    /// Reads `DATABASE_URL`, `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, and `PGDATABASE`.
+    /// Returns `None` if no relevant env vars are set.
+    pub fn from_env() -> Option<Self> {
+        let database_url = std::env::var("DATABASE_URL").ok();
+        let pghost = std::env::var("PGHOST").ok();
+        let pgport = std::env::var("PGPORT").ok().and_then(|p| p.parse().ok());
+        let pguser = std::env::var("PGUSER").ok();
+        let pgpassword = std::env::var("PGPASSWORD").ok();
+        let pgdatabase = std::env::var("PGDATABASE").ok();
+
+        let has_any = database_url.is_some()
+            || pghost.is_some()
+            || pgport.is_some()
+            || pguser.is_some()
+            || pgpassword.is_some()
+            || pgdatabase.is_some();
+
+        if !has_any {
+            return None;
+        }
+
+        Some(Self {
+            connection_string: database_url,
+            host: pghost,
+            port: pgport,
+            username: pguser,
+            password: pgpassword,
+            database: pgdatabase,
+            ..Default::default()
+        })
+    }
+}

crates/pgls_configuration/src/database.rs

@@ -35,6 +35,14 @@ pub struct PgLSEnv {
     pub pgls_log_prefix: PgLSEnvVariable,
     pub pgls_config_path: PgLSEnvVariable,
 
+    // Standard Postgres connection env vars
+    pub database_url: PgLSEnvVariable,
+    pub pghost: PgLSEnvVariable,
+    pub pgport: PgLSEnvVariable,
+    pub pguser: PgLSEnvVariable,
+    pub pgpassword: PgLSEnvVariable,
+    pub pgdatabase: PgLSEnvVariable,
+
     // DEPRECATED - kept for backward compatibility
     pub pgt_log_path: PgLSEnvVariable,
     pub pgt_log_level: PgLSEnvVariable,
@@ -64,6 +72,22 @@ impl PgLSEnv {
                 "A path to the configuration file",
             ),
 
+            database_url: PgLSEnvVariable::new(
+                "DATABASE_URL",
+                "A connection string that encodes the full database connection setup.",
+            ),
+            pghost: PgLSEnvVariable::new("PGHOST", "The host of the database server."),
+            pgport: PgLSEnvVariable::new("PGPORT", "The port of the database server."),
+            pguser: PgLSEnvVariable::new("PGUSER", "The username to connect to the database."),
+            pgpassword: PgLSEnvVariable::new(
+                "PGPASSWORD",
+                "The password to connect to the database.",
+            ),
+            pgdatabase: PgLSEnvVariable::new(
+                "PGDATABASE",
+                "The name of the database to connect to.",
+            ),
+
             pgt_log_path: PgLSEnvVariable::new(
                 "PGT_LOG_PATH",
                 "The directory where the Daemon logs will be saved. Deprecated, use PGLS_LOG_PATH instead.",
@@ -156,6 +180,31 @@ impl Display for PgLSEnv {
             }
         };
 
+        let sensitive = [&self.database_url, &self.pgpassword];
+        let non_sensitive = [&self.pghost, &self.pgport, &self.pguser, &self.pgdatabase];
+
+        for var in sensitive {
+            match var.value() {
+                None => {
+                    KeyValuePair(var.name, markup! { <Dim>"unset"</Dim> }).fmt(fmt)?;
+                }
+                Some(_) => {
+                    KeyValuePair(var.name, markup! { <Dim>"set"</Dim> }).fmt(fmt)?;
+                }
+            };
+        }
+
+        for var in non_sensitive {
+            match var.value() {
+                None => {
+                    KeyValuePair(var.name, markup! { <Dim>"unset"</Dim> }).fmt(fmt)?;
+                }
+                Some(value) => {
+                    KeyValuePair(var.name, markup! {{DebugDisplay(value)}}).fmt(fmt)?;
+                }
+            };
+        }
+
         match self.pgt_log_path.value() {
             None => {
                 KeyValuePair(self.pgt_log_path.name, markup! { <Dim>"unset"</Dim> }).fmt(fmt)?;

crates/pgls_env/src/lib.rs

@@ -6,6 +6,7 @@ use crate::session::{
 use crate::utils::{into_lsp_error, panic_to_lsp_error};
 use futures::FutureExt;
 use futures::future::ready;
+use pgls_configuration::database::PartialDatabaseConfiguration;
 use pgls_fs::{ConfigName, FileSystem, OsFileSystem};
 use pgls_workspace::workspace::{RegisterProjectFolderParams, UnregisterProjectFolderParams};
 use pgls_workspace::{DynRef, Workspace, workspace};
@@ -162,9 +163,9 @@ impl LanguageServer for LSPServer {
 
     #[tracing::instrument(level = "info", skip_all)]
     async fn did_change_configuration(&self, params: DidChangeConfigurationParams) {
-        self.session
-            .load_workspace_settings(serde_json::from_value(params.settings).ok())
-            .await;
+        let extra_config: Option<pgls_configuration::PartialConfiguration> =
+            serde_json::from_value(params.settings).ok();
+        self.session.load_workspace_settings(extra_config).await;
         self.setup_capabilities().await;
         self.session.update_all_diagnostics().await;
     }
@@ -410,17 +411,27 @@ pub struct ServerFactory {
     /// This shared flag is set to true once at least one sessions has been
     /// initialized on this server instance
     is_initialized: Arc<AtomicBool>,
+    /// Configuration from environment variables (DATABASE_URL, PGHOST, etc.).
+    /// Computed once at factory creation and passed to each session.
+    env_config: Option<pgls_configuration::PartialConfiguration>,
 }
 
 impl ServerFactory {
     pub fn new(stop_on_disconnect: bool) -> Self {
+        let env_config = PartialDatabaseConfiguration::from_env().map(|db| {
+            pgls_configuration::PartialConfiguration {
+                db: Some(db),
+                ..Default::default()
+            }
+        });
         Self {
             cancellation: Arc::default(),
             workspace: None,
             sessions: Sessions::default(),
             next_session_key: AtomicU64::new(0),
             stop_on_disconnect,
             is_initialized: Arc::default(),
+            env_config,
         }
     }
 
@@ -441,13 +452,15 @@ impl ServerFactory {
 
         let session_key = SessionKey(self.next_session_key.fetch_add(1, Ordering::Relaxed));
 
+        let env_config = self.env_config.clone();
         let mut builder = LspService::build(move |client| {
             let mut session = Session::new(
                 session_key,
                 client,
                 workspace,
                 self.cancellation.clone(),
                 fs,
+                env_config,
             );
             if let Some(path) = config_path {
                 session.set_config_path(path);