Administer a PostgreSQL connection

Bounded pilot, 24 September 2026. This route reads PostgreSQL well headers. It does not provide SQL curve support, arbitrary SQL execution or database writes. File, SQLite and OSDU setup retain their deployment-managed setup.

Before setup

Your deployment operator must approve the database host, port, database, schema, table and transport settings. The server makes the private encryption key at its first start (see Install). The gateway host needs network access to that target. Entering a private address in a browser would not make it reachable; this pilot supplies no private-network tunnel.

Ask for a PostgreSQL principal with SELECT access to the approved table and its username/password. Sign into Workspace as a project administrator.

Configure it yourself

1. Open Connections → Administration → Add PostgreSQL connection.
2. Select the approved target. Its database and schema/table are shown.
3. Enter a display name, database username and password. Save credentials.
4. Choose Test access. Success reports the number of rows, not scientific approval.
5. Open Connections → Data sources, expand the connection and select the table.
6. Map well ID, name, X/Y and any depth/operator fields. Declare known CRS, depth unit/type/reference and missing-value interpretation. Unknown context stays unknown; mapping does not convert coordinates or units. Preview, review and add the source.

Saving a connection alone adds no project data. Tables are bounded to 1,000 rows; use an operator-approved filtered view for a larger database. Source selections remain account-owned; this administration feature does not share an administrator’s SQL selection with every member. The retained LAS workflow is the separate qualified path for ordinary scientists.

Maintain access

• Replace credential: after the database password changes, enter the new username and password here, save, and test. This changes Ophiolite’s stored credential; it does not change the password inside PostgreSQL.
• Disable: blocks subsequent reads through Ophiolite. It does not invalidate the upstream password, stop an already authorized request or recall retained/downloaded data.
• Enable: test access again. Offline selections recover through source reconciliation; use Resume if a prior authentication failure left a selection access-denied.
• Unreachable or rejected: verify credentials and reachability from the gateway. Detailed upstream errors are withheld to keep private connection information out of logs/UI.
• Key unavailable: ask the deployment operator to import the key exported from this deployment. Existing file connections can remain usable while managed credentials fail closed.

Passwords are encrypted at rest and never returned to ordinary users. Backups must contain both the journal and its dedicated connection key. Changing target host, database or table requires a new approved target/authority; password rotation does not. One registration per approved target is supported in this pilot. Test attempts are limited to ten per minute per administrator. No production availability guarantee is implied.

Declare a copy and identifiers

Importing wells from a table keeps a copy of the accepted rows and names each well by its identifier. The approved database says whether both are allowed, in the targets document:

{"targets": {"groningen": {"host": "wells.example.internal", "port": 5432, "dbname": "wells", "schema": "public",
  "table": "groningen_wells", "sslmode": "verify-full", "sslrootcert": "/state/ca/corp.pem",
  "copy": {"permitted": true, "audience": ["alice", "bob"]},
  "identifiers": {"authority": "nlog"}, "crs": "EPSG:28992"}}}

copy.audience lists the people a copy may be shared with; the person importing must be one of them. identifiers names the authority that issues the table’s well identifiers (a short lowercase name). Removing copy later makes the kept copies unreadable while the wells stay; a sign-in that is replaced, rotated or disabled does not.

crs (optional) declares the coordinate system the table’s X and Y columns are in: EPSG:4326, Amersfoort / RD New (EPSG:28992), WGS 84 / UTM zone 31N (EPSG:32631) or ED50 / UTM zone 31N (EPSG:23031). When mapping the table, that system is chosen for the person and shown as “Declared in the approved database settings”; they can still choose another, and the screen says when their earlier mapping disagrees with the declaration. Changing crs does not change a saved mapping, an import or a copy.

Share a connection with your organisation

When several projects of one organisation read the same database, make the connection once, at the organisation:

1. An organisation owner opens the organisation’s Connections page and adds a connection to an approved database, with their own database sign-in.
2. For each person, the owner says whether they may use the connection and whether they may administer it. Administering means changing who has access and turning the connection on or off; it does not let you read through it.
3. Everyone who uses the connection adds their own sign-in for it. The database sees each person as themselves, so its own permissions decide what each person may read. Nobody’s sign-in is shown to, or used for, anyone else.
4. In any project of the organisation, Add source → From your organisation’s connections lists the connections you use. Each project keeps its own selections and its own mapping of the table.

Taking away someone’s use stops their sources from reading the database at once; those sources say so and come back when use is given again. Copies already kept, and wells already imported, stay with their project under the project’s own rules. Someone who leaves the organisation can no longer use its connections.

A connection a project already has can be made available to its organisation in place: its sources, mappings, kept copies and an import that was interrupted all keep working. Before anything changes you see who will need to add their own sign-in, and you confirm it.

