Connect a database

restward connect is the one-command path from a database to a live REST API:

restward connect orders-db --connection-string "postgresql://api_reader:s3cret@db.example.com:5432/orders"

Connected: 12 tables, 47 columns
Endpoints live:
  GET  /api/public/customers
  GET  /api/public/customers/{id}
  POST /api/public/customers
  ...
Docs: https://chinook-test-org-vzubqp.run.restward.tech/openapi.json
Key:  rw_aB3dQ2Zx9…  (stored SHA-256-hashed)
Full key (shown only once — store it now): rw_aB3dQ2Zx9f…

You need to be logged in with an organization selected.

Supported databases

The RestWard platform connects to your database, not your machine. The host in the connection string must be reachable from RestWard, so a database on localhost or a private network only works for a self-hosted RestWard that can reach it. RestWard refuses loopback, private and link-local addresses by default; a self-hosted operator who needs them sets DatabaseConnections__AllowInternalTargets=true on the API, the API runtime and the provisioning (workflows) worker.

Passing the connection string

The CLI looks for the connection string in this order:

1. --connection-string "<cs>"
2. the RESTWARD_CONNECTION_STRING environment variable
3. a prompt, when running in a terminal (input is not echoed)

The connection string contains a password, so prefer the environment variable or the prompt over the flag: a flag value can end up in your shell history. The CLI never prints the connection string or the password.

Connection string formats

URI

postgresql://user:password@host:5432/database?sslmode=require
mysql://user:password@host:3306/database
mssql://user:password@host:1433/database
oracle://user:password@host:1521/service_name
db2://user:password@host:50000/SAMPLE

The scheme selects the database type. Special characters in the user name or password must be percent-encoded (for example @ as %40). A missing port uses the default.

Key=value

Host=db.example.com;Port=5432;Database=orders;Username=api_reader;Password=s3cret
Server=tcp:sql.example.com,1433;Database=orders;User Id=api_reader;Password=s3cret

Keys are case-insensitive. The database type comes from a Provider= key, then from --provider. SQL Server-style keys (Server, Data Source, User Id, Initial Catalog) imply SQL Server. Otherwise pass --provider, or the command stops with Cannot infer the database provider.

Db2

IBM Db2 for Linux, UNIX and Windows (LUW) connects to one named database. Use the db2:// URI or the Db2 driver's own Server=host:port form (default port 50000):

db2://db2inst1:s3cret@db2.example.com:50000/SAMPLE?sslmode=disable
Server=db2.example.com:50000;Database=SAMPLE;UID=db2inst1;PWD=s3cret

The API covers the connecting user's schema (upper case, e.g. DB2INST1). For a TLS listener (often port 50001), keep SSL on and give the server's certificate if it is not signed by a CA the platform already trusts:

restward connect orders-db \
  --connection-string "db2://db2inst1:s3cret@db2.example.com:50001/SAMPLE" \
  --server-certificate ./db2-server.arm

The certificate can also be named in the connection string, as ?sslservercertificate=./db2-server.arm (URI) or Security=SSL;SSLServerCertificate=./db2-server.arm (key=value); --server-certificate wins over both. The file is read on your machine and its PEM content (-----BEGIN CERTIFICATE-----) is sent to the platform, which stores it encrypted. A certificate together with --no-ssl, or for another database type, is rejected, and so is a file that contains a private key (nothing is sent). If the server presents a different certificate, or the port does not speak TLS, the connection test fails with TLS handshake failed. The certificate must also name the host you connect to (its subject alternative names or common name), as the Db2 driver checks the host name.

Db2 for z/OS and Db2 for i (AS/400) are not supported.

Oracle

Oracle connects by service name (the EZConnect form), not by SID or connect descriptor. Use the oracle:// URI or the driver's own [tcp:// | tcps://] host:port/service_name form in the Data Source/Server field (default port 1521; tcp:// turns SSL off, tcps:// or no prefix keeps it on):

oracle://user:password@db.example.com:1521/service_name
Data Source=tcp://db.example.com:1521/service_name;Username=user;Password=s3cret

The API covers the connecting user's schema (upper case, e.g. ORCLUSER). Unlike Db2, Oracle does not accept --server-certificate: the server certificate must chain to a CA already trusted by the platform.

If the listener requires a client certificate (mutual TLS), give the auto-login wallet that holds it, the cwallet.sso file of your Oracle wallet directory:

restward connect orders-db \
  --connection-string "oracle://user:s3cret@db.example.com:2484/service_name" \
  --client-wallet ./wallet/cwallet.sso

The file is read on your machine and sent to the platform, which stores it encrypted; it is never shown or returned again, and it is not logged. The wallet is used for every connection RestWard makes to that database (connection tests, schema sync and the generated API). Only auto-login wallets work: a password-protected ewallet.p12 or ewallet.pem is rejected. A wallet together with --no-ssl, or for another database type, is rejected too. If the handshake fails the connection test reports TLS handshake failed (the server's certificate was not accepted, or the port does not speak TLS), or TLS handshake failed: the client wallet could not be opened or used when Oracle cannot open the wallet.

Overrides

• --database <name> replaces the database name from the connection string.
• --provider <p> sets the type for a key=value string without a Provider= key.

SSL

SSL is on by default. It is turned off by any of:

• --no-ssl
• URI: ?sslmode=disable, ?encrypt=false or ?usessl=false (the misspelled ?usesl= still works but prints a deprecation warning)
• key=value: SSL Mode=disable, Encrypt=false, UseSSL=false or Mode=DISABLED

Any other URI sslmode value (require, verify-ca, verify-full, prefer, allow) keeps SSL on; an unrecognized one is rejected.

What gets created

connect <name> runs these steps, printing progress to stderr:

1. Connection: creates a database connection named <name> in your organization. The platform stores the password encrypted.
2. Test: asks the platform to connect to the database. If this fails, the command stops. The connection has been created but no API; delete it in the dashboard (Connections) or use another name when you retry.
3. Schema: reads the tables and columns, which produces the Connected: counts.
4. API: creates an API named <name> with a slug derived from the name (Orders DB becomes orders-db), covering the schemas that contain your tables.
5. Provisioning: starts the provisioning workflow and waits for the API to be running, up to 120 seconds by default (--timeout <seconds> to change it).
6. API key: issues one API key named cli for the new API.

The output

• Endpoints live: a sample of the generated paths, three lines at most. The full list is the API's OpenAPI document.
• Docs: the OpenAPI document of the running API (<endpoint>/openapi.json).
• Key / Full key: the new API key. The full key is shown only this once; RestWard stores only a SHA-256 hash of it. Store it in your secret manager now.

With --json, the same information is returned as data, including the full key in value.key.plaintext:

restward connect orders-db --json | jq -r '.value.api.endpoint, .value.key.plaintext'

Finding the endpoint and key later

restward list                    # every connection and API, with each API's endpoint URL
restward keys --api orders-db    # the API's keys: name, prefix, role, rate limit, allowed IPs, status

restward keys shows only each key's prefix; a key's full value cannot be retrieved after creation. If you lost it, create a new key in the dashboard under Auth & Keys.

To call the API with the key, see API keys & tenant API auth.