Application lifecycle
Import Application from polynom.application. It opens the database connection, maintains the schema snapshot, and creates missing relational namespaces and tables on entry to its with block. Register schemas before opening the application. Create sessions inside the active application. Each session opens a separate connection.
Create a new application object for each context. Leaving the context closes its connection and cursor and releases the configuration lock. A startup error also releases resources that PolyNOM has acquired, including the configuration lock.
| Constructor argument | Meaning |
|---|---|
app_uuid |
A string UUID that identifies the application and its stored schema snapshot. Reuse it across runs and keep it distinct from other applications on the same server. |
address |
A (host, port) tuple for plain TCP. Supply a socket path for the Unix transport. |
user, password |
Server credentials. The built-in defaults are pa and an empty password. |
transport |
plain by default. Use unix for a server with a Prism Unix socket. |
use_docker |
Start Polypheny through Docker when entering the application. Defaults to False. |
migrate |
Apply supported changes to existing schema objects. Defaults to False. |
stop_container |
Stop the configured container at context exit when Docker is enabled. Defaults to False. |
remove_container |
Remove the configured container at context exit when Docker is enabled. Set stop_container=True too when you want PolyNOM to stop and remove a running container. Defaults to False. |
log_statements |
Enable the per-application statement log. Defaults to False. |
Pass credentials and transport explicitly when overriding the defaults. The POLYPHENY_HOST, POLYPHENY_PORT, POLYPHENY_USER, and POLYPHENY_PASSWORD environment variables are read by the examples. They are passed to the application’s constructor. Connection example
Docker
Run a reachable Docker daemon before using use_docker=True. PolyNOM looks up a container by POLYPHENY_CONTAINER_NAME. If it finds one, it starts the container and waits for Prism at the supplied application address. Configure that address for the container’s published Prism port.
If no container exists, set POLYPHENY_IMAGE_NAME to an image you can pull that serves a Prism 2.2 API. The default image setting is None. The POLYPHENY_PORTS mapping controls which ports Docker publishes for a newly created container. The Docker flags operate on the named container, including one you created earlier. Choose a separate container name for development if you use automatic stopping or removal.
Configuration
Import the polynom.config module and pass its key constants to its functions. Configuration is shared by applications in the Python process. Set the values before entering an application context.
| Function | Behavior |
|---|---|
get(key) |
Read a configured, internal, or derived value. An unknown key raises KeyError. |
set(key, value) |
Update a user-configurable key. A locked configuration raises RuntimeError. A key outside the user-configurable set raises KeyError. |
set_config(overrides) |
Apply a dictionary of updates in order. Earlier updates may already be applied if a later key raises an error. |
all_config() |
Return a shallow dictionary of configuration values. It includes credentials, so avoid logging it. |
lock(), unlock() |
Increment and decrement the configuration lock count. Application manages these calls for its own context. An unmatched unlock() raises RuntimeError. |
| User-configurable key | Default and purpose |
|---|---|
DEFAULT_NAMESPACE |
polynom_entities, inherited by schemas without an explicit namespace. |
DEFAULT_DATA_MODEL |
RELATIONAL, the supported mapping model. |
POLYPHENY_CONTAINER_NAME |
polypheny, the container name used for Docker lookup and lifecycle operations. |
POLYPHENY_IMAGE_NAME |
None. Set a compatible image when you want PolyNOM to create a container. |
POLYPHENY_PORTS |
Maps container TCP ports 20590, 7659, 80, 8081, and 8082 to the same host ports by default. Keys take the form "20590/tcp". |
DEFAULT_TRANSPORT |
plain, the built-in connection default. |
DEFAULT_USER |
pa, the built-in user default. |
DEFAULT_PASS |
An empty string, the built-in password default. |
STATEMENT_LOG_FILE_NAME |
statements.log, used to derive the per-application log file name. |
Python evaluates the credential and transport defaults when it imports Application. The base schema’s default namespace and data model are also set at import. Set namespace_name explicitly on schemas when choosing a different namespace after import, and pass connection settings as constructor arguments.
INTERNAL_NAMESPACE (polynom_internal), CHANGE_LOG_TABLE (change_log), SNAPSHOT_TABLE (snapshot), SYSTEM_USER_NAME (SYSTEM), DUMP_FORMAT_VERSION (1), and DROP_PROTECTED_NAMESPACES (which contains public) are internal constants. CHANGE_LOG_IDENTIFIER is derived from the internal namespace and table name.
Schema creation and migration
On startup, PolyNOM compares the registered schema definitions with the stored snapshot for this application UUID. It creates missing namespaces and tables even with migrate=False. Changes to existing columns require migrate=True. The application records the current snapshot on startup even when migration is disabled. Enable migration when rolling out the schema change you want it to apply.
The migrator generates SQL for recognized column additions, removals, renames using a field’s previous_name, and changes to type, nullability, and default. The snapshot stores the type adapter’s class name, so parameter-only changes such as changing a VarChar length can go undetected. Table drops, table renames, namespace moves, and constraint changes require explicit DDL. A table’s previous_name is accepted by BaseSchema, but the snapshot comparison in 0.4.0 does not use it to rename a table.
Test migrations against a copy of your data before rolling them out. Removing a field from a registered schema can drop the corresponding column and its data. The migrator compares application snapshots, so changes made directly in the database can diverge from those snapshots. Schemas and models
