readme

Author: pyramation

packages/ast/Makefile

@@ -1,5 +1,5 @@
 EXTENSION = ast
-DATA = sql/ast--0.0.1.sql
+DATA = sql/ast--13.0.1.sql
 
 PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)

packages/ast/ast.control

@@ -1,6 +1,6 @@
 # ast extension
 comment = 'ast extension'
-default_version = '0.0.1'
+default_version = '13.0.1'
 module_pathname = '$libdir/ast'
 requires = 'plpgsql,uuid-ossp'
 relocatable = false

packages/ast/package.json

@@ -51,4 +51,4 @@
       "__fixtures__"
     ]
   }
-}
+}

packages/ast/sql/ast--0.0.1.sql renamed to packages/ast/sql/ast--13.0.1.sql

@@ -10,12 +10,19 @@ For dynamic SQL, string concatenation can be problematic, and AST trees are the
 
 Written entirely in plpgsql and can be installed anywhere, even in managed RDBMS environments that don't support untrusted extensions.
 
-## Schemas of interest
+## Areas of interest
+
+### schemas 
 
  - `deparser` contains the deparser [(the `deparse()` function)](packages/ast/deploy/schemas/deparser/procedures/deparse.sql) — where the magic happens ✨ 
  - `ast` contains [tools for building AST trees](packages/ast/deploy/schemas/ast/procedures/types.sql)
  - `ast_helpers` contains [Helpers for higher level AST trees, like `create_table`](packages/ast/deploy/schemas/ast_helpers/procedures/helpers.sql)
 
