Tech:Instances
From Cyclopath
Contents |
[edit] Overview
To better support expansion, parts of the Cyclopath infrastructure have been changed to allow for multiple Cyclopath instances. A Cyclopath instance in this case is a regional map corresponding to a location where Cyclopath is available. These instances run on different URLs but share the same code, installation files, configuration files, and database.
[edit] Instance List
| Instance Name | Server Name (production) | Server Name (development) | Notes |
|---|---|---|---|
minnesota
| http://magic.cyclopath.org | http://localhost | 7-county Twin Cities Metro Area |
While the instance name serves as a unique identifier for the instance, the server name is also unique and both must be set correctly in multiple locations as described below.
[edit] Pyserver
Each instance now has a separate section in CONFIG, for example [instance_minnesota] contains all of the configuration for the minnesota instance. Within each instance configuration section, server_name should be set.
[instance_minnesota] server_name: localhost
[edit] Flashclient
Instance-specific configuration is now stored in Conf_Instance.as. To make development easier, this is checked in as Conf_Instance.as.template (similar to CONFIG.template in pyserver). Copy this file to Conf_Instance.as and change the hostname identifying the config section you want to test to match that of your local machine.
public static var config:Object = {
'http://localhost': {
instance_name: 'minnesota',
[edit] Apache
One virtual host will need to be set up for each instance. ServerName should match the host name above and PythonInterpreter should be set to match the instance name.
ServerName localhost <Location /wfs> PythonInterpreter minnesota </Location>
[edit] Shell Scripts
While scripts launched by mod_python should be able to determine which instance to use by looking at the PythonInterpreter setting, other Python and shell scripts (except for those which are instance-agnostic) need to have the INSTANCE environment variable set before running them.
INSTANCE=minnesota ./routedctl start
[edit] Database Schemas
The tables in the Cyclopath database are now split into different schemas depending on their use. Before everything was in the "public" schema; now there is a separate schema for each instance in addition to the public schema. The public schema is now a "shared" schema and contains objects that are common to all instances of Cyclopath. This includes the user tables, type_code tables, and various other enum-like tables. All tables containing data specific to an instance of Cyclopath (geofeatures, annotations, etc.) have been moved to separate schemas, one for each instance.
Views are strongly linked to the tables they depend on, so views on instance-specific tables have also been moved to instance-specific schemas. Functions, on the other hand, do not appear to be strongly linked to the tables they access and can safely be kept in the public schema (with the exception of a couple functions that contain hard-coded schema-specific values).
[edit] Using psql
When connecting to the database manually using psql, only tables in the "public" schema will show up by default. To see a more complete list:
SET search_path TO minnesota, public;
This is what db_glue.py does when it starts up.
[edit] Creating new objects
All new tables need to be created in the appropriate schema. In general, enums and type tables should be created in the public schema, while tables containing instance-specific data should be created once in each instance schema. This process can be partially automated by creating two scripts: one for the public tables and one for instance-specific tables. schema-upgrade.py can distinguish between the two by checking for the @once-per-instance keyword within the script.
Example:
006-1-point-type.sql /* create the point type table */ CREATE TABLE point_type ( code INT PRIMARY KEY ...
Since the default search path includes the public schema, the table will be created in public. However, it might be more clear to explicitly specify the schema name:
CREATE TABLE public.point_type (
The instance-specific table should be created slightly differently:
006-2-point.sql /* Create the point table; this script needs to be run @once-per-instance */ SET search_path TO @@@instance@@@, public; CREATE TABLE point ( type_code INT NOT NULL REFERENCES point_type (code) ...
Specifying @once-per-instance tells schema-upgrade.py to run the script once for each instance schema. The @@@instance@@@ keyword is automatically substituted with an actual schema name when it is run by schema-upgrade.py.
While it's not required, it will probably be helpful to number related scripts with the same three-digit number. In this case, there may need to be additional numbers in the script names to ensure they are run in a specific order (as in this example).
[edit] Arbitrary SQL scripts
Use psql_wrap.sh, which accepts a SQL script name and the database name as arguments.
INSTANCE=minnesota ./psql_wrap.sh auditor.sql cycling
