Skip to content

Commit 3f070c0

Browse files
pyramationpyramation
committed
readme
1 parent c02c8fa commit 3f070c0

File tree

5 files changed

+206
-195
lines changed

5 files changed

+206
-195
lines changed

‎Makefile

+4-38
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ down:
1111
docker-compose down -v
1212

1313
ssh:
14-
docker exec -it launchql-postgres /bin/bash
14+
docker exec -it launchql-ast-postgres /bin/bash
1515

1616
install:
1717
$(MAKE) docker-install || $(MAKE) k8-install
@@ -20,56 +20,22 @@ dinstall:
2020
$(MAKE) docker-install
2121

2222
docker-install:
23-
docker exec launchql-postgres /sql-bin/install.sh
23+
docker exec launchql-ast-postgres /sql-bin/install.sh
2424

2525
k8-install:
2626
$(eval POD_NAME := $(shell kubectl get pods -l app=postgres -n webinc -o jsonpath="{.items[*].metadata.name}"))
2727
kubectl exec -n webinc -it $(POD_NAME) /sql-bin/install.sh
2828

29-
# lql dump --deps --project dbs --path $(WEBINC_PATH)/services/packages/graphql-server-service/bootstrap/app.sql
3029
dump:
3130
lql dump --deps --project dbs --path dump.sql
3231

3332
seed:
3433
createdb launchql
35-
lql deploy --recursive --database launchql --yes --project dbs
36-
lql deploy --recursive --database launchql --yes --project lql-svc-local
37-
38-
mods:
39-
createdb db-mods
40-
lql deploy --recursive --database db-mods --yes --project launchql-meta-modules
34+
lql deploy --recursive --database launchql --yes --project ast
4135

4236
deploy:
43-
@echo lql deploy --recursive --createdb --yes --project dbs --database launchql-db
44-
@echo lql deploy --recursive --createdb --yes --project db_modules --database webinc-db
45-
46-
meta:
47-
@cd packages/db_meta_utils && lql package
48-
@cd packages/db_meta_snippets && lql plan && lql package
49-
$(MAKE) install
50-
51-
generate:
52-
@cd packages/db_text && ./generate/generate.js
53-
@cd packages/db_text && lql package
54-
@cd packages/db_utils && lql package
55-
@cd packages/db_deps && lql package
56-
@cd packages/db_meta_utils && lql package
57-
@cd packages/db_meta_snippets && lql plan && lql package
58-
@cd packages/db_migrate && lql plan && lql package
59-
$(MAKE) install
60-
61-
gen:
62-
@cd packages/db_text && ./generate/generate.js
37+
@echo lql deploy --recursive --createdb --yes --project ast --database launchql-db
6338

6439
ast:
6540
@cd packages/ast && lql package
66-
@cd packages/ast_actions && lql package
67-
@cd packages/objects && lql package
68-
@cd packages/transactor && lql package
69-
@cd packages/db_migrate && lql package
70-
$(MAKE) install
71-
72-
objects:
73-
@cd packages/objects && lql package
74-
@cd packages/transactor && lql package
7541
$(MAKE) install

‎docker-compose.yml

+1-9
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
version: "3"
22
services:
33
postgres:
4-
container_name: launchql-postgres
4+
container_name: launchql-ast-postgres
55
image: pyramation/postgis
66
environment:
77
- "POSTGRES_USER=postgres"
@@ -14,11 +14,3 @@ services:
1414
- ./bin:/sql-bin
1515
- ./extensions:/sql-extensions
1616
- ./packages:/sql-packages
17-
deploy:
18-
resources:
19-
limits:
20-
cpus: '2'
21-
memory: 8G
22-
reservations:
23-
cpus: '2'
24-
memory: 8G

‎packages/ast/package.json

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
"name": "ast",
2+
"name": "@launchql/ast",
33
"version": "0.0.1",
44
"description": "PostgreSQL AST utils",
55
"author": "Dan Lynch <[email protected]>",
6-
"private": true,
6+
"private": false,
77
"scripts": {
88
"test": "FAST_TEST=1 launchql-templatedb && jest",
99
"test:watch": "FAST_TEST=1 jest --watch"
@@ -29,6 +29,7 @@
2929
"graphql": "^14.0.2",
3030
"graphql-tag": "2.10.3",
3131
"jest": "26.1.0",
32+
"jest-in-case": "1.0.2",
3233
"pgsql-deparser": "13.1.9",
3334
"pgsql-parser": "13.1.9",
3435
"prettier": "2.0.5",
@@ -42,4 +43,4 @@
4243
"__fixtures__"
4344
]
4445
}
45-
}
46+
}

‎readme.md

