feat(gb-9009): views support

Author: pimeys

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "grafbase-postgres"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 license = "Apache-2.0"
 
@@ -27,3 +27,5 @@ sqlx = { workspace = true, features = [
 ] }
 semver = { version = "1.0.26", features = ["serde"] }
 url = { version = "2.5.4", features = ["serde"] }
+toml.workspace = true
+dotenv = "0.15.0"

cli/postgres/Cargo.toml

@@ -23,10 +23,12 @@ cargo install --path .
 
 - `DATABASE_URL` - Connection string to your PostgreSQL database
 
+If the current directory has a `.env` file stored with the `DATABASE_URL` environment variable, it will be used as the default value for the `--database-url` option.
+
 ### Basic Command
 
 ```bash
-grafbase-postgres --database-url "postgres://username:password@localhost:5432/mydatabase" introspect --extension-version 1.0.0 --database-name mydb
+grafbase-postgres --database-url "postgres://username:password@localhost:5432/mydatabase" introspect --config grafbase-postgres.toml
 ```
 
 ### Command Options
@@ -37,39 +39,34 @@ grafbase-postgres --database-url "postgres://username:password@localhost:5432/my
 
 #### Introspect Command
 
-- `-o, --output-file <PATH>` - Write the SDL output to a file instead of stdout
-- `-d, --database-name <NAME>` - Name for the database in the GraphQL SDL (default: "default")
-- `-s, --default-schema <SCHEMA>` - Default schema to use (will be omitted from definitions) (default: "public")
-- `-u, --extension-url <URL>` - URL to the Grafbase PostgreSQL extension
-- `-v, --extension-version <VERSION>` - Version of the Grafbase PostgreSQL extension (semver)
-
-**Note**: Either `--extension-url` or `--extension-version` must be provided.
+- `-c, --config <PATH>` - Specify configuration file for introspection. Defaults to `./grafbase-postgres.toml` if not provided.
 
 ## Examples
 
 ### Output SDL to Terminal
 
 ```bash
-grafbase-postgres --database-url "postgres://user:pass@localhost:5432/mydb" introspect --extension-version 1.0.0
+grafbase-postgres \
+    --database-url "postgres://user:pass@localhost:5432/mydb" \
+    introspect \
+    --config grafbase-postgres.toml
 ```
 
 ### Save SDL to a File
 
 ```bash
-grafbase-postgres --database-url "postgres://user:pass@localhost:5432/mydb" introspect --extension-version 1.0.0 --output-file schema.graphql
-```
-
-### Use a Custom Database Name and Schema
-
-```bash
-grafbase-postgres --database-url "postgres://user:pass@localhost:5432/mydb" introspect --extension-version 1.0.0 --database-name production --default-schema app
+grafbase-postgres \
+    --database-url "postgres://user:pass@localhost:5432/mydb" \
+    introspect \
+    --config grafbase-postgres.toml > schema.graphql
 ```
 
 ## What Gets Introspected
 
 The following database objects are introspected:
 - Schemas
 - Tables
+- Views (normal and materialized)
 - Columns (including data types and constraints)
 - Primary keys and unique constraints
 - Foreign keys (relationships between tables)
@@ -84,16 +81,80 @@ The tool:
 4. Renders the definition as GraphQL SDL
 5. Outputs the SDL to stdout or a file
 
-## Advanced Usage
+## Configuration
 
-### Using a Custom Extension URL
+Configure the introspection command using a TOML configuration file. Include these essential settings:
 
