diff options
| -rw-r--r-- | doc/Makefile | 3 | ||||
| -rw-r--r-- | doc/londiste.cmdline.txt | 72 | ||||
| -rw-r--r-- | doc/upgrade.txt | 52 |
3 files changed, 126 insertions, 1 deletions
diff --git a/doc/Makefile b/doc/Makefile index cc5dc36f..3854e6d3 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,7 +11,8 @@ EPYARGS = --no-private --url="http://pgfoundry.org/projects/skytools/" \ HTMLS = londiste.cmdline.html londiste.config.html README.html INSTALL.html \ londiste.ref.html TODO.html pgq-sql.html pgq-admin.html pgq-nodupes.html \ - walmgr.html set.notes.html + walmgr.html set.notes.html \ + upgrade.html all: man diff --git a/doc/londiste.cmdline.txt b/doc/londiste.cmdline.txt index 4cd77c72..595e9b1b 100644 --- a/doc/londiste.cmdline.txt +++ b/doc/londiste.cmdline.txt @@ -279,6 +279,78 @@ you system paths. See `londiste(5)`. +== UPGRADING == + +As the skytools software contains code which is run directly from +inside the database server (+PostgreSQL+ functions), installing the +new package version at the OS level is not enough to perform the +upgrade. + +It still is possible to upgrade londiste without stopping the service, +how to do this somewhat depends on the specifics version you're +upgrading from and to, please refer to the +upgrade.txt+ +documentation, which can be found at this url too: +http://skytools.projects.postgresql.org/doc/upgrade.html[upgrade.html] + +== CURRENT LIMITATIONS == + ++londiste+, as a trigger based solution, is not able to replicate +neither +http://www.postgresql.org/docs/current/interactive/ddl.html[DDL] nor +http://www.postgresql.org/docs/current/static/sql-truncate.html[TRUNCATE] ++SQL+ commands. + +Please also note that the cascaded replication scenario is still a ++TODO+ item, which means +londiste+ is not yet able to properly handle +the case on its own. + +=== DDL === + +If you edit a table definition on the provider, you have to manually +update the table definition on every subscriber replicating the table +data. When adding, renaming or removing columns, replication won't +work for the table until subscriber is updated too, but +londiste+ +won't loose any item to replicate, and reapply them once schemas match. + +=== TRUNCATE === + +For truncating a table +foo+ which is replicated by +londiste+, the +easier way is to remove +foo+ from subscriber(s), +TRUNCATE+ it on the +provider and add it again on subscriber(s): + + subscriber> londiste.py conf.ini subscriber remove foo + provider> psql provider_db -c "truncate foo;" + subscriber> londiste.py conf.ini subscriber add foo + +Of course, you need to perform the subscriber steps on each of your +subscribers if you have more than one currently replicating the +foo+ +table. + +=== Cascaded replication === + ++londiste+ is not yet able to handle cascaded replication. What it +means is that if you setup the three servers A, B and C such as some +tables from A are replicated to B and the same table are replicated +from B to C, and if the replication from A to B is stopped, +londiste+ +won't be able to have the replication to C ongoing by reconfiguring it +from A to C for you. + +== SWITHOVER == + +While using +londiste+ to replicate data from a provider to a +subscriber, it is possible to have the subscriber become the provider. +This can be used, for example, to upgrade from one +PostgreSQL+ +version to another (more recent) one, or from a physical setup to +another, for example. + +The recommanded procedure to achieve a switchover is the following: + + 1. stop all write access to db. + 2. let the londiste apply last changes + 3. set up new queue on slave as provider, add tables + 4. subscribe old master to new master, add tables with --expect-sync + 5. do some DDL things on new master (triggers, etc) + 6. allow write access to new master == SEE ALSO == diff --git a/doc/upgrade.txt b/doc/upgrade.txt new file mode 100644 index 00000000..0c9abe94 --- /dev/null +++ b/doc/upgrade.txt @@ -0,0 +1,52 @@ + += Live londiste upgrade = + +It is possible to upgrade +londiste+ software without having to stop the service, +how to do so depends on specifics versions you're upgrading from and to. + +This document list steps to follow once the new version of +skytools+ package is +installed on the provider and subscriber hosts where to operate a live upgrade. + +As the +skytools+ software contains code which is run directly from inside the +database server (+PostgreSQL+ functions), installing the new package version at +the OS level is not enough to perform the upgrade. + +The following sections list the manual steps to perform in order to upgrade a +running londiste and PgQ solution at the database side. + + +== upgrading from 2.1.5 to 2.1.6 == + +First, +PgQ+ software has to be upgraded. It often is installed on the provider +side of your replication setup, and runs on the provider host. + +Then +londiste+ database functions have to be updated too, which are normally run +from the subscriber host. You need to repeat the londiste steps for each and +every running subscriber. + + +=== PgQ upgrade === + + * PgQ (used on Londiste provider side), table structure, plpgsql functions: + + $ psql dbname -f upgrade/final/v2.1.5.pgq_core.sql + + * PgQ new insert_event(), written in C: + + $ psql dbname -f sql/pgq/lowlevel/pgq_lowlevel.sql + + * PgQ new triggers (sqltriga, logtriga, logutriga), written in C: + + $ psql dbname -f sql/pgq/triggers/pgq_triggers.sql + +=== Londiste upgrade === + + * Londiste (both provider and subscriber side) + + $ psql dbname -f upgrade/final/v2.1.5.londiste.sql + + * pgq_ext: + + $ psql dbname -f upgrade/final/v2.1.5.pgq_ext.sql + + |