docs: document how auto-create table works

timescale · May 21, 2023 · 228dd2f · 228dd2f
1 parent bcfd3e3
commit 228dd2f
Show file tree

Hide file tree

Showing 2 changed files with 139 additions and 18 deletions.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,14 +1,26 @@
 # Getting Started with the Influx Listener
 
 The easiest way to get started with the Influx Listener is to install
-it in a schema and launch a worker process.
+it in a schema and launch a worker process for that schema.
 
 ```sql
 CREATE EXTENSION influx WITH SCHEMA metrics;
-SELECT worker_launch('metrics', '8089');
+SELECT metrics.worker_launch('8089');
 ```
 
-This will spawn a single worker that will listen to socket 8089.
+This will spawn a single worker that will listen to socket 8089. The
+`worker_launch` procedure will assume that the worker is for that
+schema.
+
+> **NOTE:** PostgreSQL does not allow installing an extension multiple
+> times in the same database, so you cannot use this method to launch
+> workers for different schema. If you want to do that, you need to
+> use the [2-argument version of `worker_launch`][1]. If you do that,
+> however, you will not be able to start workers automatically in the
+> background since you can (currently) only give one schema for the
+> workers and not have several workers writing to different schema.
+
+[1]: procedures.md#function-worker_launch
 
 ## Automatically starting listeners
 
@@ -24,3 +36,11 @@ influx.database = my_database
 influx.role = influx       # defaults to superuser
 influx.workers = 10        # defaults to 4
 ```
+
+> **NOTE:** When pre-loading the library, it will not create the
+> schema nor add functions (such as [`_create`][2]) to the schema, so
+> before editing the configuration file, you should create the
+> extension in the database and schema that you want to use as
+> explained above.
+
+[2]: procedures.md#function-_create
diff --git a/docs/procedures.md b/docs/procedures.md
@@ -1,15 +1,14 @@
 # Reference Manual for `pg_influx`
 
-## Function `worker_launch`
+## Table of Contents
 
-Launch a new background worker.
+1. [Procedure `send_packet`](#procedure-send_packet)
+2. [Function `worker_launch`](#function-worker_launch)
+3. [Function `_create`](#function-_create)
 
-### Parameters
+## Function `worker_launch`
 
-|      Name | Type           | Description                         |
-|----------:|:---------------|:------------------------------------|
-| namespace | `regnamespace` | Namespace for the metrics.          |
-|   service | `text`         | Service for the worker to listen on |
+Launch a new background worker.
 
 The service is looked up using `getaddrinfo` so it is possible to
 either provide a port number of service name that will be translated
@@ -20,17 +19,58 @@ The function will bind to the first address suitable for receiving UDP
 traffic (using `AI_PASSIVE` and a NULL node name), which means that it
 is not possible to select the IP address to listen on.
 
-### Return value
+### Parameters
 
-Integer indicating the PID of the started worker. This can be used
-with [`pg_terminate_backend`][1] to terminate the backend.
+|      Name | Type           | Description                                                                     |
+|----------:|:---------------|:--------------------------------------------------------------------------------|
+| namespace | `regnamespace` | Namespace for the metrics. Optional. Defaults to the namespace of the function. |
+|   service | `text`         | Service for the worker to listen on                                             |
+
+### Returns
+
+An integer being the PID of the started worker. This can be used with
+[`pg_terminate_backend`][1] to terminate the backend.
 
 [1]: https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SIGNAL-TABLE
 
+### Examples
+
+If you have installed the extension in the schema `metrics` you can
+spawn a worker listening on socket 8089 using:
+
+```sql
+SELECT metrics.worker_launch('8089');
+```
+
+If you have installed the extension in the `public` schema (which is
+the default if you do not give a schema when using [`CREATE
+EXTENSION`]()) you can start a worker using:
+
+```sql
+SELECT worker_launch('metrics', '8089');
+```
+
+If you want to terminate a previously started worker, you can save the
+PID in a `psql` variable:
+
+```sql
+SELECT metrics.worker_launch('8089') as pid \gset
+   .
+   .
+   .
+SELECT pg_terminate_backend(:pid);
+```
+
 ## Procedure `send_packet`
 
 Send a UDP packet to a network address.
 
+The text string provided will be sent as an UDP packet to the host and
+service given by `service` and `hostname` parameters. Service and
+hostname lookup is done using `getaddrinfo` so it accepts both
+numerical IP addresses (both IPv4 and IPv6) as well as service names
+and also handles hostname resolution.
+
 ### Parameters
 
 |     Name | Type   | Description                                   |
@@ -39,9 +79,70 @@ Send a UDP packet to a network address.
 |  service | `text` | Service for the worker to listen on           |
 | hostname | `text` | Hostname to send to. Defaults to `localhost`. |
 
-The text string provided will be sent as an UDP packet to the host and
-service given by `service` and `hostname` parameters. Service and
-hostname lookup is done using `getaddrinfo` so it accepts both
-numerical IP addresses (both IPv4 and IPv6) as well as service names
-and also handles hostname resolution.
+## Function `_create`
+
+Create a table for a metric.
+
+This function is not intended to be called directly, even though it is
+possible. It is used by the workers to create a table for the metric
+when a table for the metric can't be found.
+
+When installing the extension, a default function is created in the
+schema where the extension is installed. The default function will
+create a table in the schema where the function is installed and with
+the following definition:
+
+|  Column | Type          | Description              |
+|--------:|:--------------|:-------------------------|
+|   _time | `timestamptz` | Timestamp of the metric. |
+|   _tags | `jsonb`       | Array of tag names.      |
+| _fields | `jsonb`       | Array of field names.    |
+
+> **NOTE:** If you replace this function you need to make sure that a
+> table with the same name as the metric is created. If you do not,
+> this function will be called again for each received metric.
+
+### Parameters
+
+|   Name | Type     | Description                                                                 |
+|-------:|:---------|:----------------------------------------------------------------------------|
+| metric | `name`   | Name of metric to create. The function should create a table with this name |
+|   tags | `name[]` | Array of tag names. Note that the values of the tags are not given.         |
+| fields | `name[]` | Array of field names. Note that the values of the fields are not given.     |
+
+### Returns
+
+A OID of type `regclass`, which is the OID of the created table. This
+OID will then be used when writing the metric.
+
+### Examples
+
+All the examples below assume that you have created a schema `metrics`
+for the metrics and installed the extension there:
+
+```sql
+CREATE SCHEMA metrics;
+CREATE EXTENSION influx WITH SCHEMA metrics;
+```
+
+To not create tables by default, you have to drop the function, but to
+do that, you first need to remove it from the extension using `ALTER
+TABLE`:
+
+```sql
+ALTER EXTENSION influx DROP FUNCTION metric._create;
+DROP FUNCTION db_create._create;
+```
+
+To use a function that creates a table that just creates the `_fields`
+column as a JSON (not JSONB) you can use the following definition:
 
+```sql
+CREATE OR REPLACE FUNCTION metrics._create(metric name, tags name[], fields name[])
+RETURNS regclass AS $$
+BEGIN
+   EXECUTE format('CREATE TABLE db_create.%I (_time timestamp, _fields json)', metric);
+   RETURN format('db_create.%I', metric)::regclass;
+END;
+$$ LANGUAGE plpgsql;
+```