Add a database in the browser

On a deployment in organisation mode, an organisation owner, or someone an owner lets add databases, adds a database by its address on the organisation’s Connections page, with their own sign-in. Nobody edits a file and the server does not restart. Everyone else who administers a project of the organisation chooses Ask for a database instead: they name the database, send no sign-in, and an owner or someone who may add databases approves or declines it.

• Approving adds the database to the organisation, or uses the organisation’s connection to it when there already is one. Whether the person who asked may use it is a separate choice: only someone who administers the connection can give use, and everyone who uses it adds their own sign-in.
• Declining needs a reason; the person who asked sees it. They can withdraw a request that is still waiting. An organisation has at most 20 requests waiting at once.
• Who may add databases is a table on the same page that only owners change. Owners always may.
• What the organisation offers: the person who administers a connection can offer only some schemas or tables. Projects then see only those in Add a source; a selection of a table no longer offered stops reading and says so (outside-restriction). Copies already kept stay readable. The database’s own permissions still decide what each person reads with their own sign-in.

Where a database may be: the destination rule

The deployment administrator decides which addresses may be added in the browser, with one rule (ophiolite-ops configure destination-rule, see Install):

Field	Meaning
mode	organisation: approval in the browser, inside the rule. operator: only the operator’s file approves databases (what an absent rule means, so a deployment upgraded from an earlier release keeps it).
profile	self-hosted: private address ranges are allowed. public: only global addresses, unless listed under allow.
allow, deny	Address ranges and host names. A host name matches the name typed; a range matches every address the name answers.

Every address a name answers is decided in this order: the built-in refusals first (link-local and cloud metadata addresses, unspecified, multicast and reserved ranges, and the deployment’s own databases by address and port), then deny, then allow, then the profile. Loopback is neither private nor global, so it is refused unless allowed. The check is made again at every connection, against the address actually used, so a name that later answers a refused address is refused then (destination-refused).

Databases the operator approved in the file (configure connection-admin) never pass through the rule: they keep working in both modes, as before. To review them, read the targets of the document with your usual operator access; remove one with configure connection-admin and a document without it.

Turning browser approval off

Configure {"mode": "operator"}. Nothing is deleted: databases added in the browser stay listed, with their selections and kept copies, and say Browser approval is turned off on this deployment (browser-approval-off). To keep one working in operator mode, adopt it: its id is under Technical details on the organisation’s Connections page.

./ophiolite-ops connection-admin adopt managed-1b2c3d   # its identity, tables and selections stay as they are

A database whose certificate comes from your organisation’s own certificate authority needs that authority kept first (./ophiolite-ops connection-ca corp corp-ca.pem); people then give the kept file’s name, corp.pem, as the certificate issuer when they add it.

What a state means and who fixes it

Every blocked or failed state on Add a source is one of the states below. The screen shows its sentence, who can fix it and what they do, and links here; the state’s name is under Technical details.

ready

Ready. Who fixes it: you. Nothing to do: add a connection, or test the one you have.

not-configured

Connection administration is not set up on this deployment. Who fixes it: your deployment administrator. The server could not read its own records to decide whether a key may be made. Check that the database is running, then restart the server; it sets connection administration up at start.

key-unavailable

The deployment’s connection key is not available, so saved sign-ins cannot be used. Who fixes it: your deployment administrator. Import the key exported from this deployment: ./ophiolite-ops connection-key import connection.key. A key file with the wrong permissions (it must be owner-only) or unreadable bytes is reported the same way, with the reason under Technical details.

no-approved-database

No database has been approved for this deployment yet. Who fixes it: your deployment administrator. Approve one: ./ophiolite-ops configure connection-admin targets.json, then restart the server.

key-mismatch

Some saved sign-ins were saved under a different connection key. Who fixes it: your deployment administrator. Import the original key, or have each affected sign-in replaced by a project administrator.

credential-unreadable

The saved sign-in can no longer be read. Who fixes it: a project administrator. Replace the sign-in (Replace credential).

credential-context-mismatch

The saved sign-in belongs to a different connection. Who fixes it: a project administrator. Replace the sign-in (Replace credential).

connection-disabled

This connection is turned off. Who fixes it: a project administrator. Turn the connection on again (Enable).

target-changed

The approved database of this connection was changed or removed. Who fixes it: your deployment administrator. Restore the approved database as it was in the targets document, or approve a new one and add a new connection.

unreachable

The database server could not be reached. Who fixes it: your deployment administrator. Check that the database is running and reachable from the server (host, port, firewall).

tls-refused

The secure connection to the database was refused. Who fixes it: your deployment administrator. Check the database’s certificate and the certificate authority named in the target (./ophiolite-ops connection-ca).

