v1.4.0 adds the GIT_BUNDLE_OPTS and ZIP_BUNDLE_OPTS environment variables.
The former is passed to git archive and the latter to zip, and let
additional options be passed to those commands. For example, the vectorize
extension’s release workflow sets GIT_BUNDLE_OPTS: --add-file META.json
because git archive archives only checked-in files, and META.json is not
checked in but generated from META.json.in.
v1.4.0 adds the GIT_BUNDLE_OPTS and ZIP_BUNDLE_OPTS environment variables.
The former is passed to git archive and the latter to zip, and let
additional options be passed to those commands. For example, the vectorize
extension’s release workflow sets GIT_BUNDLE_OPTS: --add-file META.json
because git archive archives only checked-in files, and META.json is not
checked in but generated from META.json.in.
v1.4.1 fixes an issue where git archive was never actually used to build a
release zip archive. This changed at some point without noticing due to the
introduction of the safe.directory configuration in recent versions of Git.
Inside the container the directory was never trusted, and the pgxn-bundle
command caught the error, decided it wasn’t working with a Git repository, and
used the zip command, instead.
As a result, a number of recent releases have included files they shouldn’t,
such as the contents of the .git directory. The fix
disables safe.directory so that the repository directory is always trusted
inside the container, as needed in GitHub actions.
If you use pgxn-bundle in a GitHub workflow, be aware that recent releases
(since November 2021 at least) include stuff that it should not, including the
.git directory (here’s a list) and patterns excluded in .gitattributes.
Your next release should be cleaner.
v1.4.1 also allows the setting of the PROFILE environment variable, so that
the default PROFILE=--Werror can be overridden.
v1.4.2 adds (and v1.4.3 improves, see below) git-archive-all to the image,
and the GIT_ARCHIVE_CMD environment variable to tell pgxn-bundle which archive
command to use, either archive or archive-all. The latter is useful for
repositories that use Git submodules and need to include their contents in the
release, as demonstrated in this plv8 pull request.
v1.4.2 also adds cmake and the libarchive-tools package to the image.
The latter bundles in libarchive tools like bsdtar and bsdcpio, which
might be useful for editing Zip files in place.
v1.4.3 passes the --force-submodules option to git-archive-all, because
otherwise submodules weren’t included in the bundle.
All of this should just start showing up in your GitHub workflows as long as
they use container: pgxn/pgxn-tools or container: pgxn/pgxn-tools@v1.
Questions? Post em in the #extensions channel on the Postgres Slack or to the attention of the PGXN Mastodon bot.
]]>Makefile in the How To. But the
most important change for new releases going forward is that version ordering
is now enforced. That means two things:]]>Makefile in the How To. But the
most important change for new releases going forward is that version ordering
is now enforced. That means two things:
v1.2.0 today and v1.1.0 tomorrow.The changes have been applied to the reindexing code, as well, which also prevents versions from being greater than in subsequent releases. That won’t come up very often—most of the time, I end up reindexing something that has just been released. But in the future I expect to add an interface for release managers to reindex their own distributions, so it may be that someone reindexes a release that’s a few versions old. Or not. But just in case, it’ll be handled.
So what are you going to release on PGXN today? Get to it!.
]]>Hi everybody!
I’m proud to tell you that a new version of PGXN Utils was released with this new features:
You can start a new extension with or without version control. By default
pgxn-utils supports git but it will not create a repository unless you use
--git option in the skeleton task.
You can try:
$ pgxn-utils skeleton my_cool_versioned_extension --git
When you create a new extension with git support in addition to creating the
skeleton, pgxn-utils will initialize a git repository and create the initial
commit.
Hi everybody!
I’m proud to tell you that a new version of PGXN Utils was released with this new features:
You can start a new extension with or without version control. By default
pgxn-utils supports git but it will not create a repository unless you use
--git option in the skeleton task.
You can try:
$ pgxn-utils skeleton my_cool_versioned_extension --git
When you create a new extension with git support in addition to creating the
skeleton, pgxn-utils will initialize a git repository and create the initial
commit.
Once you have your extension in a git repository your bundle will use only
the committed files to create the archive, but if your repository is dirty
then pgxn-utils will suggest that you to commit or stash your changes before
bundling.
You must be careful with new files not added to repository, because they will not be archived.
There are three default templates: sql, c and fdw. If you call
skeleton without specifying a template, sql is the default. But if your
extension will supply some C modules or you will create a FDW, you can create
the extension calling skeleton with a --template option.
Try:
$ pgxn-utils skeleton my_cool_c_extension --template=c
$ pgxn-utils skeleton my_cool_fdw_extension --template=fdw
The templates contain example code and some links to PostgreSQL documentation
that will try to help you to start coding. SQL and C templates contains some
test examples, and the example code will compile and pass make installcheck.
However, this code is intended to be an example, and you must write your own
tests and code.
If you don’t like the templates provided by pgxn-utils you can create you
own. Just create a directory with at least a META.json or META.json.tt
file and then use your directory as argument to the --template option.
To know how create your own template, see the examples in the templates directory.
If you have PGXN client installed you can change the command line from
pgxn-utils some_task to pgxn some_task and this will save you some typing.
See:
$ cd /tmp
$ pgxn skeleton --help
PGXN Utils version: 0.1.4
Usage:
pgxn skeleton extension_name
Options:
[--git] # Initialize a git repository after create the extension
-a, [--abstract=ABSTRACT] # Defines a short description to abstract
-p, [--target=TARGET] # Define the target directory
# Default: .
[--template=TEMPLATE] # The template that will be used to create the extension. Expected values are: sql, c, fdw
# Default: sql
-r, [--release-status=RELEASE_STATUS] # Initial extension's release status
-d, [--description=DESCRIPTION] # A long text that contains more information about extension
-b, [--generated-by=GENERATED_BY] # Name of extension's generator
-l, [--license=LICENSE] # The extension license
-t, [--tags=one two three] # Defines extension's tags
-v, [--version=VERSION] # Initial version
-m, [--maintainer=MAINTAINER] # Maintainer's name <maintainer@email>
Creates an extension skeleton in current directory
$ pgxn skeleton test
create test
create test/test.control
create test/.gitignore
create test/.template
create test/META.json
create test/Makefile
create test/README.md
create test/doc/test.md
create test/sql/test.sql
create test/sql/uninstall_test.sql
create test/test/expected/base.out
create test/test/sql/base.sql
$ cd test/
$ pgxn bundle
run make distclean from "."
create /tmp/test-0.0.1.zip
I hope you enjoy this version. “:)
]]>Here’s the reason: Only “stable” releases are indexed. The first and
second adaptive_estimator releases both have their release status set to
“testing”. The PGXN API only indexes stable releases. The idea behind that is
that you want most folks to continue using stable releases while you work on
testing new versions. So when users search the site, only the latest stable
release will appear in search results. Similarly, installing an extension via
the PGXN client, prefers the latest stable release by default. If you want
the most recent, you have to specify the --unstable or --testing option.
So, the upshot is, if you want your extension to appear in the full text search results on the PGXN, site, release a stable version.
That said, I first noticed this issue a while ago, and filed an issue with the idea that, if an extension is uploaded that is not stable, but there are no stable versions, then the extension should be indexed, anyway. The idea here is that, when you first upload it, you don’t have any existing users to keep on a stable release anyway, because there is no stable release. So perhaps we should go ahead and index it. A non-stable release would only be omitted from the index if there was an existing stable release.
Thoughts?
]]>$ pgxn install semver
$ pgxn load semver
$ psql
=# select 'foo'::semver;
ERROR: bad semver value 'foo': expected number at foo
LINE 1: select 'foo'::semver;
Error! Meaning: success!
The number of extensions on PGXN is steadily increasing, so we hope the client will make their adoption even easier.
The client is now extensible: either writing in Python to reuse some of the other commands implementation or writing new self-contained scripts in any language to be invoked by the pgxn commands dispatcher. The first client extensions are already available: PGXN Utils and PGXN:Meta:Validator are targeted for easier development of new extensions.
]]>$ pgxn install semver
$ pgxn load semver
$ psql
=# select 'foo'::semver;
ERROR: bad semver value 'foo': expected number at foo
LINE 1: select 'foo'::semver;
Error! Meaning: success!
The number of extensions on PGXN is steadily increasing, so we hope the client will make their adoption even easier.
The client is now extensible: either writing in Python to reuse some of the other commands implementation or writing new self-contained scripts in any language to be invoked by the pgxn commands dispatcher. The first client extensions are already available: PGXN Utils and PGXN:Meta:Validator are targeted for easier development of new extensions.
The client is released on PyPI, so installing is just:
$ sudo easy_install pgxnclient
Complete documentation and further links are available from the project homepage.
Any feedback is welcome; you can contact me and all the other people behind PGXN on the PGXN User Group. See you there!
]]>I’m proud to tell you that a new version of pgxn_utils was released!
Now you can release a distribution to PGXN in five steps!
First, install it:
gem install pgxn_utils
Second, create your extension, optionally overwrite some defaults:
mkdir $HOME/extensions
cd $HOME/extensions
pgxn_utils skeleton my_extension --maintainer "Dickson S. Guedes"
Third, code!
Fourth, bundle it:
pgxn_utils bundle my_extension
Extension generated at: /home/guedes/extensions/my_extension-0.0.1.zip
Fifth, release it:
pgxn_utils release my_extension-0.0.1.zip
Enter your PGXN username: guedes
Enter your PGXN password: ******
Trying to release my_cool_extension-0.0.1.zip ... released successfully!
Visit: https://manager.pgxn.org/distributions/my_cool_extension/0.0.1
Ah, you can export PGXN_USER and PGXN_PASSWORD if you are tired to type
your username and password every time.
I’m proud to tell you that a new version of pgxn_utils was released!
Now you can release a distribution to PGXN in five steps!
First, install it:
gem install pgxn_utils
Second, create your extension, optionally overwrite some defaults:
mkdir $HOME/extensions
cd $HOME/extensions
pgxn_utils skeleton my_extension --maintainer "Dickson S. Guedes"
Third, code!
Fourth, bundle it:
pgxn_utils bundle my_extension
Extension generated at: /home/guedes/extensions/my_extension-0.0.1.zip
Fifth, release it:
pgxn_utils release my_extension-0.0.1.zip
Enter your PGXN username: guedes
Enter your PGXN password: ******
Trying to release my_cool_extension-0.0.1.zip ... released successfully!
Visit: https://manager.pgxn.org/distributions/my_cool_extension/0.0.1
Ah, you can export PGXN_USER and PGXN_PASSWORD if you are tired to type
your username and password every time.
First change: the package name. The package is now called pgxnclient,
without the point. As Marti has commented, the point in the name could
create problems to some distributions which may have needed to munge it into a
shape fitting their naming constraints. So, in order to install the last
release you will need the command:
First change: the package name. The package is now called pgxnclient,
without the point. As Marti has commented, the point in the name could
create problems to some distributions which may have needed to munge it into a
shape fitting their naming constraints. So, in order to install the last
release you will need the command:
$ easy_install pgxnclient
The name of the entry point script is still pgxn and it shouldn’t change.
One of the new features in this release is the addition of commands drop, to
remove the the extensions of a distribution from a database (opposite of the
load command) and uninstall, to remove installed files from the system
(opposite of install).
Another change is the ability to work on a local zip or directory instead of using the API to get metadata and package from PGXN. The main goal of this feature is to help the packagers to test their packages with the client before submission, verifying that the data uploaded can be used in an automatized way.
A third change is in the install command: it previously required to be run
as root if, as likely, the PostgreSQL directories are system ones. I was
feeling this need slightly scary as download and build phases would have been
run as root too, so now sudo is invoked by the script only when installing,
with command line options allowing its customization.
What I feel mostly missing now is documentation: I know that adding it will force a big review of the code, adding missing comments, add tests to enforce what documented… so it’s something I will start tomorrow. Once documentation and code have converged there will also be a more sound basis to discuss about the client features. And dare version 0.2, maybe :)
Thanks everybody for the feedback. If you want to have a chat about the client or PGXN in general, the best place is the PGXN group. See you there!
]]>