__neki.* routing setting on a role with ALTER ROLE ... SET, and
every connection of that role starts with it. The application then needs no
SET __neki.setting = value statements or connection options.
Settings you can store
See Shard targeting and fanout for what each
setting does.
Who can store a setting
Postgres stores a__neki.* setting only for a role that has the SET
privilege on that setting. The default postgres role has SET on each
setting in the table, and it can grant SET to other roles.
To change the settings of a different role, Postgres also requires the ADMIN
option on that role. The postgres role has the ADMIN option on the roles
that it creates with CREATE ROLE, but not on
managed roles, which PlanetScale creates.
Roles created with CREATE ROLE
For example, consider a rolereporting that only needs read access and wants
the lowest-latency reads, from replicas in the router’s own cell. Connected as
postgres, store the settings on the role:
reporting start with these settings:
ALTER ROLE reporting RESET "__neki.target"; as
postgres.
Managed roles
Roles created in the dashboard, with the API, or with the PlanetScale CLI are managed roles. Thepostgres role cannot run ALTER ROLE on them:
SET on each setting, and then store the
settings while connected as that role:
1
Connect as the managed role and get its Postgres role name:
2
Connect as
postgres and grant SET on each setting that the role will
store:3
Connect as the managed role again and store the settings:
permission denied to set parameter "__neki.target".
A managed role with a stored replica or rdonly target starts each
connection on a replica, where Neki rejects ALTER ROLE with
cannot execute ALTER ROLE: session target is not primary. To change or remove
the setting later, switch the session to the primary first:
Database defaults
Thepostgres role can also store a setting for every connection to a logical
database that it owns:
Precedence
When a setting is set in more than one place, the later one in this list wins:- Neki’s default
- A database setting:
ALTER DATABASE ... SET - A role setting:
ALTER ROLE ... SET - A role setting for one database:
ALTER ROLE ... IN DATABASE ... SET - The connection options, such as
PGOPTIONS='-c __neki.target=primary' SETin the session
When stored settings apply
Neki reads stored settings when a connection starts. Open connections, including those in a connection pool, keep their settings until they reconnect. Right after you change a setting, a connection that starts on a different router can get the earlier value for a short time. Neki checks a stored value only when a connection starts. Test the value withSET in a session before you store it. SET rejects an invalid value
immediately, and for __neki.shard it also checks that the shard exists.