-If you need to use a custom extension URL instead of the official version:
+```toml
+# The URL of the extension, which appears at the top of the GraphQL SDL.
+extension_url = "https://grafbase.com/extensions/postgres/0.3.0"
 
-```bash
-grafbase-postgres --database-url "postgres://user:pass@localhost:5432/mydb" introspect --extension-url "https://example.com/my-postgres-extension"
+# The default schema, which we'll omit from the SDL output.
+# Defaults to "public" if you don't specify it
+default_schema = "public"
+
+# The name of the database the virtual subgraph should use. This
+# maps to a Postgres database name in your gateway configuration.
+# Defaults to "default" if you don't specify it
+database_name = "default"
 ```
 
+### Exposing Views
+
+PostgreSQL views require additional configuration because the information schema doesn't provide details about unique constraints, nullability, or relations. To make a view visible in your GraphQL SDL, you must define at least one unique key.
+
+#### Unique Key Definitions
+
+```toml
+[schemas.public.views.my_view]
+# The order of columns matters - match the order in the underlying query/table.
+# Define compound keys like this:
+unique_keys = [["user_name", "user_id"]]
+
+# structure: schemas.<schema_name>.views.<view_name>.columns.<column_name>
+[schemas.public.views.my_view.columns.user_name]
+# Defaults to true if you omit this setting
+nullable = false
+# Define a single-column unique key here. Defaults to false if omitted.
+unique = false
+# Customize the GraphQL field name:
+rename = "name_user"
+# Add a description that appears as a comment in the GraphQL schema:
+description = "The name of the user"
+
+[schemas.public.views.my_view.columns.user_id]
+nullable = false
+```
+
+The introspection will fail if you reference any non-existent schemas, views, or columns.
+
+#### Relation Definitions
+
+```toml
+# structure: schemas.<schema_name>.views.<view_name>.relations.<relation_name>
+[schemas.public.views.my_view.relations.my_view_to_my_table]
+# The schema containing the referenced table or view.
+# Defaults to "public" if omitted. Must exist.
+referenced_schema = "public"
+
+# Specify either a table or view. Must exist.
+referenced_table = "my_table"
+
+# List columns in the view that reference columns in the target
+# table or view.
+#
+# Introspection fails if these columns don't exist.
+referencing_columns = ["user_id", "user_name"]
+
+# List columns in the target table or view that your view
+# references.
+#
+# Introspection fails if these columns don't exist.
+referenced_columns = ["id", "name"]
+```
+
+Define these relations in your config file to enable joins to and from your views.
+
 ## License
 
 Apache-2.0

cli/postgres/README.md

@@ -1,8 +1,6 @@
 use std::path::PathBuf;
 
-use clap::{ArgGroup, Parser, Subcommand};
-use semver::Version;
-use url::Url;
+use clap::{Parser, Subcommand};
 
 #[derive(Parser, Debug)]
 #[command(name = "grafbase-postgres")]
@@ -24,36 +22,10 @@ pub enum Commands {
 }
 
 #[derive(Parser, Debug)]
-#[command(group(
-    ArgGroup::new("extension_identifier")
-        .required(true)
-        .args(["extension_url", "extension_version"]),
-))]
 pub struct IntrospectCommand {
-    /// Output file path. If not provided, the SDL will be printed to stdout.
-    #[arg(short, long)]
-    pub output_file: Option<PathBuf>,
-    /// The name of the database to be used in the GraphQL SDL
-    #[arg(short, long, default_value = "default")]
-    pub database_name: String,
-    /// Default schema to be used in the GraphQL SDL (will be omitted from definitions)
-    #[arg(short = 's', long, default_value = "public")]
-    pub default_schema: String,
-    /// URL to the extension
-    #[arg(long, short = 'u')]
-    pub extension_url: Option<Url>,
-    /// Extension version following semver
-    #[arg(long, short = 'v')]
-    pub extension_version: Option<Version>,
-}
-
-impl IntrospectCommand {
-    pub fn extension_url(&self) -> String {
-        match self.extension_version.as_ref() {
-            Some(version) => format!("https://grafbase.com/extensions/postgres/{version}"),
-            None => self.extension_url.as_ref().unwrap().to_string(),
-        }
-    }
+    /// Configuration file location
+    #[arg(short, long, default_value = "./grafbase-postgres.toml")]
+    pub config: PathBuf,
 }
 
 pub fn parse() -> Args {

cli/postgres/src/args.rs

@@ -1,13 +1,14 @@
+use anyhow::Context;
 use args::IntrospectCommand;
-use grafbase_postgres_introspection::IntrospectionOptions;
 use sqlx::{Connection, PgConnection};
 
 mod args;
 
 #[tokio::main(flavor = "current_thread")]
 async fn main() -> anyhow::Result<()> {
-    let args = args::parse();
+    dotenv::dotenv()?;
 
+    let args = args::parse();
     let mut conn = PgConnection::connect(&args.database_url).await?;
 
     match args.command {
@@ -20,18 +21,11 @@ async fn main() -> anyhow::Result<()> {
 }
 
 async fn introspect(conn: &mut PgConnection, cmd: IntrospectCommand) -> anyhow::Result<()> {
-    let opts = IntrospectionOptions {
-        database_name: &cmd.database_name,
-        extension_url: &cmd.extension_url(),
-        default_schema: &cmd.default_schema,
-    };
+    let config = std::fs::read_to_string(&cmd.config).context("could not read the configuration file")?;
+    let config = toml::from_str(&config)?;
+    let sdl = grafbase_postgres_introspection::introspect(conn, config).await?;
 
-    let sdl = grafbase_postgres_introspection::introspect(conn, opts).await?;
-
-    match cmd.output_file {
-        Some(path) => std::fs::write(path, sdl)?,
-        None => println!("{sdl}"),
-    }
+    println!("{sdl}");
 
     Ok(())
 }

cli/postgres/src/main.rs

@@ -35,10 +35,6 @@ impl Key<String> {
 }
 
 impl Key<StringId> {
-    pub(crate) fn name(&self) -> StringId {
-        self.constraint_name
-    }
-
     pub(crate) fn r#type(&self) -> KeyType {
         self.r#type
     }

crates/database-definition/src/key.rs

@@ -31,7 +31,7 @@ use interner::StringInterner;
 pub use key::{Key, KeyType};
 pub use key_column::KeyColumn;
 use relations::Relations;
-pub use table::Table;
+pub use table::{RelationKind, Table};
 pub use table_column::{IdentityGeneration, TableColumn};
 pub use r#type::{ColumnType, DatabaseType, EnumType, ScalarKind, ScalarType};
 pub use walkers::{EnumWalker, KeyWalker, RelationWalker, TableColumnWalker, TableWalker, Walker};
@@ -198,6 +198,7 @@ impl DatabaseDefinition {
             client_name: self.interner.intern(table.client_name()),
             client_field_name: self.interner.intern(table.client_field_name()),
             client_field_name_plural: self.interner.intern(table.client_field_name_plural()),
+            kind: table.kind,
             description: table.description.map(|desc| self.interner.intern(&desc)),
         });
 

crates/database-definition/src/lib.rs

@@ -9,9 +9,29 @@ pub struct Table<T> {
     pub(super) client_name: T,
     pub(super) client_field_name: T,
     pub(super) client_field_name_plural: T,
+    pub(super) kind: RelationKind,
     pub(super) description: Option<T>,
 }
 
+#[derive(serde::Deserialize, Debug, Clone, Copy, Default, PartialEq)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum RelationKind {
+    #[default]
+    Relation,
+    View,
+    MaterializedView,
+}
+
+impl RelationKind {
+    pub fn client_name(self) -> &'static str {
+        match self {
+            RelationKind::Relation => "RELATION",
+            RelationKind::View => "VIEW",
+            RelationKind::MaterializedView => "MATERIALIZED_VIEW",
+        }
+    }
+}
+
 impl<T> Copy for Table<T> where T: Copy {}
 
 impl<T> Table<T> {
@@ -34,10 +54,14 @@ impl<T> Table<T> {
     pub fn set_description(&mut self, description: T) {
         self.description = Some(description);
     }
+
+    pub(crate) fn kind(&self) -> RelationKind {
+        self.kind
+    }
 }
 
 impl Table<String> {
-    pub fn new(schema_id: SchemaId, database_name: String, client_name: Option<String>) -> Self {
+    pub fn new(schema_id: SchemaId, database_name: String, kind: RelationKind, client_name: Option<String>) -> Self {
         let client_name = client_name.unwrap_or_else(|| database_name.to_pascal_case().to_singular());
         let client_field_name = client_name.to_camel_case();
         let client_field_name_plural = client_field_name.to_plural();
@@ -48,6 +72,7 @@ impl Table<String> {
             client_name,
             client_field_name,
             client_field_name_plural,
+            kind,
             description: None,
         }
     }

crates/database-definition/src/table.rs

@@ -10,11 +10,6 @@ impl<'a> KeyWalker<'a> {
         self.walk(self.get().table_id())
     }
 
-    /// The constraint name.
-    pub fn name(self) -> &'a str {
-        self.get_name(self.get().name())
-    }
-
     /// The columns defining the unique value.
     pub fn columns(self) -> impl ExactSizeIterator<Item = KeyColumnWalker<'a>> + 'a {
         let range = super::range_for_key(&self.database_definition.key_columns, self.id, |column| column.key_id());