Merge pull request #104 from supabase/extension_structure_docs

Extension structure docs

Author: imor

docs/extension_structure.md

@@ -0,0 +1,83 @@
+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
+    - README.md
+
+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`. The readme file should be named `README.md` (case sensitive).
+
+## 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). A comment added to the extension object created in the database.
+- 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 extension'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).
+
+### Syntax
+
+A control file contains key-value pairs. Each pair should be on a separate line. Empty lines are ignored. Text after a `#` is a comment and is also ignored. Keys should start with a letter and contain only letters or digits. The `=` sign following a key is optional, but there must be at least one whitespace after a key if `=` is omitted. Values can be either a boolean or a string. Valid values for a boolean are `true` or `false`. Strings are anything between a pair of single quotes. If you want to include a single quote in the middle of a string, use `''` to escape it. A complete list of escape sequences is:
+
+1. `\b` - backspace
+2. `f` - formfeed
+3. `\n` - newline
+4. `\r` - carriage return
+5. `\t` - tab
+6. `''` - single quote
+
+Strings which do not contain whitespace or escape sequences can be written without the surrounding single quotes.
+
+Some examples of valid control file syntax follow:
+
+```
+# A boolean value
+relocatable = true
+
+# `=` is optional
+superuser false
+
+# A string
+comment = 'a comment for the extension'
+
+# A string without quotes should not have whitespace or escape sequences
+comment = ACommentForTheExtension
+
+# A string with escapse sequences
+comment = 'A double quote '' and a newline \n'
+```
+
+
+## Script Files
+
+Script files contain the SQL commands to create or modify database objects. These database objects can be, but are not limited to, tables, views, functions, types, operators etc. For example, the [pgjwt's `pgjwt--0.1.1.sql` file](https://github.com/michelp/pgjwt/blob/master/pgjwt--0.1.1.sql) contains definitions for functions which the extension adds to the database. One exception to the SQL commands which can exist in a script file are transaction control commands like `BEGIN`, `COMMIT`, `ROLLBACK` etc.
+
+You might have noticed a strange line at the beginning of the [`pgjwt-0.1.1.sql` file](https://github.com/michelp/pgjwt/blob/master/pgjwt--0.1.1.sql) starting with `\echo`. This line prevents the script file from being run accidentally in `psql`. Lines starting with `\echo` are run only in `psql` but are ignored when the script file is executed by the [`CREATE EXTENSION` command](https://www.postgresql.org/docs/current/sql-createextension.html). It is recommended that you include such a line at the beginning of your script file.
+
+### Update Scripts
+
+Update scripts are used to update an installed extension. An update script should be named `<extension_name>--<old_version>--<new_version>.sql`. For example if version `1.0` of `my-extension` was published already and you want to publish a new version `1.1` you need to create `my-extension--1.0--1.1.sql`. Update scripts can create new database object or modify/delete existing objects created by the previous version of the extension.
+
+## README.md File
+
+README.md file contains documentation for the extension in the [markdown](https://en.wikipedia.org/wiki/Markdown) format. The documentation typically contains installation and usage instructions about the extension.

docs/install.md

@@ -2,14 +2,14 @@ The dbdev CLI is required to publish your TLE to [database.dev](https://database
 
 ## Installation
 
-Binaries for dbdev CLI are available for Linux, Windows and macOS platforms. Visit the [dbdev releases page](https://github.com/supabase/dbdev/releases) to download a binary for your OS. The downloaded binary should be placed in a folder which is in your [PATH](https://en.wikipedia.org/wiki/PATH_(variable))
+Binaries for dbdev CLI are available for Linux, Windows and macOS platforms. Visit the [dbdev releases page](https://github.com/supabase/dbdev/releases) to download a binary for your OS. The downloaded binary should be placed in a folder which is in your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)).
 
 Alternatively, you can build the binary from source. You will need to have [Rust installed](https://www.rust-lang.org/tools/install) on your system. To build from source:
 
 1. Clone the repo: ```git clone https://github.com/supabase/dbdev.git```.
 2. Change directory to `dbdev`: ```cd dbdev```.
 3. Build: ```cargo install --release```.
-4. Copy the `dbdev` binary in `target/release` to a folder in you PATH.
+4. Copy the `dbdev` binary in `target/release` to a folder in your PATH.
 
 If you have [cargo-install](https://doc.rust-lang.org/cargo/commands/cargo-install.html), you can perform all the above steps with a single command: ```cargo install --git https://github.com/supabase/dbdev.git dbdev```.
 

docs/publish.md

@@ -1,4 +1,4 @@
-Before you can publish your TLE, you need to authenticate with [database.dev](https://database.dev/).
+Before you can publish your extension, you need to authenticate with [database.dev](https://database.dev/).
 
 ### Login to database.dev
 
@@ -14,12 +14,42 @@ If you don't have an account, [sign-up for one](https://database.dev/sign-up) on
 
 You are now logged into `database.dev`.
 
-### Publish TLE
+### Publish Your First Extension
 
-To publish a TLE, run the `dbdev publish` command. For example, to publish a TLE in the `/all_tles/my_tle` folder run the following:
+Let's create your first extension. Create a folder which will contain the extension:
 
 ```
-dbdev publish --path /all_tles/my_tle
+mkdir my_first_tle
+cd my_first_tle
 ```
 
-Your TLE is now published to `database.dev` and visible at `https://database.dev/<handle>/<package_name>`. Users can install it using the [dbdev in-database client](https://database.dev/installer).
+Next create a `hello_world--0.0.1.sql` file, which will contain your extension's SQL objects.  Add the following function definition to this file:
+
+```sql
+create function greet(name text default 'world')
+  returns text language sql
+as $$ select 'hello, ' || name; $$;
+```
+
+Let's also add some docs about this extension. Create a `README.md` file and add the following content to it:
+
+```
+The `hello_world` extension provides a `greet` function, which returns a greeting.
+```
+
+Lastly, add a `hello_world.control` file with the following key-value pairs:
+
+```
+default_version = 0.0.1
+comment = 'An extension to generate greetings'
+```
+
+Your extension is ready to publish. Its name is `hello_world` and version is `0.0.1`. For details about what constitutes a valid extension, read about the [Structure of an Extension](extension_structure.md).
+
+Now run the `dbdev publish` command to publish it.
+
+```
+dbdev publish --path /path/to/my_first_tle
+```
+
+Your extension is now published to `database.dev` and visible under your account profile. You can visit your account profile from the account drop-down at the top right. Users can now install your extension using the [dbdev in-database client](https://database.dev/installer).

mkdocs.yaml

@@ -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'