+193-38
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,242 @@
1-
# LaunchQL
1+
# PostgreSQL ASTs in PostgreSQL
22

3-
## API info
3+
This project is the plpgsql companion to https://github.com/pyramation/pgsql-parser. A PostgreSQL AST toolkit and deparser, written in pure plpgsql.
44

5-
If you're on the mobile dev team, this is probably useful!
5+
## Why?
66

7-
* [API info](docs/readme.md)
7+
Because string concatenation is bad, and ASTs are the DNA of software itself.
88

9-
## Cloud Functions
9+
### a note on compatibility
1010

11-
* [Cloud Functions](docs/cloud-fns.md)
11+
Written in pure plpgsql so that it can be installed anywhere, including managed RDBMS environments that don't support untrusted extensions.
12+
## Usage
1213

13-
* [Cloud Functions Quickstart](docs/cloud-functions-quickstart.md)
14+
Use the `deparser.deparse()` function to deparse Postgres ASTs, in SQL:
1415

15-
## postgres
16+
```sql
17+
select deparser.deparse( $1::jsonb );
18+
```
1619

17-
* [Policy Templates](docs/rls/templates.md)
18-
* [Postgres Testing](docs/postgres.md)
20+
## Examples
1921

20-
# Development
22+
#### alter table add column
2123

22-
## start the postgres db process
24+
```sql
25+
select
26+
deparser.expression(
27+
ast_helpers.alter_table_add_column(
28+
v_schema_name := 'myschema',
29+
v_table_name := 'mytable',
30+
v_column_name := 'mycolumn',
31+
v_column_type := 'Geometry(Polygon, 4326)' :: text
32+
)
33+
);
34+
```
2335

24-
First you'll want to start the postgres docker (you can also just use `docker-compose up -d`):
36+
produces
2537

26-
```sh
27-
make up
38+
```sql
39+
ALTER TABLE
40+
myschema.mytable
41+
ADD
42+
COLUMN mycolumn pg_catalog.Geometry(Polygon, 4326);
2843
```
2944

30-
## install modules
45+
#### drop function
3146

32-
Install modules
47+
```sql
48+
SELECT deparser.deparse(ast_helpers.drop_function(
49+
v_schema_name := 'schema',
50+
v_function_name := 'name'
51+
));
52+
```
53+
produces
3354

34-
```sh
35-
yarn install
55+
```sql
56+
DROP FUNCTION schema.name;
3657
```
3758

38-
## install the Postgres extensions
59+
#### create function
60+
61+
Here is an example that uses `create_function`:
62+
63+
```sql
64+
SELECT deparser.deparse(ast_helpers.create_function(
65+
v_schema_name := 'schema',
66+
v_function_name := 'name',
67+
v_type := 'TRIGGER',
68+
v_parameters := to_jsonb(ARRAY[
69+
ast_helpers.simple_param(
70+
'param1',
71+
'text'
72+
),
73+
ast_helpers.simple_param(
74+
'active',
75+
'bool'
76+
),
77+
ast_helpers.simple_param(
78+
'sid',
79+
'uuid',
80+
'uuid_generate_v4()'
81+
),
82+
ast_helpers.simple_param(
83+
'description',
84+
'text',
85+
'NULL'
86+
),
87+
ast_helpers.simple_param(
88+
'tags',
89+
'text[]',
90+
ast.a_const(ast.null())
91+
)
92+
]::jsonb[]),
93+
v_body := 'code here',
94+
v_volatility := 'volatile',
95+
v_language := 'plpgsql',
96+
v_security := 0
97+
));
98+
```
3999