+### extension
+
+While the project uses [sqitch](https://sqitch.org/), we've bundled it into a single file and extension using [launchql/cli](https://github.com/launchql/launchql)
+
+ - the extension lives in [packages/ast/sql](packages/ast/sql)
 ## Usage
 
 Use the `deparser.deparse()` function to deparse Postgres AST trees, in SQL:
@@ -62,6 +69,25 @@ produces
 SELECT mt.my_field FROM my_schema_name.my_table_name AS mt WHERE mt.id = 2
 ```
 
+#### create table
+
+```sql
+select deparser.deparse(
+    ast_helpers.create_table(
+		v_schema_name := 'my_schema_name',
+		v_table_name := 'my_table_name'
+	)
+);
+```
+
+produces 
+
+```sql
+CREATE TABLE my_schema_name.my_table_name (
+  
+);
+```
+
 #### alter table add column
 
 ```sql
@@ -85,18 +111,23 @@ ADD
     COLUMN mycolumn pg_catalog.Geometry(Polygon, 4326);
 ```
 
-#### drop function
+#### rename column
 
 ```sql
-SELECT deparser.deparse(ast_helpers.drop_function(
-  v_schema_name := 'schema',
-  v_function_name := 'name'
-));
+select deparser.expression(
+	ast_helpers.alter_table_rename_column(
+		v_schema_name := 'myschema',
+		v_table_name := 'mytable',
+		v_old_column_name := 'my-column1',
+		v_new_column_name := 'mycolumn2'
+	)
+);
 ```
-produces
+
+produces 
 
 ```sql
-DROP FUNCTION schema.name;
+ALTER TABLE myschema.mytable RENAME COLUMN "my-column1" TO mycolumn2;
 ```
 
 #### alter table set column data type
@@ -121,6 +152,53 @@ ALTER TABLE
 ALTER COLUMN
     mycolumn1 TYPE mycustomtype USING mycolumn1::mycustomtype;
 ```
+#### create index
+
+```sql
+select deparser.deparse(
+	ast_helpers.create_index(
+		v_index_name := 'v_index_name',
+		v_schema_name := 'v_schema_name',
+		v_table_name := 'v_table_name',
+		v_fields := '{a,b,c}',
+		v_include_fields := '{a,b}',
+		v_unique := TRUE,
+		v_accessMethod := 'GIST'
+	)
+);
+```
+
+produces
+
+```sql
+CREATE UNIQUE INDEX v_index_name ON v_schema_name.v_table_name USING GIST (a, b, c) INCLUDE (a, b);
+```
+
+### add check constraint
+
+```sql
+select deparser.expression(
+    ast_helpers.alter_table_add_check_constraint(
+        v_schema_name := 'schema_name',
+        v_table_name := 'table_name',
+        v_constraint_name := 'constraint_name',
+        v_constraint_expr := ast_helpers.matches(
+            v_lexpr := ast.column_ref(
+                v_fields := to_jsonb(ARRAY[
+                    ast.string('email')
+                ])
+            ),
+            v_regexp := '^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+[.][A-Za-z]+$'
+        )
+    )
+);
+```
+
+produces
+
+```sql
+ALTER TABLE schema_name.table_name ADD CONSTRAINT constraint_name CHECK (email ~* '^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+[.][A-Za-z]+$');
+```
 
 #### create function
 
@@ -177,6 +255,20 @@ CREATE FUNCTION schema.name (
 $LQLCODEZ$ LANGUAGE plpgsql VOLATILE;
  ```
 
+ #### drop function
+
+```sql
+SELECT deparser.deparse(ast_helpers.drop_function(
+  v_schema_name := 'schema',
+  v_function_name := 'name'
+));
+```
+produces
+
+```sql
+DROP FUNCTION schema.name;
+```
+
 #### table grant
 
 ```sql
@@ -307,6 +399,89 @@ ALTER POLICY mypolicy
 );
 ```
 
+#### create trigger
+
+```sql
+select
+	deparser.deparse(
+		ast_helpers.create_trigger(
+			v_trigger_name := 'v_trigger_name',
+			v_schema_name := 'v_schema_name',
+			v_table_name := 'v_table_name',
+			v_trigger_fn_schema := 'v_trigger_fn_schema',
+			v_trigger_fn_name := 'v_trigger_fn_name',
+			v_whenClause := ast.a_expr(
+				v_kind := 'AEXPR_DISTINCT',
+				v_lexpr := ast.column_ref(
+					to_jsonb(ARRAY [ ast.string('old'),ast.string('field-b') ])
+				),
+				v_name := to_jsonb(ARRAY [ast.string('=')]),
+				v_rexpr := ast.column_ref(
+					to_jsonb(ARRAY [ ast.string('new'),ast.string('field-b') ])
+				)
+			),
+			v_params := NULL,
+			v_timing := 2,
+			v_events := 16
+		)
+	);
+```
+
+produces
+
+```sql
+CREATE TRIGGER v_trigger_name 
+ BEFORE UPDATE ON v_schema_name.v_table_name 
+ FOR EACH ROW 
+ WHEN (OLD."field-b" IS DISTINCT FROM NEW."field-b") 
+ EXECUTE PROCEDURE v_trigger_fn_schema.v_trigger_fn_name ( );
+```
+
+### trigger distinct fields
+
+```sql
+select deparser.deparse( 
+  ast_helpers.create_trigger_distinct_fields(
+    v_trigger_name := 'my-trigger',
+    v_schema_name := 'my-schema',
+    v_table_name := 'my-table',
+    v_trigger_fn_schema := 'my-tg-fn-schema',
+    v_trigger_fn_name := 'my-tg-fn',  
+    v_fields := ARRAY['name', 'description']::text[],
+    v_timing := 2,
+    v_events := 4 | 16)
+  )
+ ```
+
+ produces
+
+ ```sql
+CREATE TRIGGER "my-trigger" 
+ BEFORE INSERT OR UPDATE ON "my-schema"."my-table" 
+ FOR EACH ROW 
+ WHEN (OLD.name IS DISTINCT FROM NEW.name OR OLD.description IS DISTINCT FROM NEW.description) 
+ EXECUTE PROCEDURE "my-tg-fn-schema"."my-tg-fn" ( );
+ ```
+
+#### fixtures
+
+```sql
+select deparser.deparse(
+    ast_helpers.create_fixture(
+     	v_schema := 'myschema',
+     	v_table := 'mytable',
+     	v_cols := '{a,b,c,d}',
+     	v_values := '[[{"type":"int","value":1},{"type":"text","value":"textme"},{"type":"float","value":1.3},{"type":"bool","value":true}],[{"type":"int","value":2},{"type":"text","value":"yolo"},{"type":"float","value":1.3},{"type":"bool","value":false}]]'
+	)
+);
+```
+
+produces
+
+```sql
+INSERT INTO myschema.mytable (a, b, c, d) VALUES (1, 'textme', 1.3, TRUE), (2, 'yolo', 1.3, FALSE);
+```
+
 #### denormalized fields trigger
 
 ```sql
@@ -337,6 +512,33 @@ new.f;
   END;
 ```
 
+#### comments
+
+the `smart_comments` helpers is meant for use with [graphile](https://www.graphile.org/postgraphile/), but you can use any comment string
+
+```sql
+select deparser.expression(
+    ast.comment_stmt(
+        v_objtype := 'OBJECT_TABCONSTRAINT',
+        v_object := to_jsonb(ARRAY[
+            ast.string('my_schema'),
+            ast.string('my_table'),
+            ast.string('my_constraint')
+        ]),
+        v_comment := ast_helpers.smart_comments(
+			tags := '{"type":"object","props":["id","url","title","tags"]}'::jsonb,
+			description := 'my description'
+		)
+    )
+);
+```
+
+produces
+
+```sql
+COMMENT ON CONSTRAINT my_constraint ON my_schema.my_table IS E'@type object\n@props id\n@props url\n@props title\n@props tags\nmy description'
+```
+
 ## installation
 
 If you know how to use extensions, or perhaps even just grab the sql and run with it, you can use the bundled extension here [packages/ast/sql](packages/ast/sql). If you run it manually, you just need to make sure to install the `uuid-ossp` extension. 
@@ -435,10 +637,12 @@ Our latest is built with `13-latest` branch from libpg_query
 |--------------------------|-------------|---------------------|---------|
 | 13                       | 13-latest   | Active development  | `latest`
 
-## Special Thanks and Resources
+## Special Thanks and our Community
 
 * [pgsql-parser](https://github.com/pyramation/pgsql-parser)
 * [libpg-query-node](https://github.com/pyramation/libpg-query-node)
 * [libpg_query](https://github.com/pganalyze/libpg_query)
 * [pg_query](https://github.com/lfittl/pg_query)
 * [sqitch](https://sqitch.org/)
+* [postgraphile](https://www.graphile.org/postgraphile/)
+* [launchql](https://github.com/launchql/launchql)