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 $<
+
-#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
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.
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
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;
+
+
-#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 <NR>;
-}}}
+ RUN ON <NR>;
+
Run on partition number `<NR>`.
-{{{
-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.
+
+
* 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
== 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.
+
projects / plproxy.git / commitdiff