From 351979dd7fe6eb4fb9456c40204ad58e865ee925 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Tue, 28 Nov 2023 13:47:18 +0400 Subject: [PATCH 01/16] upgrade prgx to 0.11.1 --- .gitignore | 1 + Cargo.toml | 6 +++--- Dockerfile | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index a9d37c5..9b8efed 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ target Cargo.lock +.vscode/ \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index c4f3a9f..1edae49 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,7 +10,7 @@ rust-version = "1.70.0" crate-type = ["cdylib"] [features] -default = ["pg15"] +default = ["pg16"] pg11 = ["pgrx-tests/pg11", "pgrx/pg11"] pg12 = ["pgrx-tests/pg12", "pgrx/pg12"] pg13 = ["pgrx-tests/pg13", "pgrx/pg13"] @@ -21,10 +21,10 @@ pg_test = [] [dependencies] inner_ulid = { package = "ulid", version = "1.0.0" } -pgrx = "=0.10.2" +pgrx = "=0.11.1" [dev-dependencies] -pgrx-tests = "=0.10.2" +pgrx-tests = "=0.11.1" [profile.dev] panic = "unwind" diff --git a/Dockerfile b/Dockerfile index 4dc0c67..3a516d4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -31,7 +31,7 @@ RUN \ cargo --version # pgrx -RUN cargo install cargo-pgrx --version 0.10.2 --locked +RUN cargo install cargo-pgrx --version 0.11.1 --locked RUN cargo pgrx init --pg${PG_MAJOR} $(which pg_config) From 0387e156bcd4e66ea24e1fda855bf6c75b95228a Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Tue, 28 Nov 2023 14:58:36 +0400 Subject: [PATCH 02/16] upgrade version --- CHANGELOG.md | 4 ++++ Cargo.toml | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 969cee9..86d78ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## 0.1.4 +* with a timezone issue with unit tests +* upgrade prgx to 0.11.1 + ## 0.1.3 #### Enhancements diff --git a/Cargo.toml b/Cargo.toml index 1edae49..ab11471 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,10 +1,10 @@ [package] name = "ulid" publish = false -version = "0.1.3" +version = "0.1.4" edition = "2021" -rust-version = "1.70.0" +rust-version = "1.74.0" [lib] crate-type = ["cdylib"] From 79c959a78be8e7e017057d651e56b36933966cec Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Wed, 29 Nov 2023 23:30:05 +0400 Subject: [PATCH 03/16] revisit README --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 103 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3501ccd..912aaa7 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,18 @@ A postgres extension to support [ulid][]. 1. [Why should I use this?](#why-should-i-use-this) 2. [Why should I use ulid over uuid?](#why-should-i-use-ulid-over-uuid) 3. [Monotonicity](#monotonicity) -4. [Usage](#usage) -5. [Installation](#installation) +4. [Installation](#installation) +5. [Usage](#usage) +6. [Recommendation](#recommendation) +7. [Building](#building) ## Why should I use this? +The use of GUID in a database is a trade off between performance and security. GUIDs are typically used in OLTP to get around id predictability and distributed scalability. + There are several different postgres extensions for [ulid][], but all of them have feature gaps. A good extension should have: -- **Generator**: A generator function to generate [ulid][] identifiers. +- **Generator**: A generator function to generate [ulid][] identifiers. crypto secure as it uses rand::thread_rng() - **Binary**: Data be stored as binary and not text. - **Type**: A postgres type `ulid` which is displayed as [ulid][] text. - **Uuid**: Support for casting between UUID and [ulid][] @@ -35,15 +39,20 @@ There are several different postgres extensions for [ulid][], but all of them ha [^1]: You can convert the [ulid][] into `uuid` or `bytea` and store it like that. [^2]: Supports casting indirectly through `bytea`. -## Why should I use ulid over uuid? +## Why should I use ULID over UUID? -The main advantages are: +The main advantages of ULID are: -* Indexes created over ULIDs are less fragmented compared to UUIDs due to the timestamp and [monotonicity][] that was encoded in the ULID when it was created. +* Indexes generated using ULIDs exhibit lower fragmentation compared to UUIDs thanks to the encoded timestamp and monotonicity. +* ULID are K-ordered, which means you can used to sort the column by time order * ULIDs don't use special characters, so they can be used in URLs or even HTML. * ULIDs are shorter than UUIDs as they are comprised of 26 characters compared to UUIDs' 36 characters. +* ULID are more secure than UUIDv7, their randomness is 80 bits as opposed to 62 bits. +* UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address +* UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures +* UUID v4 provides no other information than randomness which can cause fragmentation in many data structures -This extension is approximately **30% faster** than both `pgcrypto`'s UUID and `pg_uuidv7`'s UUIDv7 when generating a million identifiers. +This extension is approximately **30% faster** than both `pgcrypto`'s UUID and `pg_uuidv7`'s UUIDv7 when generating a million identifiers while leveraging a crypto secure random generator.
@@ -112,6 +121,8 @@ ulid=# EXPLAIN ANALYSE INSERT INTO ulid_keys(id) SELECT gen_ulid() FROM generate ## Monotonicity +Monotony ensures guarantees k-sorting order on the same postgres instance. + This extension supports [monotonicity][] through `gen_monotonic_ulid()` function. To achive this, it uses PostgreSQL's shared memory and LWLock to store last generated ULID. To be able to use [monotonic][monotonicity] ULID's, it is necessary to add this extension to `postgresql.conf`'s `shared_preload_libraries` configuration setting. @@ -187,6 +198,10 @@ ulid=# EXPLAIN ANALYZE INSERT INTO users (name) SELECT 'Client 2' FROM generate_ *...But, chances are negligible.* +## Installation + + + ## Usage Use the extension in the database: @@ -195,6 +210,19 @@ Use the extension in the database: CREATE EXTENSION ulid; ``` +Test Generation speed + +```SQL +# gen +EXPLAIN ANALYSE SELECT gen_ulid() FROM generate_series(1, 1000000); +# gen and insert +EXPLAIN ANALYSE INSERT INTO ulid_keys(id) SELECT gen_ulid() FROM generate_series(1, 1000000); + +# same as above but monotonic +EXPLAIN ANALYSE SELECT gen_monotonic_ulid() FROM generate_series(1, 1000000); +EXPLAIN ANALYSE INSERT INTO ulid_keys(id) SELECT gen_monotonic_ulid() FROM generate_series(1, 1000000); +``` + Create a table with [ulid][] as a primary key: ```sql @@ -220,22 +248,81 @@ SELECT * FROM users WHERE id = '01ARZ3NDEKTSV4RRFFQ69G5FAV'; ``` Cast [ulid][] to timestamp: +```SQL +SELECT id::timestamp FROM users WHERE id; +``` -```sql -ALTER TABLE users -ADD COLUMN created_at timestamp GENERATED ALWAYS AS (id::timestamp) STORED; +or to uuid +```SQL +SELECT id::uuid FROM users WHERE id; ``` -Cast timestamp to [ulid][], this generates a zeroed ULID with the timestamp prefixed (TTTTTTTTTT0000000000000000): +## Recommendation -```sql --- gets all users where the ID was created on 2023-09-15, without using another column and taking advantage of the index -SELECT * FROM users WHERE id BETWEEN '2023-09-15'::timestamp::ulid AND '2023-09-16'::timestamp::ulid; +### Do not confuse ULID's internal date with the record creation date + +They are indeed very similar at first sight, but the dates have different meanings and more importantly a different lifecycle. + +**I would strongly advise against** using ulid as a create_date column for the following reasons: + +* First an index of a date column will be faster than on a random-date-ordered guid. +* Shit happens - loss of data, code mistakes, migrations - you may have to change one of these dates without impacting the other. +* You may decide to create ULIDs asynchronously or in advence, therefore dissociating generation from record creation. +* In the end they are two different things: the **id's** creation date vs the **record's** creation date. + +## Building + + You may build and deploy the extension locally: + +```shell +$ cargo install cargo-pgrx --version 0.11.1 --locked +# on osx only, because we need pg_config +$ brew install postgresql ``` -## Installation +[pgrx][] is a friendly framework to deploy postgresql extensions in rust, to install a local dev environment, use + +```shell +# if postgresql is not installed +# the following command will install and configure each version +$ cargo pgrx init +``` + +or use your own running instance: +```shell +# if you need to reuse a pre-installed postgresql +# make sure postgresql/bin is in the PATH +# ie. fish_add_path /opt/homebrew/opt/postgresql@16/bin +$ cargo pgrx init --pg16 (which pg_config) +``` + +From there, your may run the unit tests, interact with a test instance or compile the delivery package. + +```shell +# run the unit tests +$ cargo pgrx test +``` + +```shell +# interact with a test instance +$ cargo pgrx start +$ cargo pgrx connect +``` + +```shell +# compile the delivery package +$ cargo pgrx install --release +$ cargo pgrx package +``` + +Last, buid a postgres distribution with builtin ulid support + +```shell +# ensure docker is up +make +``` -Use [pgrx][]. You can clone this repo and install this extension locally by following [this guide](https://github.com/tcdi/pgrx/blob/master/cargo-pgrx/README.md#installing-your-extension-locally). +Further details can be found by following [this guide](https://github.com/tcdi/pgrx/blob/master/cargo-pgrx/README.md#installing-your-extension-locally). You can also download relevant files from [releases](https://github.com/pksunkara/pgx_ulid/releases) page. From dc3385bd55ab8d811318e7aebcbb68d5a6774a3f Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Wed, 29 Nov 2023 23:30:15 +0400 Subject: [PATCH 04/16] update dockerignore --- .dockerignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.dockerignore b/.dockerignore index e72e096..12809de 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,6 +1,7 @@ .git .github .gitignore +.vscode *.md *.yml From 4566f65ec4112d55246aa8e3ce09cf59c98779ab Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Wed, 29 Nov 2023 23:30:33 +0400 Subject: [PATCH 05/16] rework dockerfile --- Dockerfile | 28 +++++++++++++++++++--------- Makefile | 2 ++ 2 files changed, 21 insertions(+), 9 deletions(-) create mode 100644 Makefile diff --git a/Dockerfile b/Dockerfile index 3a516d4..cd05678 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,7 @@ +# use 12, 13, 14, 15, 15 ARG PG_MAJOR -FROM postgres:${PG_MAJOR} +FROM postgres:${PG_MAJOR} as build RUN apt-get update @@ -25,7 +26,7 @@ RUN chown postgres:postgres /home/postgres USER postgres RUN \ - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path --profile minimal --default-toolchain 1.70.0 && \ + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path --profile minimal --default-toolchain 1.74.0 && \ rustup --version && \ rustc --version && \ cargo --version @@ -33,19 +34,28 @@ RUN \ # pgrx RUN cargo install cargo-pgrx --version 0.11.1 --locked +# init postgress dev env for target version RUN cargo pgrx init --pg${PG_MAJOR} $(which pg_config) +# Compile as ROOT to avoid a permission denied when copying to /usr/share/postgresql USER root COPY . . -RUN cargo pgrx install +RUN cargo pgrx package -RUN chown -R postgres:postgres /home/postgres -RUN chown -R postgres:postgres /usr/share/postgresql/${PG_MAJOR}/extension -RUN chown -R postgres:postgres /usr/lib/postgresql/${PG_MAJOR}/lib +# RUN chown -R postgres:postgres /home/postgres +# RUN chown -R postgres:postgres /usr/share/postgresql/${PG_MAJOR}/extension +# RUN chown -R postgres:postgres /usr/lib/postgresql/${PG_MAJOR}/lib -USER postgres +# # multi-stage - let's start clean +# FROM postgres:${PG_MAJOR} -ENV POSTGRES_HOST_AUTH_METHOD=trust -ENV USER=postgres +# # COPY --from=build /home/postgres/${PG_MAJOR}/extension/ulid.control /home/postgres/${PG_MAJOR}/extension/ulid.control +# COPY --from=build /usr/share/postgresql/${PG_MAJOR}/extension/ulid*.* /usr/share/postgresql/${PG_MAJOR}/extension/ +# COPY --from=build /usr/lib/postgresql/${PG_MAJOR}/lib/ulid.so /usr/lib/postgresql/${PG_MAJOR}/lib/ulid.so +# # why? convenient, but should stick to upstream behaviors. +# USER postgres +# # allow deployment without a password +# ENV POSTGRES_HOST_AUTH_METHOD=trust +# ENV USER=postgres diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..245ef78 --- /dev/null +++ b/Makefile @@ -0,0 +1,2 @@ +all: + docker build --build-arg="PG_MAJOR=16" . \ No newline at end of file From 85c2f6e396880f703b2cee0d6490443ca5f508b0 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Wed, 29 Nov 2023 23:31:05 +0400 Subject: [PATCH 06/16] update changelog --- CHANGELOG.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86d78ff..8af0cb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,10 @@ # Changelog ## 0.1.4 -* with a timezone issue with unit tests -* upgrade prgx to 0.11.1 +* With a timezone issue with unit tests +* Upgrade prgx to 0.11.1 +* Rework Dockerfile +* Improve README ## 0.1.3 From d17d6dbbfbee924811a87634ae612cba681e7f86 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 00:21:16 +0400 Subject: [PATCH 07/16] docker updates and readme --- Dockerfile | 16 +++++++++++----- Makefile | 2 +- README.md | 13 ++++++++++++- 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/Dockerfile b/Dockerfile index cd05678..b9f023c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -38,18 +38,21 @@ RUN cargo install cargo-pgrx --version 0.11.1 --locked RUN cargo pgrx init --pg${PG_MAJOR} $(which pg_config) # Compile as ROOT to avoid a permission denied when copying to /usr/share/postgresql -USER root +# USER root COPY . . RUN cargo pgrx package + # RUN chown -R postgres:postgres /home/postgres # RUN chown -R postgres:postgres /usr/share/postgresql/${PG_MAJOR}/extension # RUN chown -R postgres:postgres /usr/lib/postgresql/${PG_MAJOR}/lib -# # multi-stage - let's start clean -# FROM postgres:${PG_MAJOR} +# multi-stage - let's start clean +FROM postgres:${PG_MAJOR} + +COPY --from=build /home/postgres/target/release/ulid-pg${PG_MAJOR}/ / # # COPY --from=build /home/postgres/${PG_MAJOR}/extension/ulid.control /home/postgres/${PG_MAJOR}/extension/ulid.control # COPY --from=build /usr/share/postgresql/${PG_MAJOR}/extension/ulid*.* /usr/share/postgresql/${PG_MAJOR}/extension/ @@ -57,5 +60,8 @@ RUN cargo pgrx package # # why? convenient, but should stick to upstream behaviors. # USER postgres # # allow deployment without a password -# ENV POSTGRES_HOST_AUTH_METHOD=trust -# ENV USER=postgres +ENV POSTGRES_HOST_AUTH_METHOD=trust +ENV USER=postgres + +# add comma for more shared_preload_libraries=A,B,C +CMD ["postgres","-c","shared_preload_libraries=ulid"] \ No newline at end of file diff --git a/Makefile b/Makefile index 245ef78..212c730 100644 --- a/Makefile +++ b/Makefile @@ -1,2 +1,2 @@ all: - docker build --build-arg="PG_MAJOR=16" . \ No newline at end of file + docker build -t mypsql --build-arg="PG_MAJOR=16" . \ No newline at end of file diff --git a/README.md b/README.md index 912aaa7..a80d133 100644 --- a/README.md +++ b/README.md @@ -200,7 +200,18 @@ ulid=# EXPLAIN ANALYZE INSERT INTO users (name) SELECT 'Client 2' FROM generate_ ## Installation +The extension consist of 3 files +1. **ulid--0.1.4.sql** & **ulid.control** - the extension configuration file, to deploy in SHAREDIR +2. **ulid.so** - the extension itself, to deploy in LIBDIR + +edit postgresql.conf, add the following line + +```conf +shared_preload_libraries = 'ulid' # (change requires restart) +``` + +> Note: None of these configuration are required if you use the custom docker image ## Usage @@ -268,7 +279,7 @@ They are indeed very similar at first sight, but the dates have different meanin * First an index of a date column will be faster than on a random-date-ordered guid. * Shit happens - loss of data, code mistakes, migrations - you may have to change one of these dates without impacting the other. * You may decide to create ULIDs asynchronously or in advence, therefore dissociating generation from record creation. -* In the end they are two different things: the **id's** creation date vs the **record's** creation date. +* In the end they are two different things: the **id's** creation date vs the **record's** creation date. Typically, in IT we get much better results when we split concerns. ## Building From 3db5ee4e875c315d3c0ea72e2de48bd073515940 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 00:36:44 +0400 Subject: [PATCH 08/16] fix --- Dockerfile | 3 ++- install-extensions.sql | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 install-extensions.sql diff --git a/Dockerfile b/Dockerfile index b9f023c..cc0b23e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -53,6 +53,7 @@ RUN cargo pgrx package FROM postgres:${PG_MAJOR} COPY --from=build /home/postgres/target/release/ulid-pg${PG_MAJOR}/ / +COPY --from=build /home/postgres/install-extensions.sql /docker-entrypoint-initdb.d # # COPY --from=build /home/postgres/${PG_MAJOR}/extension/ulid.control /home/postgres/${PG_MAJOR}/extension/ulid.control # COPY --from=build /usr/share/postgresql/${PG_MAJOR}/extension/ulid*.* /usr/share/postgresql/${PG_MAJOR}/extension/ @@ -64,4 +65,4 @@ ENV POSTGRES_HOST_AUTH_METHOD=trust ENV USER=postgres # add comma for more shared_preload_libraries=A,B,C -CMD ["postgres","-c","shared_preload_libraries=ulid"] \ No newline at end of file +# CMD ["postgres","-c","shared_preload_libraries=ulid"] \ No newline at end of file diff --git a/install-extensions.sql b/install-extensions.sql new file mode 100644 index 0000000..3c27b46 --- /dev/null +++ b/install-extensions.sql @@ -0,0 +1 @@ +CREATE EXTENSION IF NOT EXISTS ulid; \ No newline at end of file From 0c88f1cfb49d440d7094da7382236f5d6cfe4261 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 00:44:35 +0400 Subject: [PATCH 09/16] fix --- Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 212c730..5604c85 100644 --- a/Makefile +++ b/Makefile @@ -1,2 +1,5 @@ all: - docker build -t mypsql --build-arg="PG_MAJOR=16" . \ No newline at end of file + docker build -t mypsql --build-arg="PG_MAJOR=16" . + +run: + docker run -p 5432:5432 mypsql \ No newline at end of file From d1fa4586e431a8117189b3f5f077cf3f8e89b73a Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 09:05:20 +0400 Subject: [PATCH 10/16] tuning --- Dockerfile | 2 +- README.md | 6 +++--- docker/config-postgres.sh | 2 ++ install-extensions.sql => docker/install-extensions.sql | 0 4 files changed, 6 insertions(+), 4 deletions(-) create mode 100755 docker/config-postgres.sh rename install-extensions.sql => docker/install-extensions.sql (100%) diff --git a/Dockerfile b/Dockerfile index cc0b23e..1c0154c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -53,7 +53,7 @@ RUN cargo pgrx package FROM postgres:${PG_MAJOR} COPY --from=build /home/postgres/target/release/ulid-pg${PG_MAJOR}/ / -COPY --from=build /home/postgres/install-extensions.sql /docker-entrypoint-initdb.d +COPY --from=build /home/postgres/docker/* /docker-entrypoint-initdb.d/ # # COPY --from=build /home/postgres/${PG_MAJOR}/extension/ulid.control /home/postgres/${PG_MAJOR}/extension/ulid.control # COPY --from=build /usr/share/postgresql/${PG_MAJOR}/extension/ulid*.* /usr/share/postgresql/${PG_MAJOR}/extension/ diff --git a/README.md b/README.md index a80d133..e100eb0 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ ulid=# EXPLAIN ANALYSE INSERT INTO ulid_keys(id) SELECT gen_ulid() FROM generate
-## Monotonicity +### Monotonicity Monotony ensures guarantees k-sorting order on the same postgres instance. @@ -178,13 +178,13 @@ ulid=# EXPLAIN ANALYZE INSERT INTO users (name) SELECT 'Client 2' FROM generate_ -### Pros +#### Pros 1. Monotonic ULIDs are better for indexing, as they are sorted by default. 2. Monotonic ULIDs slightly faster than `gen_ulid()` when generating lots of ULIDs within one millisecond. Because, in this case, there is no need to generate random component of ULID. Instead it is just incremented. -### Cons +#### Cons 1. Previously generated ULID is saved in shmem and accessed via LWLock. i.e. it is exclusive for function invocation within database. Theoretically this can lead to slowdowns. diff --git a/docker/config-postgres.sh b/docker/config-postgres.sh new file mode 100755 index 0000000..3f29fd1 --- /dev/null +++ b/docker/config-postgres.sh @@ -0,0 +1,2 @@ +#!/usr/bin/env bash +echo "shared_preload_libraries = 'ulid'" >> $PG_DATA/postgresql.conf diff --git a/install-extensions.sql b/docker/install-extensions.sql similarity index 100% rename from install-extensions.sql rename to docker/install-extensions.sql From c6a9e7b676db68265cee468eb1b249b2a437d4f6 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 15:06:02 +0400 Subject: [PATCH 11/16] at last, get the docker config proper --- CHANGELOG.md | 2 +- Makefile | 4 ++-- docker/config-postgres.sh | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8af0cb1..9abd3c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ## 0.1.4 * With a timezone issue with unit tests * Upgrade prgx to 0.11.1 -* Rework Dockerfile +* Reworked Dockerfile - multi-stage, better extension configuration, added a Makefile with 'all' and 'run' targets * Improve README ## 0.1.3 diff --git a/Makefile b/Makefile index 5604c85..d770778 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ all: - docker build -t mypsql --build-arg="PG_MAJOR=16" . + docker build -t postgresql-ulid --build-arg="PG_MAJOR=16" . run: - docker run -p 5432:5432 mypsql \ No newline at end of file + docker run -p 5432:5432 postgresql-ulid \ No newline at end of file diff --git a/docker/config-postgres.sh b/docker/config-postgres.sh index 3f29fd1..0748ebd 100755 --- a/docker/config-postgres.sh +++ b/docker/config-postgres.sh @@ -1,2 +1,2 @@ #!/usr/bin/env bash -echo "shared_preload_libraries = 'ulid'" >> $PG_DATA/postgresql.conf +echo "shared_preload_libraries = 'ulid'" >> ~/data/postgresql.conf From 7e7e6ac81988fdc2d886cfd50e54c09878d2bca3 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 15:47:29 +0400 Subject: [PATCH 12/16] fix README --- Dockerfile | 23 +++++------------------ README.md | 16 ++++++++++++---- 2 files changed, 17 insertions(+), 22 deletions(-) diff --git a/Dockerfile b/Dockerfile index 1c0154c..0d279c2 100644 --- a/Dockerfile +++ b/Dockerfile @@ -37,32 +37,19 @@ RUN cargo install cargo-pgrx --version 0.11.1 --locked # init postgress dev env for target version RUN cargo pgrx init --pg${PG_MAJOR} $(which pg_config) -# Compile as ROOT to avoid a permission denied when copying to /usr/share/postgresql -# USER root - +# move the code COPY . . +# compile and package RUN cargo pgrx package - -# RUN chown -R postgres:postgres /home/postgres -# RUN chown -R postgres:postgres /usr/share/postgresql/${PG_MAJOR}/extension -# RUN chown -R postgres:postgres /usr/lib/postgresql/${PG_MAJOR}/lib - # multi-stage - let's start clean FROM postgres:${PG_MAJOR} -COPY --from=build /home/postgres/target/release/ulid-pg${PG_MAJOR}/ / +# copy & configure the entension +COPY --from=build --chown=root /home/postgres/target/release/ulid-pg${PG_MAJOR}/ / COPY --from=build /home/postgres/docker/* /docker-entrypoint-initdb.d/ -# # COPY --from=build /home/postgres/${PG_MAJOR}/extension/ulid.control /home/postgres/${PG_MAJOR}/extension/ulid.control -# COPY --from=build /usr/share/postgresql/${PG_MAJOR}/extension/ulid*.* /usr/share/postgresql/${PG_MAJOR}/extension/ -# COPY --from=build /usr/lib/postgresql/${PG_MAJOR}/lib/ulid.so /usr/lib/postgresql/${PG_MAJOR}/lib/ulid.so -# # why? convenient, but should stick to upstream behaviors. -# USER postgres -# # allow deployment without a password +# allow deployment without a password ENV POSTGRES_HOST_AUTH_METHOD=trust ENV USER=postgres - -# add comma for more shared_preload_libraries=A,B,C -# CMD ["postgres","-c","shared_preload_libraries=ulid"] \ No newline at end of file diff --git a/README.md b/README.md index e100eb0..f05b94a 100644 --- a/README.md +++ b/README.md @@ -205,7 +205,7 @@ The extension consist of 3 files 1. **ulid--0.1.4.sql** & **ulid.control** - the extension configuration file, to deploy in SHAREDIR 2. **ulid.so** - the extension itself, to deploy in LIBDIR -edit postgresql.conf, add the following line +edit *postgresql.conf*, add the following line: ```conf shared_preload_libraries = 'ulid' # (change requires restart) @@ -252,6 +252,14 @@ CREATE TABLE users ( ); ``` +Insert records + +```SQL +INSERT INTO users values (DEFAULT, 'Olivier'); +``` + + + Operate it normally with text in queries: ```sql @@ -272,14 +280,14 @@ SELECT id::uuid FROM users WHERE id; ### Do not confuse ULID's internal date with the record creation date -They are indeed very similar at first sight, but the dates have different meanings and more importantly a different lifecycle. +They are indeed quite similar at first glance, yet the dates have different connotations and, more significantly, a distinct life cycle. **I would strongly advise against** using ulid as a create_date column for the following reasons: -* First an index of a date column will be faster than on a random-date-ordered guid. +* First an index is faster on a date column than on a random-date-ordered guid. thanks to its randomness. * Shit happens - loss of data, code mistakes, migrations - you may have to change one of these dates without impacting the other. * You may decide to create ULIDs asynchronously or in advence, therefore dissociating generation from record creation. -* In the end they are two different things: the **id's** creation date vs the **record's** creation date. Typically, in IT we get much better results when we split concerns. +* In the end they are two different things: the **id's creation date** vs the **record's creation date**. Typically, in IT we get much better results when by spliting concerns. ## Building From 2540e9ee8aee4a486dec7e0a6aba42db1b19c403 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 16:12:53 +0400 Subject: [PATCH 13/16] readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index f05b94a..b5f5a04 100644 --- a/README.md +++ b/README.md @@ -338,7 +338,10 @@ Last, buid a postgres distribution with builtin ulid support ```shell # ensure docker is up +# to build the docker image make +# to run it +make run ``` Further details can be found by following [this guide](https://github.com/tcdi/pgrx/blob/master/cargo-pgrx/README.md#installing-your-extension-locally). From 9a1fa4b7fdbce1337a7c70a2651194f6ae27eefa Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 23:25:59 +0400 Subject: [PATCH 14/16] formatting issue --- src/lib.rs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index b5fff88..e077824 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -189,15 +189,19 @@ mod tests { #[pg_test] fn test_ulid_to_timestamp() { - let result = - Spi::get_one::<&str>(&format!("set timezone TO 'UTC'; SELECT '{TEXT}'::ulid::timestamp::text;")).unwrap(); + let result = Spi::get_one::<&str>(&format!( + "set timezone TO 'UTC'; SELECT '{TEXT}'::ulid::timestamp::text;" + )) + .unwrap(); assert_eq!(Some(TIMESTAMP), result); } #[pg_test] fn test_timestamp_to_ulid() { - let result = - Spi::get_one::<&str>(&format!("set timezone TO 'UTC'; SELECT '{TIMESTAMP}'::timestamp::ulid::text;")).unwrap(); + let result = Spi::get_one::<&str>(&format!( + "set timezone TO 'UTC'; SELECT '{TIMESTAMP}'::timestamp::ulid::text;" + )) + .unwrap(); assert_eq!(Some("01GV5PA9EQ0000000000000000"), result); } From ad5a102e8d92459631272cd7ba8dc9171b40d477 Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Thu, 30 Nov 2023 23:26:08 +0400 Subject: [PATCH 15/16] typo in changelof --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9abd3c1..5dfd19b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog ## 0.1.4 -* With a timezone issue with unit tests +* Fixed a timezone issue with unit tests * Upgrade prgx to 0.11.1 * Reworked Dockerfile - multi-stage, better extension configuration, added a Makefile with 'all' and 'run' targets * Improve README From ea9f2f818bc69a403b9f0fae783c690205d24e3f Mon Sep 17 00:00:00 2001 From: Olivier Refalo Date: Fri, 1 Dec 2023 11:53:38 +0400 Subject: [PATCH 16/16] fix typos --- .gitignore | 2 +- Dockerfile | 2 +- Makefile | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 9b8efed..865d4a7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ target Cargo.lock -.vscode/ \ No newline at end of file +.vscode/ diff --git a/Dockerfile b/Dockerfile index 0d279c2..943a4d0 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -# use 12, 13, 14, 15, 15 +# use 12, 13, 14, 15, 16 ARG PG_MAJOR FROM postgres:${PG_MAJOR} as build diff --git a/Makefile b/Makefile index d770778..8195de0 100644 --- a/Makefile +++ b/Makefile @@ -2,4 +2,4 @@ all: docker build -t postgresql-ulid --build-arg="PG_MAJOR=16" . run: - docker run -p 5432:5432 postgresql-ulid \ No newline at end of file + docker run -p 5432:5432 postgresql-ulid