sign-in-refused

The database refused the user name or password. Who fixes it: a project administrator. Replace the sign-in with a user name and password the database accepts.

no-read-right

The sign-in may not read the approved table. Who fixes it: your organisation’s owner. Ask the database’s owner to grant this user SELECT on the approved table.

table-missing

The approved table does not exist in the database. Who fixes it: your deployment administrator. Check the schema and table in the targets document against the database.

undetermined

The cause could not be determined. Who fixes it: your deployment administrator. Note the time of the test and the request id under Technical details, and report them.

changed-elsewhere

The connection was changed elsewhere. Who fixes it: you. Reload, then repeat the change.

invalid-input

Some fields are missing or not accepted. Who fixes it: you. Correct the fields and send again.

target-not-approved

That database is not approved for this deployment. Who fixes it: you. Choose one of the approved databases.

limit-reached

The connection limit is reached. Who fixes it: your deployment administrator. Remove a connection that is no longer needed (16 per project, 32 per deployment).

target-in-use

That database already has a connection. Who fixes it: you. Maintain the existing connection to it.

source-collision

Another source already reads that database. Who fixes it: your deployment administrator. Remove the other source, or approve a different database.

not-found

That connection was not found. Who fixes it: you. Reload the list of connections.

test-limit

Too many access tests in the last minute. Who fixes it: you. Wait a minute, then test again (ten tests per minute per administrator).

copy-not-declared

The approved database does not permit keeping a copy of its rows. Who fixes it: your deployment administrator. Declare copy on the approved database with ophiolite-ops configure connection-admin (see Declare a copy and identifiers). Until then importing wells stops before anything is kept.

identifiers-not-declared

The approved database does not say which authority names its wells; wells are named after the connection. Who fixes it: your deployment administrator. Declare identifiers on the approved database with ophiolite-ops configure connection-admin. An import still runs; the review warns you first.

sign-in-needed

You have not added your own sign-in to this connection yet. Who fixes it: you. Add your own database sign-in to the connection on the organisation’s Connections page.

no-use

You may not use this organisation connection. Who fixes it: the connection’s administrator. Ask the connection’s administrator or an organisation owner to give you use.

use-organisation-connection

Your organisation already has a connection to that database, and you may use it. Who fixes it: you. Add the source from your organisation’s connections instead of making a new connection.

ask-for-use

An organisation connection already reads this database. Who fixes it: an organisation owner. An organisation owner or its administrator can give you use.

ask-to-promote

Another project of your organisation already has a connection to that database. Who fixes it: an organisation owner. Ask an organisation owner to make that connection available to the organisation.

sign-in-owner-unknown

It cannot be told whose sign-in this connection holds. Who fixes it: your project administrator. Replace the sign-in, then make the connection available to the organisation again.

destination-refused

The database’s address is not allowed on this deployment. Who fixes it: your deployment administrator. Ask the deployment administrator which database addresses are allowed; the destination rule decides, at every connection.

browser-approval-off

Browser approval is turned off on this deployment. Who fixes it: your deployment administrator. The deployment administrator must approve continued use of this connection: adopt it with ophiolite-ops connection-admin adopt, or turn organisation mode back on.

request-needed

Adding this database needs an organisation owner’s approval. Who fixes it: an organisation owner. Ask an organisation owner to add the database, or to let you add databases; Ask for a database sends them the request.

outside-restriction

This table is no longer offered by the organisation. Who fixes it: the connection’s administrator. Ask the connection’s administrator to offer the table again. Copies already kept stay readable.

command-reused

That command was already used for another request. Who fixes it: you. Send the request again as a new command; the screen does this when you open the form again.

no-list-right

This key cannot list files. Who fixes it: a project administrator. Ask the storage’s owner for a key that may list the folder. The states from here on are a storage bucket’s.

bucket-missing

This storage has no bucket with that name. Who fixes it: you. Check the bucket name.

wrong-region

This storage expects a different region. Who fixes it: you. Give the region the storage names for this bucket. Some stores accept any region, and never answer this.

object-missing

This file is no longer in your storage. Who fixes it: you. Choose the file again; this does not confirm it was deleted.

object-changed

This file changed in your storage since you reviewed it. Who fixes it: you. Review it again: a file read in place is pinned at the bytes read when it was added.

throttled

This storage is busy. Who fixes it: you. Try again shortly.

unreadable

This storage answered in a way Ophiolite could not read. Who fixes it: your deployment administrator. Report the time of the test to the deployment administrator.

no-consistent-read

This storage cannot read large files safely. Who fixes it: your deployment administrator. Use storage that honours If-Match, or keep files under the stated size.