From: Marko Kreen Date: Mon, 19 Nov 2007 12:32:50 +0000 (+0000) Subject: convert docs to asciidoc, some updates X-Git-Tag: plproxy_2_0_3~11 X-Git-Url: http://git.postgresql.org/gitweb/static/gitweb.js?a=commitdiff_plain;h=af6ad977db38fa971a6910a30165d7223cae154f;p=plproxy.git convert docs to asciidoc, some updates --- diff --git a/doc/Makefile b/doc/Makefile index ebec08f..296b1a0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,14 +3,26 @@ wiki = https://developer.skype.com/SkypeGarage/DbProjects/PlProxy web = mkz@shell.pgfoundry.org:/home/pgfoundry.org/groups/plproxy/htdocs/ +ASCIIDOC = asciidoc + +HTML = config.html syntax.html todo.html tutorial.html + all: +html: $(HTML) + upload: devupload.sh overview.txt $(wiki) - devupload.sh config.txt $(wiki)/ClusterConfig - devupload.sh syntax.txt $(wiki)/LanguageSyntax - devupload.sh todo.txt $(wiki)/ToDo + #devupload.sh config.txt $(wiki)/ClusterConfig + #devupload.sh syntax.txt $(wiki)/LanguageSyntax + #devupload.sh todo.txt $(wiki)/ToDo clean: rm -rf api +web: $(HTML) + rsync -avz $(HTML) $(web)/doc/ + +%.html: %.txt + $(ASCIIDOC) -a toc $< + diff --git a/doc/config.txt b/doc/config.txt index 926c9ba..87799c3 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -1,30 +1,35 @@ -#pragma section-numbers 2 = PL/Proxy Cluster Configuration API = -[[TableOfContents]] +For `CONNECT` functions, no configuration is used. -When running plproxy calls these functions: +For `CLUSTER` functions, following configuration functions are called. +== plproxy.get_cluster_version(cluster_name) == -== plproxy.get_cluster_version(cluster) == + plproxy.get_cluster_version(cluster_name text) + returns integer -{{{ -plproxy.get_cluster_version(cluster_name text) -returns integer -}}} - -It is called on each request, it should return version of particular +It is called on each request, it should return version number of particular cluster config. If version is higher than cached, config and partitions are reloaded. +Example function without use of separate tables: + + CREATE OR REPLACE FUNCTION plproxy.get_cluster_version(cluster_name text) + RETURNS int4 AS $$ + BEGIN + IF cluster_name = 'a_cluster' THEN + RETURN 1; + END IF; + RAISE EXCEPTION 'Unknown cluster'; + END; + $$ LANGUAGE plpgsql; -== plproxy.get_cluster_partitions(cluster) == +== plproxy.get_cluster_partitions(cluster_name) == -{{{ -plproxy.get_cluster_partitions(cluster_name text) -returns setof text -}}} + plproxy.get_cluster_partitions(cluster_name text) + returns setof text This is called when new partitions need to be loaded. Should returns connstrings to partitions, in right order. Total count must @@ -35,14 +40,27 @@ user=CURRENT_USER appended to connection string to forward current user name. As plproxy does not know any passwords, partition database should be using "trust" authentication method then. +Example function without use of separate tables: + + CREATE OR REPLACE FUNCTION plproxy.get_cluster_partitions(cluster_name text) + RETURNS SETOF text AS $$ + BEGIN + IF cluster_name = 'a_cluster' THEN + RETURN NEXT 'dbname=part00 host=127.0.0.1'; + RETURN NEXT 'dbname=part01 host=127.0.0.1'; + RETURN NEXT 'dbname=part02 host=127.0.0.1'; + RETURN NEXT 'dbname=part03 host=127.0.0.1'; + RETURN; + END IF; + RAISE EXCEPTION 'Unknown cluster'; + END; + $$ LANGUAGE plpgsql; == plproxy.get_cluster_config(cluster) == -{{{ -plproxy.get_cluster_config(cluster_name text, - out key text, out val text) -returns setof record -}}} + plproxy.get_cluster_config(in cluster_name text, + out key text, out val text) + returns setof record Should return pairs of key-value pairs. All of them are optional. Timeouts/lifetime are given in seconds. If 0 or NULL then disabled. @@ -51,11 +69,6 @@ Timeouts/lifetime are given in seconds. If 0 or NULL then disabled. PL/Proxy will drop older connections. - connect_timeout:: - - Initial connect is canceled, if it takes more that this. - Duplicated connstring setting (should be just added to connstr?) - query_timeout:: If query result does not appear in this time, the connection @@ -66,3 +79,28 @@ Timeouts/lifetime are given in seconds. If 0 or NULL then disabled. disable_binary:: Do not use binary I/O for connections to this cluster. + + connect_timeout:: + + Initial connect is canceled, if it takes more that this. + Deprecated - it duplicates libpq connect string parameter + with same name. Its better to just add the parameter to + connect string. + +Example function without use of separate tables: + + CREATE OR REPLACE FUNCTION plproxy.get_cluster_config( + in cluster_name text, + out key text, + out val text) + RETURNS SETOF record AS $$ + BEGIN + -- lets use same config for all clusters + key := 'connection_lifetime'; + val := 30*60; -- 30m + RETURN NEXT; + RETURN; + END; + $$ LANGUAGE plpgsql; + + diff --git a/doc/syntax.txt b/doc/syntax.txt index 48f6b7b..9aa1574 100644 --- a/doc/syntax.txt +++ b/doc/syntax.txt @@ -1,66 +1,64 @@ -#pragma section-numbers 2 -== Language Syntax == += PL/Proxy Language Syntax = -The language contains only 4 statements: CONNECT, CLUSTER, RUN and SELECT. +The language is similar to plpgsql - string quoting, comments, +semicolon at the statements end. -Each function needs to have either CONNECT or CLUSTER+RUN statement -to specify where to run the function. The SELECT statement is optional, -if it is missing, there will be default query generated based on proxy -function signature. +It contains only 4 statements: `CONNECT`, `CLUSTER`, `RUN` and `SELECT`. -=== CONNECT === -{{{ -CONNECT 'libpq connstr'; -}}} +Each function needs to have either `CONNECT` or pair of `CLUSTER` + `RUN` statements +to specify where to run the function. + +The `SELECT` statement is optional, if it is missing, there will be default +query generated based on proxy function signature. + +== CONNECT == + + CONNECT 'libpq connstr'; Specifies exact location where to connect and execute the query. If several functions have same connstr, they will use same connection. -=== CLUSTER === -{{{ -CLUSTER 'cluster_name'; -}}} +== CLUSTER == + + CLUSTER 'cluster_name'; Specifies exact cluster name to be run on. The cluster name will be passed to plproxy.get_cluster_* functions. -{{{ -CLUSTER cluster_func(..); -}}} + CLUSTER cluster_func(..); + Cluster name can be dynamically decided upon proxy function arguments. -`cluster_func` should returns text value for final cluster name. +`cluster_func` should return text value of final cluster name. + +== RUN ON == + + RUN ON ALL; -=== RUN ON === -{{{ -RUN ON ALL; -}}} Query will be run on all partitions in cluster in parallel. -{{{ -RUN ON ANY; -}}} + RUN ON ANY; + Query will be run on random partition. -{{{ -RUN ON ; -}}} + RUN ON ; + Run on partition number ``. -{{{ -RUN ON partition_func(..); -}}} + RUN ON partition_func(..); + Run partition_func() which should return one or more hash values. (int4) Query will be run on tagged partitions. If more than one partition was tagged, query will be sent in parallel to them. +== SELECT == -=== SELECT === -{{{ -SELECT .... ; -}}} + SELECT .... ; -=== Argument substitution === + +== Argument substitution == Proxy function arguments can be referenced using name or `$n` syntax. Everything that is not argument reference is just passed on. + + diff --git a/doc/todo.txt b/doc/todo.txt index a281dc4..5278fac 100644 --- a/doc/todo.txt +++ b/doc/todo.txt @@ -12,8 +12,15 @@ * support both older (2.5.4) and newer (2.5.33) flex * quoting for function name and result columns * fetch columns explicitly + * drop statement_timeout -== Needs to be checked == +=== todo === + + * updated docs + - move docs to asciidoc + - include Steve's intro + +== Near future == * Clean up the binary-or-not decision. There should be possible to have partitions with different versions. That may mean @@ -22,10 +29,11 @@ == Just thoughts == * A way to give config to CONNECT functions. - * SET param = xxx; + - SET param = xxx; ??? * Dynamic connstr loading for CONNECT functions? * RUN ON ALL: sort by? * RUN ON ALL: ignore errors? * RUN ON ANY: if one con failed, try another * Streaming for big resultsets, to avoid loading them fully in memory. - Needs also backend changes. + This needs also backend changes. +