Skip to content
Documentation menu

Data Sources

Connections to your Oracle and PostgreSQL databases, per environment, with encrypted credentials and read-only access.

A data source connects Prynt to a database you already use. Datasets read their rows from it with SQL, always read-only. You manage data sources in the Data sources page of a workspace.

What a data source is

A data source is logical: a name, a code such as ERP_MAIN and a database type. The actual host, user and password live in its connections, one for each environment of the workspace. Templates refer to the code, never to a connection string, so the same template reads the development database in the Designer and the production database when your production system renders it.

  • The code uses upper-case letters, digits and underscores, starts with a letter (at most 64 characters) and cannot change after creation: datasets and published versions use it.
  • One data source is the workspace's default: datasets that do not name a data source read it. The first data source is always the default; Make default moves the role to another one.
  • The type cannot change after creation. Deleting a data source deletes its connections and stored credentials.

Supported databases

Oracleoracle
Through ODP.NET (managed), service name, TCP or TCPS. SQL, functions, pipelined functions and procedures with SYS_REFCURSOR. See Oracle.
PostgreSQLpostgresql
Through Npgsql, database name, TLS with sslmode. SQL and set-returning functions. See PostgreSQL.

SQL Server and MySQL appear as coming soon: they cannot be created yet. Read the database guides for users, grants and dialect notes: Oracle, PostgreSQL.

Create a data source

  1. In Data sources, choose New data source: name, code, database type, an optional description and, if you want, Default data source.
  2. On the data source's page, choose Configure on an environment and pick how Prynt reaches the database: Prynt Gateway or Direct connection.
  3. Enter host, port, service name or database, user and password, and the TLS mode.
  4. Save connection: Prynt saves and tests it, and shows the result with any warning.
  5. Repeat for the other environments you use.

One connection per environment

Every workspace has environments (Development, Staging and Production by default), and a data source has at most one connection for each. Which connection is used:

  • In the Designer (SQL editor, database explorer, dataset tests, previews, render tests): the environment chosen at the top of the application, Development by default.
  • Through the API: the environment of the render request, otherwise the default environment of the API key.

There is no fallback: if the chosen environment has no connection, the request fails with DATA_SOURCE_NOT_CONFIGURED. The list of data sources shows the state of each connection: Connected, Connected with warnings, Failed, Not tested, Not configured or Gateway offline.

Gateway or direct

Each connection reaches its database in one of two ways, chosen per environment:

  • Prynt Gateway (recommended for private networks, the default for new connections): a small agent next to the database connects out to Prynt over HTTPS. The database stays private and the credentials are encrypted for the gateway in your browser. See Gateway.
  • Direct connection (cloud databases): Prynt connects over the internet, with TLS required and private addresses refused. See Direct connections.

Connection settings

Hoststringrequired
Direct: the public DNS name. Gateway: the host as the gateway sees it (erp-db.local, 10.0.0.12).
Portinteger
Default 1521 (Oracle) or 5432 (PostgreSQL).
Service namestringrequired
Oracle only: the database service, for example ORCLPDB1. SIDs are not supported.
Databasestringrequired
PostgreSQL only: the database name.
Usernamestringrequired
A read-only user: Prynt warns when it can write.
Passwordsecret
Write-only: after saving, Password stored with Replace. With a gateway, encrypted for the gateway in the browser.
Current schemastring
Where names without a schema resolve (Oracle: CURRENT_SCHEMA; PostgreSQL: search_path).
Schemas in the explorerstring[]
The schemas the database explorer lists (up to 50). Empty = every schema the user can see, except system schemas.
TLSmode
Disabled, Required, Verify CA, Verify certificate and host (recommended). Direct connections must use TLS.
Advancednumbers
Connect timeout (1–120 s, default 15), query timeout of the explorer and session setup (1–600 s, default 30), max pool size (1–100, default 20).

Credentials are never shown again

Passwords are encrypted at rest and never returned to a browser or an API. Changing any setting creates a new revision of the connection, and open connections are replaced.

Test the connection

Save connection saves and tests at once; Test connection tests again (permission sql.execute). The result shows latency, server version and the effective user, for example Connected · 31 ms · Oracle 19c · user PRYNT_READER, or the error. Warnings tell you what to fix:

TLS_DISABLEDwarning
Traffic is not encrypted between the connecting side and the database. Acceptable only on a private network next to a gateway.
TLS_NOT_VERIFIEDwarning
Encrypted, but the server certificate (or its host name) is not verified.
WRITE_PRIVILEGESwarning
The user can insert, change or own tables. Prynt only reads, but use a dedicated read-only user: the test offers the SQL script.
ADMIN_PRIVILEGESwarning
ANY privileges, DBA roles or superuser: far more than Prynt needs.
NOT_READ_ONLY_BY_DEFAULTwarning
PostgreSQL: the user's default_transaction_read_only is off (Prynt still uses read-only transactions).
CURRENT_SCHEMA_INVALIDwarning
The current schema does not exist: names without a schema will not resolve.
PRIVILEGES_UNKNOWNwarning
The user cannot read the privilege catalog, so read-only could not be confirmed.

Database explorer

In the Designer's dataset editor, the database explorer reads the catalog of the dataset's data source, through the connection of the current environment:

  • tables, views, functions and procedures (and Oracle packages) of the schemas in the explorer, with search and a filter by kind;
  • the columns of an object with type, nullability and primary key, and the arguments of a routine;
  • a search for the tables that have a column with a given name;
  • insert a SELECT on an object, or its name, into the SQL editor.

The catalog is cached for 5 minutes; Refresh reads it again from the database.

Data sources in datasets

Each dataset picks its data source in the dataset toolbar (empty = the default). A template may read several data sources; each one is read in its own consistent snapshot, so data is consistent only among datasets of the same data source (the Designer warns about it). The SQL dialect follows the data source: an Oracle query does not run on PostgreSQL.

Errors you may meet

DATA_SOURCE_NOT_CONFIGURED422
No connection for the requested environment, or no default data source.
DATA_SOURCE_UNKNOWNerror
The dataset names a data source code that does not exist in the workspace.
GATEWAY_OFFLINE503
The connection's gateway is not connected.
DATA_SOURCE_UNAVAILABLE503
The database cannot be reached right now (network, listener, login refused).

Permissions

  • datasources.read (designers and above): see data sources and choose them in datasets.
  • datasources.manage (developers, admins, owner): create, edit and delete data sources and connections, add and revoke gateways.
  • sql.execute (developers, admins, owner): test connections, browse the database, run queries.