Skip to content

Commit

Permalink
add 'structure of an extension' docs
Browse files Browse the repository at this point in the history
  • Loading branch information
imor committed Sep 29, 2023
1 parent 768b0bb commit fbe18f0
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 0 deletions.
37 changes: 37 additions & 0 deletions docs/extension_structure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
A Postgres [trusted lanuguage extension](https://github.com/aws/pg_tle) (TLE) consists of the following files:

1. Script files. These files contain the SQL commands to create the extension's objects.
2. Control files. These files contain basic properties of the extension itself.

For an extension to be valid, one file of each type must be present in an extension. For example, if you want to create an extension named `my-extension`, create the following folder structure:

* my-extension
* my-extension.control
* my-extension--0.0.1.sql

In the above example, the `my-extension` folder contains the extension files. Names of the files are important. The control file should be named `<extension_name>.control` and the script file should be named `<extension_name>--<extension_version>.sql`.

## Control Files
A control file contains metadata about the extension in key-value pairs. The most common keys that you should consider setting are the following:

* default_version (string). The version to use if the user doesn't provide one in the `create extension` command.
* comment (string). Think of this as the description of the extension.
* requires (string). A comma separated list of extensions that this extension depends on.
* relocatable (boolean). Set to true if the extension's objects can be moved to a different schema after they are created.
* superuser (boolean). Set to true if only superusers should be able to create this extension.

For example, the [pgjwt extenion's control file](https://github.com/michelp/pgjwt/blob/master/pgjwt.control) looks like this:

```control
# pgjwt extension
comment = 'JSON Web Token API for Postgresql'
default_version = '0.2.0'
relocatable = false
requires = pgcrypto
superuser = false
```

For a complete list of keys available in a control file, refer to [Postgres documentation](https://www.postgresql.org/docs/current/extend-extensions.html#EXTEND-EXTENSIONS-FILES).

## Script Files
Script files contain the SQL objects to be created by the extension.
1 change: 1 addition & 0 deletions mkdocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ nav:
- Welcome: 'index.md'
- Install CLI: 'install.md'
- Publish a Package: 'publish.md'
- Structure of a Postgres Extension: 'extension_structure.md'

theme:
name: 'material'
Expand Down

0 comments on commit fbe18f0

Please sign in to comment.