Merge pull request #101 from supabase/docs

Docs

Author: imor

docs/assets/favicon.ico

@@ -0,0 +1,29 @@
+# `dbdev`
+
+<p>
+<a href=""><img src="https://img.shields.io/badge/postgresql-14+-blue.svg" alt="PostgreSQL version" height="18"></a>
+<a href="https://github.com/supabase/dbdev/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/markdown-subtemplate.svg" alt="License" height="18"></a>
+<a href="https://github.com/supabase/dbdev/actions/workflows/pgTAP.yaml"><img src="https://github.com/supabase/dbdev/actions/workflows/pgTAP.yaml/badge.svg" alt="pgTAP Tests" height="18"></a>
+<a href="https://github.com/supabase/dbdev/actions/workflows/cli.yaml"><img src="https://github.com/supabase/dbdev/actions/workflows/cli.yaml/badge.svg" alt="CLI" height="18"></a>
+
+</p>
+
+---
+
+**Documentation**: <a href="https://supabase.github.io/dbdev" target="_blank">https://supabase.github.io/dbdev</a>
+
+**Source Code**: <a href="https://github.com/supabase/dbdev" target="_blank">https://github.com/supabase/dbdev</a>
+
+---
+
+## Overview
+
+dbdev is a package manager for Postgres [trusted lanuguage extensions](https://github.com/aws/pg_tle) (TLEs). It consists of:
+
+- [database.dev](https://database.dev): our first-party package registry to store and distribute TLEs.
+- dbdev CLI: a CLI for publishing TLEs to a registry.
+- dbdev client: an in-database client for installing TLEs from registries.
+
+If you want to publish your own TLE, you will need the dbdev CLI. Follow its [installation instructions](install.md) to get started.
+
+If you want to install an extension from the registry, you will need the SQL dbdev client. Follow its [installation instructions](https://database.dev/installer) to enable it in your database.

docs/index.md

@@ -0,0 +1,17 @@
+The dbdev CLI is required to publish your TLE to [database.dev](https://database.dev/).
+
+## 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))
+
+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.
+
+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```.
+
+
+Now you're ready to [publish your first package](publish.md).

docs/install.md

@@ -0,0 +1,25 @@
+Before you can publish your TLE, you need to authenticate with [database.dev](https://database.dev/).
+
+### Login to database.dev
+
+If you don't have an account, [sign-up for one](https://database.dev/sign-up) on the website. Then follow the steps below:
+
+1. Make sure you are logged into the `database.dev` website.
+2. Navigate to the **Access Tokens** page from the account drop-down at top right.
+3. Click **New Token**.
+4. Enter a token name and click **Create Token**.
+5. Copy the generated token. Note that this is the only time the token will be shown.
+6. On the terminal, run the `dbdev login` command.
+7. Paste the token you copied.
+
+You are now logged into `database.dev`.
+
+### Publish TLE
+
+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:
+
+```
+dbdev publish --path /all_tles/my_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).

docs/publish.md

@@ -0,0 +1,2 @@
+mkdocs
+mkdocs-material

docs/requirements_docs.txt

@@ -0,0 +1,35 @@
+site_name: dbdev
+site_url: https://supabase.github.io/dbdev
+site_description: A package manager for PostgreSQL trusted language extensions
+
+repo_name: supabase/dbdev
+repo_url: https://github.com/supabase/dbdev
+
+nav:
+    - Welcome: 'index.md'
+    - Install CLI: 'install.md'
+    - Publish a Package: 'publish.md'
+
+theme:
+    name: 'material'
+    favicon: 'assets/favicon.ico'
+    logo: 'assets/favicon.ico'
+    homepage: https://supabase.github.io/dbdev
+    features:
+      - navigation.expand
+    palette:
+        primary: black
+        accent: light green
+
+markdown_extensions:
+    - pymdownx.highlight:
+        linenums: true
+        guess_lang: false
+        use_pygments: true
+        pygments_style: default
+    - pymdownx.superfences
+    - pymdownx.tabbed:
+        alternate_style: true
+    - pymdownx.snippets
+    - pymdownx.tasklist
+    - admonition

mkdocs.yaml

@@ -57,6 +57,26 @@ create extension "supabase-dbdev";
 select dbdev.install('supabase-dbdev');
 drop extension if exists "supabase-dbdev";
 create extension "supabase-dbdev";
+\`\`\`
+
+## Use
+
+Once the client is installed, you an install a TLE available on [database.dev](https://database.dev/) by running SQL that looks like the following:
+
+\`\`\`sql
+select dbdev.install(<extension_name>);
+create extension <extension_name>
+    schema <schema>
+    version <version>;
+\`\`\`
+
+For example, to install [pg_headerkit](https://database.dev/burggraf/pg_headerkit) version \`1.0.0\` in schema \`public\` run:
+
+\`\`\`sql
+select dbdev.install('burggraf-pg_headerkit');
+create extension "burggraf-pg_headerkit"
+    schema 'public'
+    version '1.0.0';
 \`\`\``}
         </Markdown>
       </div>