Connecting a database

RestWard lets you securely connect your organization's databases and expose them as managed REST APIs. Here's how to add and manage database connections.

Supported databases

RestWard works with the following database engines:

• PostgreSQL
• SQL Server
• MySQL
• MariaDB (uses the MySQL driver)

Adding a connection

To connect a database:

1. Go to Connections in the main menu
2. Click Add Connection
3. Select the database type from the grid (PostgreSQL, SQL Server, MySQL, or MariaDB)
4. Fill in the connection details:
   • Connection Name - a friendly name for your reference (e.g., "Production DB")
   • Host - the server address (e.g., db.example.com)
   • Port - the connection port (default is pre-filled based on database type)
   • Username - database user account
   • Password - user password (only visible to administrators)
   • Use SSL - toggle if your database requires encrypted connections
   • Server certificate (IBM Db2 with SSL on) - optional: paste the PEM certificate (-----BEGIN CERTIFICATE-----) the database server presents, or its CA, when it is not signed by a CA RestWard already trusts. It is stored encrypted and never shown again
   • Client wallet (Oracle with SSL on) - optional: upload the auto-login wallet file (cwallet.sso) holding the client certificate when your Oracle listener requires mutual TLS (SSL_CLIENT_AUTHENTICATION=TRUE). The platform uses it for every connection to that database. It is stored encrypted and never shown again; editing the connection lets you replace or remove it. Password-protected wallets (ewallet.p12) are not supported
5. (Optional) Click Browse to search and select a specific database from your server
6. Click Test & Save

RestWard will validate the connection before saving. If the test fails, check your credentials and network access, then try again.

After adding a connection

Once saved, your connection card appears in the Connections list showing:

• Connection name and location (host:port)
• Database provider and database name
• SSL status
• Number of tables available
• Number of APIs using this connection
• Last sync timestamp

Allowing RestWard through your database firewall

If your database sits behind a firewall, security group or private network rule, allow RestWard's outbound addresses before you add the connection. The Connections page shows them in the panel Allow these addresses in your database firewall, with a copy button for each address and Copy all addresses. The add-connection dialog shows the same panel.

These addresses are for RestWard-hosted APIs and connection tests: the platform connects to your database from them. RestWard detects them itself: the platform's API and each running compute host ask RestWard's own echo endpoint what address they connect from, over IPv4 and IPv6, every six hours. Each address shows when it was last verified. An address not verified for more than 24 hours is marked Stale, which means the platform could not re-check it recently; contact your RestWard operator if it stays stale. Some deployments also list extra addresses or ranges (198.51.100.0/24) by configuration; those show as Configured. The panel is hidden when no address is known at all.

Caveat: a NAT gateway with several outbound addresses shows only the address that the echo saw. If your database firewall must allow every NAT address, ask your operator for the full list.

Allow the port your database listens on (PostgreSQL 5432, MySQL and MariaDB 3306, SQL Server 1433, Oracle 1521, Db2 usually 50000, or 50001 with TLS), from each address:

• AWS (RDS, Aurora, EC2): add an inbound rule to the database instance's security group with the database port and source <address>/32. The instance must be publicly accessible, or reachable over the network path you use.
• GCP (Cloud SQL): open Connections, then Networking, then Authorized networks, and add <address>/32. Public IP must be enabled. For a self-managed VM, add a VPC firewall rule that allows ingress on the database port from <address>/32.
• Azure (Database for PostgreSQL flexible server): open Networking, then Firewall rules, and add a rule whose start and end address are both <address>. For a VM, add an inbound rule to its network security group.

IPv6 entries are listed separately. Some managed services, including older RDS and Cloud SQL setups, accept IPv4 only; if yours does, use the IPv4 addresses.

Internal addresses are blocked

For your protection, RestWard refuses connections whose host is — or resolves to — an internal address: loopback, RFC 1918 ranges (10/8, 172.16/12, 192.168/16), link-local (including the cloud metadata address 169.254.169.254), and internal-only names (*.local, *.internal, *.cluster.local, bare hostnames). This applies to every provider, including Oracle and Db2.

This is enforced twice: the platform checks the target when you save or test a connection, and the network layer denies the runtime's egress to internal ranges, so a DNS name that changes its answer after the check (DNS rebinding) still cannot reach an internal address.

Self-hosted deployments can turn the application-level check off with DatabaseConnections:AllowInternalTargets=true (the dev/demo compose layout sets it, because its demo databases live on the same Docker network). The network-level rules are independent of that flag and are configured by your operator — see the deployment documentation (deploy/hetzner/README.md, k8s/README.md).

Testing and refreshing

To verify a connection is still working:

1. On the connection card, click Test - the result shows immediately
2. To refresh the table schema after database changes, click Sync

Editing a connection

To update connection details:

1. On the connection card, click Edit
2. Modify any field except the database type (which cannot be changed)
3. For Password, leave blank to keep the current password, or enter a new one to update it. A stored Server certificate works the same way: leave the field empty to keep it, paste a new one to replace it, or tick Remove the stored certificate
4. (Optional) Click Test to verify changes before saving
5. Click Save Changes

Deleting a connection

Deleting a connection removes it from RestWard but does not affect your actual database.

1. On the connection card, click Delete
2. Read the confirmation message: "This action cannot be undone"
3. Click Delete to confirm

After deletion, any APIs relying on this connection will no longer function.

Troubleshooting

"Failed to load connections"

Refresh the page. If the error persists, check your network connection and contact your RestWard administrator.

Connection test fails

• Verify the Host, Port, Username, and Password are correct

• Confirm your database server is accessible from RestWard's network

• For remote or cloud-hosted databases, check firewall and security group rules

• If using Use SSL, verify your database supports SSL connections

• "TLS handshake failed" means the server's certificate was not accepted or the port does not speak TLS: check the port (Db2 often uses a separate port such as 50001 for TLS) and the Server certificate, and that the certificate names the host you entered (Db2 checks the host name)

• For Oracle, "TLS handshake failed" also covers a refused client certificate; "TLS handshake failed: the client wallet could not be opened or used" means the uploaded wallet is not an auto-login cwallet.sso the driver accepts (upload the wallet's cwallet.sso, not ewallet.p12)

• A few characters cannot be used because the database driver would read them as connection settings or refuses them: IBM Db2 values cannot contain ;, and Db2 passwords cannot start or end with a space; an Oracle host cannot contain (, ) or ,, and an Oracle service name cannot contain ?, :, /, ( or ).

Can't find your database in the browser dropdown

• Click Sync on the connection card to refresh the schema
• Verify your database user account has permission to list databases
• Some database types may not support database browsing; enter the database name manually

Password changes aren't saving

• Ensure you enter a new password in the Password field (leaving it blank keeps the old one)
• Test the connection to verify the new password is correct