40-
Now that the postgres process is running, install the extensions:
100+
produces
101+
102+
```sql
103+
CREATE FUNCTION schema.name (
104+
param1 text,
105+
active bool,
106+
sid uuid DEFAULT uuid_generate_v4(),
107+
description text DEFAULT NULL,
108+
tags text[] DEFAULT NULL
109+
) RETURNS TRIGGER AS $LQLCODEZ$
110+
code here
111+
$LQLCODEZ$ LANGUAGE plpgsql VOLATILE;
112+
```
113+
114+
#### alter policy
115+
116+
```sql
117+
SELECT deparser.deparse(ast_helpers.alter_policy(
118+
v_policy_name := 'mypolicy',
119+
v_schema_name := 'schemanamed',
120+
v_table_name := 'mytable',
121+
v_roles := '{authenticated}'::text[],
122+
v_qual := ast.bool_expr('OR_EXPR', to_jsonb(ARRAY[
123+
ast.a_expr(v_kind := 'AEXPR_OP',
124+
v_lexpr := ast.column_ref(
125+
v_fields := to_jsonb(ARRAY[ ast.string('responder_id') ])
126+
),
127+
v_name := to_jsonb(ARRAY[ast.string('=')]),
128+
v_rexpr := ast.func_call(
129+
v_funcname := to_jsonb(ARRAY[ ast.string('dbe'), ast.string('get_uid') ]),
130+
v_args := to_jsonb(ARRAY[ ast.string('c'), ast.string('b') ])
131+
)
132+
),
133+
ast.a_expr(v_kind := 'AEXPR_OP',
134+
v_lexpr := ast.column_ref(
135+
v_fields := to_jsonb(ARRAY[ ast.string('requester_id') ])
136+
),
137+
v_name := to_jsonb(ARRAY[ast.string('=')]),
138+
v_rexpr := ast.func_call(
139+
v_funcname := to_jsonb(ARRAY[ ast.string('dbe'), ast.string('get_other_uid') ]),
140+
v_args := to_jsonb(ARRAY[ ast.string('c'), ast.string('b') ])
141+
)
142+
)
143+
])),
144+
v_with_check := NULL
145+
));
146+
```
147+
148+
produces
149+
150+
```sql
151+
ALTER POLICY mypolicy
152+
ON schemanamed.mytable TO authenticated USING (
153+
responder_id = dbe.get_uid(c, b)
154+
OR requester_id = dbe.get_other_uid(c, b)
155+
);
156+
```
157+
## installation
158+
159+
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.
160+
161+
To do an automated recursive deploy that automatically installs deps, you can use `sqitch` and `launchql`.
162+
### Recursive Deploy
163+
164+
If you already have `lql` and `sqitch`, simply run this
41165

42166
```sh
43-
make install
167+
createdb launchql
168+
lql deploy --recursive --database launchql --yes --project ast
44169
```
45170

46-
This basically `ssh`s into the postgres instance with the `packages/` folder mounted as a volume, and installs the bundled sql code as pgxn extensions.
171+
If you don't have them installed, continue below.
172+
## developing
173+
#### Install `psql`
174+
175+
Install `psql` without actually running the database. On mac you can use
176+
177+
`brew install libpq`
178+
179+
Or you can install the full-blown postgres locally, but it is recommended that you shut the service down. You'll be using `psql` to connect to the postgres that runs inside of a docker container.
47180

181+
#### Install `sqitch`
182+
183+
https://sqitch.org/
184+
185+
mac users can use brew
186+
187+
```
188+
brew install sqitch --with-postgres-support --without-postgresql
189+
```
190+
191+
or for brew sqitch docs: https://github.com/sqitchers/homebrew-sqitch
192+
193+
#### Install `launchql`
194+
195+
You'll want to install [launchql](https://github.com/launchql/launchql) to run `lql` commands
196+
197+
```sh
198+
npm install -g @launchql/cli
199+
```
48200
## testing
201+
### start the postgres db process
49202

50-
Testing will load all your latest sql changes and create fresh, populated databases for each sqitch module in `packages/`.
203+
Start the postgres docker
51204

52205
```sh
53-
yarn test:watch
206+
docker-compose up -d
54207
```
55208

56-
## building new modules
209+
### install modules
57210

58-
Create a new folder in `packages/`
211+
This command leverages npm to pull some SQL dependencies.
59212

60213
```sh
61-
lql init
214+
yarn install
62215
```
63216

64-
Then, run a generator:
217+
### install testing roles
65218

66219
```sh
67-
lql generate
220+
psql < ./bootstrap-roles.sql
221+
psql < ./bootstrap-test-roles.sql
68222
```
223+
### install the Postgres extensions
69224

70-
You can also add arguments if you already know what you want to do:
225+
Now install the extensions:
71226

72227
```sh
73-
lql generate schema --schema myschema
74-
lql generate table --schema myschema --table mytable
228+
make install
75229
```
76230

77-
## deploy code as extensions
231+
This basically `ssh`s into the postgres instance with the `packages/` folder mounted as a volume, and installs the bundled sql code as pgxn extensions.
78232

79-
`cd` into `packages/<module>`, and run `lql package`. This will make an sql file in `packages/<module>/sql/` used for `CREATE EXTENSION` calls to install your sqitch module as an extension.
233+
### testing
80234

81-
## recursive deploy
235+
Testing will load all your latest sql changes and create fresh, populated databases for each sqitch module in `packages/`.
82236

83-
You can also deploy all modules utilizing versioning as sqtich modules. Remove `--createdb` if you already created your db:
237+
For example
84238

85239
```sh
86-
lql deploy awesome-db --yes --recursive --createdb
240+
cd ./packages/ast
241+
yarn test:watch
87242
```

0 commit comments

Comments
 (0)