Skip to content
This page View Markdown Open in ChatGPT Open in Claude

Is valid connection string

Opens a connection with the string given and closes it : the check the Test Instance button of the instances page makes. Useful for an onboarding screen which lets a customer register their own database, or before writing a tenant row.
Method POST
URL /api/system-api/admin/is-valid-connection-string : admin is the user path of your account
Body { connectionString, instanceType, oracleDBUsername?, oracleDBPassword?, oracleDBPrivilege? } or an array of them
Answer data : { success, data: true | false, error? }, or an array of them
From code g.sys.system.isValidConnectionString

The call

Body
{ "connectionString": "postgresql://crm:secret@db-1:5432/crm_acme", "instanceType": "POSTGRE_SQL_DB" }
Answer
{ "success": true, "statusCode": 200, "data": { "success": true, "data": true } }
Answer when the database refuses
{ "success": true, "statusCode": 200, "data": { "success": false, "data": false, "error": "password authentication failed for user \"crm\"" } }
Key Meaning
connectionString The string, in the format of the database : see the connection strings pages.
instanceType MONGO_DB, MYSQL_DB, MARIA_DB, SQL_SERVER_DB, POSTGRE_SQL_DB or ORACLE_DB.
oracleDBUsername, oracleDBPassword, oracleDBPrivilege Oracle : the user, the password and the privilege, as on the instance form.
  • An array of bodies checks several strings in one call and answers an array in the same order.

From code

const cs = g.req.body.connectionString;
const check = await g.sys.system.isValidConnectionString({ connectionString: cs, instanceType: T.EInstanceType.POSTGRE_SQL_DB });
if (!check.success) throw new Error('This database can not be reached : ' + check.error);

cs = g.req.body.connectionString
check = await g.sys.system.is_valid_connection_string(cs, 'POSTGRE_SQL_DB')
if not check.success:
    raise Exception(f'This database can not be reached : {check.error}')

$cs = $g->req->body->connectionString;
$check = $g->sys->system->isValidConnectionString($cs, 'POSTGRE_SQL_DB');
if (!$check->success) {
    throw new Exception('This database can not be reached : ' . json_encode($check->error));
}

var cs = g.Req.Body.GetString("connectionString");
var check = await g.Sys.System.IsValidConnectionString(new IsValidConnectionString(cs, "POSTGRE_SQL_DB"));
if (!check.Success) throw new Exception($"This database can not be reached : {check.Error}");

import "fmt"

cs := g.Req.Body().String("connectionString")
check, err := g.Sys.System.IsValidConnectionString(am.IsValidConnectionString{ConnectionString: cs, InstanceType: "POSTGRE_SQL_DB"})
if err != nil {
    return nil, err
}
if !check.Success {
    return nil, fmt.Errorf("This database can not be reached : %v", check.Error)
}

let cs = g.req.body()["connectionString"].as_str().unwrap_or_default().to_owned();
let check = g.sys.system.is_valid_connection_string(IsValidConnectionString::new(cs, "POSTGRE_SQL_DB"))?;
if !check.success {
    return Err(am::fail(500, &format!("This database can not be reached : {}", check.error)));
}

String cs = g.req.getBody().getString("connectionString");
Checked check = g.sys.system.isValidConnectionString(new IsValidConnectionString(cs, "POSTGRE_SQL_DB"));
if (!check.isSuccess()) throw new IllegalStateException("This database can not be reached : " + check.getError());

val cs = g.req.body.getString("connectionString")
val check = g.sys.system.isValidConnectionString(IsValidConnectionString(cs, "POSTGRE_SQL_DB"))
if (!check.isSuccess) throw IllegalStateException("This database can not be reached : ${check.error}")

Access and settings

  • Over HTTP, a system API answers once its settings give it apiAccessType: TOKEN_ACCESS (the token of an API user whose group grants this system API, in x-am-authorization) or IS_PUBLIC. Without settings it is NO_ACCESS : your code calls it through g.sys, the admin panel tests it, and an HTTP call is refused.
  • The settings can also cache the answer or require person tokens (authProviders) ; pre and post hooks run around it like around any API.
  • The request headers apply : x-am-response-case, x-am-content-type-response, x-am-internationalization, x-am-tenant-username…

Errors

Code When
400 The body is wrong : the message names the missing or invalid key.
401 No valid API user token, or the API is NO_ACCESS : You are not authorized to access this API.
403 No group grants this system API.