Merge branch 'docs-and-pgrx-upgrade'

Author: rustprooflabs

ADVANCED-INSTALL.md

@@ -2,20 +2,21 @@
 
 This page covers installing PgDD from source locally, and the Docker build
 method based on [ZomboDB's build system](https://github.com/zombodb/zombodb)
-used to create the binaries.
+used to create the binaries for multiple versions.
 
 
-## Install `pgdd` from source
+## Create Binary installer for your system
 
+The following steps walk through creating a package on a typical
+Ubuntu based system with Postgres 15.
 
-One way to install `pgdd` is to install from source by cloning this repository.
 
 ### Prereqs
 
 pgrx and its dependencies are the main prereq for PgDD.
 Install Prereqs and ensure PostgreSQL dev tools are installed.
 
-> See the [Cargo pgrx](https://github.com/zombodb/pgrx/tree/master/cargo-pgrx)
+> See the [Cargo pgrx](https://github.com/tcdi/pgrx/tree/master/cargo-pgrx)
 documentation for more information on using pgrx.
 
 
@@ -57,68 +58,53 @@ cargo pgrx init
 ```
 
 
-### Clone PgDD repo
+
+The `fpm` step requires the `fpm` Ruby gem.
 
 ```bash
-mkdir ~/git
-cd ~/git
-git clone https://github.com/rustprooflabs/pgdd.git
-cd ~/git/pgdd
+sudo apt install ruby-rubygems
+sudo gem i fpm
 ```
 
-### Test deployment
-
-Specify version, `pg10` through `pg13` are currently supported. This command will
-start a test instance of Postgres on port `28812`.  Using a different version
-changes the last two digits of the port!
-
+Of course, the PgDD project itself is required.
 
 ```bash
-cargo pgrx run pg14
+mkdir ~/git
+cd ~/git
+git clone https://github.com/rustprooflabs/pgdd.git
+cd ~/git/pgdd
 ```
 
-The output starts with something similar to:
+### Create package
 
-```bash
-building extension with features `pg14`
-"cargo" "build" "--lib" "--features" "pg14" "--no-default-features"
-    Updating crates.io index
-```
+> Timing note:  `cargo pgrx package` takes ~ 2 minutes on my main dev machine.
 
 
 ```bash
-     Copying control file to `/home/username/.pgrx/14.0/pgrx-install/share/postgresql/extension/pgdd.control`
-     Copying shared library to `/home/username/.pgrx/14.0/pgrx-install/lib/postgresql/pgdd.so`
-    Building SQL generator with features `pg14`
-"cargo" "build" "--bin" "sql-generator" "--features" "pg14" "--no-default-features"
-   Compiling pgdd v0.4.0 (/home/username/git/pgdd)
-    Finished dev [unoptimized + debuginfo] target(s) in 13.84s
- Discovering SQL entities
-  Discovered 9 SQL entities: 0 schemas (0 unique), 6 functions, 0 types, 0 enums, 3 sqls, 0 ords, 0 hashes
-running SQL generator with features `pg14`
-"cargo" "run" "--bin" "sql-generator" "--features" "pg14" "--no-default-features" "--" "--sql" "/home/username/.pgrx/14.0/pgrx-install/share/postgresql/extension/pgdd--0.4.1-dev.sql"
-    Finished dev [unoptimized + debuginfo] target(s) in 0.06s
-     Running `target/debug/sql-generator --sql /home/username/.pgrx/14.0/pgrx-install/share/postgresql/extension/pgdd--0.4.1-dev.sql`
-     Copying extension schema file to `/home/username/.pgrx/14.0/pgrx-install/share/postgresql/extension/pgdd--0.4.1-dev.sql`
-    Finished installing pgdd
-    Starting Postgres v14 on port 28814
-    Re-using existing database pgdd
-```
+cargo pgrx package --pg-config /usr/lib/postgresql/15/bin/pg_config
+cd target/release/pgdd-pg15/
 
-In the test instance of psql, create the extension in database.
+find ./ -name "*.so" -exec strip {} \;
+OUTFILE=pgdd.deb
+rm ${OUTFILE} || true
+fpm \
+  -s dir \
+  -t deb -n pgdd \
+  -v 0.5.0 \
+  --deb-no-default-config-files \
+  -p ${OUTFILE} \
+  -a amd64 \
+  .
 
-```bash
-CREATE EXTENSION pgdd;
+sudo dpkg -i --force-overwrite ./pgdd.deb
 ```
 
-> Note: When you see "Re-using existing database pgdd" your previous installed version of `pgdd` will be available. To ensure you are working with the latest version of the `pgdd` extension you must drop/create the extension, quit the psql shell, and re-run the `cargo pgrx run` command.
 
 
-## Build binary packages
+## Use Docker to build binary packages
 
-Debian/Ubuntu Bionic binaries are available for 0.4.0
-(first [pgrx](https://github.com/tcdi/pgrx) version)
-and later.  More distributions will likely have binaries available in the future.
+Ubuntu 22.04 (Jammy) binaries are available for 0.5.0 for Postgres 11
+through Postgres 15.
 
 
 ```bash
@@ -128,11 +114,6 @@ time bash ./build.sh
 
 Tagged versions will be attached to their [releases](https://github.com/rustprooflabs/pgdd/releases).
 
-During development some versions may be copied to the `./standalone/` directory.
-
-```bash
-cp ./target/artifacts/* ./standalone/
-```
 
 ## pgrx Generate graphviz
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pgdd"
-version = "0.5.0-dev"
+version = "0.5.0"
 edition = "2018"
 description = "In-database (PostgreSQL) data dictionary providing database introspection via standard SQL query syntax."
 
@@ -17,12 +17,12 @@ pg15 = ["pgrx/pg15"]
 pg_test = []
 
 [dependencies]
-pgrx = "=0.7.4"
-pgrx-macros = "=0.7.4"
+pgrx = "=0.9.5"
+pgrx-macros = "=0.9.5"
 
 
 [dev-dependencies]
-pgrx-tests = "=0.7.4"
+pgrx-tests = "=0.9.5"
 
 
 [profile.dev]

README.md

@@ -9,20 +9,19 @@ The extension is built on the Rust [pgrx framework](https://github.com/tcdi/pgrx
 
 ## Compatibility
 
-PgDD has been tested to work for PostgreSQL 10 through 14.
+PgDD has been tested to work for PostgreSQL 11 through 15.
 
 
 ## Install from binary
 
-Binaries are available for Ubuntu 20.04 (focal) and Ubuntu 21.04 (hirsute).
-See [releases](https://github.com/rustprooflabs/pgdd/releases) for the full list
-of binaries.
+Binaries are available for Ubuntu 22.04 (jammy) for AMD 64 architectures.
+See [releases](https://github.com/rustprooflabs/pgdd/releases) for the full list of binaries.
 
-Download and install for Postgres 14 on Ubuntu 20.04 (focal).
+Download and install for Postgres 15 on Ubuntu 22.04.
 
 ```bash
-wget https://github.com/rustprooflabs/pgdd/releases/download/0.4.0/pgdd_0.4.0_focal_pg14_amd64.deb
-sudo dpkg -i ./pgdd_0.4.0_focal_pg14_amd64.deb
+wget https://github.com/rustprooflabs/pgdd/releases/download/0.5.0/pgdd_0.5.0_focal_pg15_amd64.deb
+sudo dpkg -i ./pgdd_0.5.0_focal_pg15_amd64.deb
 ```
 
 Create the extension in your database.
@@ -50,6 +49,7 @@ SELECT extname, extversion
 ```
 
 
+
 ## Use Data Dictionary
 
 Connect to your database using your favorite SQL client. This
@@ -275,7 +275,7 @@ extension to using the [pgrx framework](https://github.com/zombodb/pgrx).
 
 Upgrading versions currently requires `DROP EXTENSION pgdd; CREATE EXTENSION pgdd;`
 to recreate the extension.
-This is unlikely to change until [pgrx #121 is resolved](https://github.com/zombodb/pgrx/issues/121).
+This is unlikely to change until [pgrx #121 is resolved](https://github.com/tcdi/pgrx/issues/121).
 
 
 

build/build.sh

@@ -1,6 +1,6 @@
 # Borrowed heavily from https://github.com/zombodb/zombodb/blob/master/build/build.sh
 #
-# Copyright 2018-2021 RustProof Labs
+# Copyright 2018-2023 RustProof Labs
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ BASE=$(dirname `pwd`)
 VERSION=$(cat $BASE/pgdd.control | grep default_version | cut -f2 -d\')
 LOGDIR=${BASE}/target/logs
 ARTIFACTDIR=${BASE}/target/artifacts
-PGXVERSION=0.6.0
+PGRXVERSION=0.9.5
 
 PG_VERS=("pg11" "pg12" "pg13" "pg14" "pg15")
 #PG_VERS=("pg15")
@@ -30,7 +30,7 @@ echo $BASE
 echo $VERSION
 echo $LOGDIR
 echo $ARTIFACTDIR
-echo "PGX Version: ${PGXVERSION}"
+echo "PGRX Version: ${PGRXVERSION}"
 
 mkdir -p ${LOGDIR}
 mkdir -p ${ARTIFACTDIR}
@@ -49,7 +49,7 @@ for image in `ls docker/  ` ; do
 
     cd docker/${image}
     echo "  Building Docker image: ${image}"
-    docker build -t ${image} --build-arg PGXVERSION=${PGXVERSION}  . 2>&1 > ${LOGDIR}/${image}-build.log || exit 1
+    docker build -t ${image} --build-arg PGRXVERSION=${PGRXVERSION}  . 2>&1 > ${LOGDIR}/${image}-build.log || exit 1
 
     for PG_VER in ${PG_VERS[@]} ; do
 

build/docker/pgdd-ubuntu-jammy/Dockerfile

@@ -5,7 +5,7 @@ LABEL maintainer="PgDD Project - https://github.com/rustprooflabs/pgdd"
 ARG USER=docker
 ARG UID=1000
 ARG GID=1000
-ARG PGXVERSION
+ARG PGRXVERSION
 
 RUN useradd -m ${USER} --uid=${UID}
 
@@ -43,4 +43,4 @@ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs > rustup.sh
 ENV PATH="/home/${USER}/.cargo/bin:${PATH}"
 
 RUN /bin/bash rustup.sh -y \
-    && cargo install --locked cargo-pgx --version ${PGXVERSION}
+    && cargo install --locked cargo-pgrx --version ${PGRXVERSION}

build/package.sh

@@ -1,6 +1,6 @@
 # Borrowed heavily from https://github.com/zombodb/zombodb/blob/master/build/package.sh
 #
-# Copyright 2021-2022 RustProof Labs
+# Copyright 2021-2023 RustProof Labs
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -28,11 +28,11 @@ fi
 PKG_FORMAT=deb
 
 PG_VER_SHORT=${PG_VER: -2}
-echo "    Running pgx init for ${PG_VER} (${PG_VER_SHORT})"
+echo "    Running pgrx init for ${PG_VER} (${PG_VER_SHORT})"
 
-mkdir -p /home/docker/.pgx/data-${PG_VER_SHORT} 
+mkdir -p /home/docker/.pgrx/data-${PG_VER_SHORT}
 
-cargo pgx init --${PG_VER} /usr/lib/postgresql/${PG_VER_SHORT}/bin/pg_config
+cargo pgrx init --${PG_VER} /usr/lib/postgresql/${PG_VER_SHORT}/bin/pg_config
 
 echo "Changing to build dir..."
 cd /build
@@ -42,11 +42,11 @@ VERSION=$(cat pgdd.control | grep default_version | cut -f2 -d\')
 
 echo "PgDD Building for:  ${OSNAME}-${VERSION}"
 
-PG_CONFIG_DIR=$(dirname $(grep ${PG_VER} ~/.pgx/config.toml | cut -f2 -d= | cut -f2 -d\"))
+PG_CONFIG_DIR=$(dirname $(grep ${PG_VER} ~/.pgrx/config.toml | cut -f2 -d= | cut -f2 -d\"))
 export PATH=${PG_CONFIG_DIR}:${PATH}
 
-echo "   Packaging pgx"
-cargo pgx package || exit $?
+echo "   Packaging pgrx"
+cargo pgrx package || exit $?
 
 
 #

pgdd.control

@@ -1,5 +1,5 @@
 comment = 'An in-database data dictionary providing database introspection via standard SQL query syntax.  Developed using pgx (https://github.com/zombodb/pgx).'
-default_version = '0.4.1'
+default_version = '0.5.0'
 module_pathname = '$libdir/pgdd'
 relocatable = false
 schema = dd