Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(installation): add missing pgrx initialization and database connection steps #514

Merged
merged 3 commits into from
May 14, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
26 changes: 23 additions & 3 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,35 @@
First, install [pgrx](https://github.com/tcdi/pgrx) by running `cargo install --locked cargo-pgrx@version`, where version should be compatible with the [pgrx version used by pg_graphl](https://github.com/supabase/pg_graphql/blob/master/Cargo.toml#L16)
First, install [pgrx](https://github.com/tcdi/pgrx) by running `cargo install --locked cargo-pgrx@version`, where version should be compatible with the [pgrx version used by pg_graphql](https://github.com/supabase/pg_graphql/blob/master/Cargo.toml#L16).

Then clone the repo and install using
Then clone the repo and install using:

```bash
git clone https://github.com/supabase/pg_graphql.git
cd pg_graphql
cargo pgrx install --release
```

To enable the extension in PostgreSQL we must execute a `create extension` statement. The extension creates its own schema/namespace named `graphql` to avoid naming conflicts.
Before enabling the extension in PostgreSQL, you need to initialize `pgrx`. Depending on your PostgreSQL installation, you might need to specify the path to `pg_config`. For example, on macOS with PostgreSQL installed via Homebrew:

```bash
cargo pgrx init --pg14 "/opt/homebrew/bin/pg_config"
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we do two things here:

  1. Use pg15 as it is a later version (also use pg15 below in other commands).
  2. Remove the path to pg_config as people might have a different path in their installation. Even better would be to simply use cargo pgrx init --pg15 and then add a note about explicitly mentioning pg_config only if it is not on path.

Copy link
Contributor

@mlabisi mlabisi May 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For what it's worth, omitting the pg_config path for the cargo pgrx init --pg15 command gave me an error
image

Running cargo pgrx init --help seems to provide a clear explanation of the command and its usage!
image

(although I guess the latest would be pg16 now!)


To start the database:

```bash
cargo pgrx start pg14
```

To connect:

```bash
cargo pgrx connect pg14
```

Finally, to enable the `pg_graphql` extension in PostgreSQL, execute the `create extension` statement. This extension creates its own schema/namespace named `graphql` to avoid naming conflicts.

```psql
create extension pg_graphql;
```

These additional steps ensure that `pgrx` is properly initialized, and the database is started and connected before attempting to install and use the `pg_graphql` extension.