Skip to content
EmberBlocks Docs

Database Connections

Database connections are the bridge between your EmberBlocks apps and your data. By connecting your PostgreSQL databases, you unlock the ability to display, create, update, and delete data through your custom-built interfaces.

What is a Database Connection?

Section titled “What is a Database Connection?”

A Database Connection links your EmberBlocks app to an external PostgreSQL database. Once connected, EmberBlocks can:

  • Introspect your schema to discover tables and fields
  • Query data for display in components
  • Execute operations like creating, updating, and deleting rows
  • Validate types to ensure data integrity

Adding a Connection

Section titled “Adding a Connection”

To add a new database connection:

  1. Open your app in the editor
  2. Navigate to the Data tab
  3. Click Connections in the sidebar
  4. Click the Add Connection button
  5. Fill in the connection details:
FieldRequiredDescription
Connection NameYesA friendly name to identify this connection (e.g., “Production DB”)
HostYesThe database server hostname or IP address
PortYesThe database port (default: 5432)
Database NameYesThe name of the PostgreSQL database
UsernameYesDatabase user with appropriate permissions
PasswordYesDatabase user password (encrypted at rest)
SSL ModeYesSecurity mode for the connection

SSL Mode Options

Section titled “SSL Mode Options”
ModeDescription
disableNo SSL encryption (not recommended for production)
requireSSL required, but server certificate not verified
verify-caSSL required, server certificate verified against CA
verify-fullSSL required, server certificate verified with hostname match

Connection Testing

Section titled “Connection Testing”

Before saving a connection, EmberBlocks automatically tests it to verify:

  • The host is reachable
  • Credentials are valid
  • The database exists and is accessible
  • SSL settings work correctly

If the test fails, you’ll see an error message explaining the issue.

Connection Status

Section titled “Connection Status”

Each connection displays its current status:

StatusDescription
ConnectedConnection is active and working
ErrorConnection failed (hover for details)
PendingConnection has not been tested yet

Managing Connections

Section titled “Managing Connections”

Editing a Connection

Section titled “Editing a Connection”
  1. Click on the connection in the list
  2. Update the desired fields
  3. Click Save to apply changes

The connection will be re-tested automatically after saving.

Deleting a Connection

Section titled “Deleting a Connection”
  1. Click the menu icon on the connection card
  2. Select Delete
  3. Confirm the deletion

Multiple Connections

Section titled “Multiple Connections”

EmberBlocks supports multiple database connections per app. This is useful when:

  • You have data spread across different databases
  • You need to combine data from staging and production
  • Different teams manage separate databases

Each table you import will be associated with its source connection.

Security Best Practices

Section titled “Security Best Practices”

Use Read-Only Users

Section titled “Use Read-Only Users”

For apps that only display data, create a read-only database user:

CREATE USER emberblocks_reader WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE your_database TO emberblocks_reader;
GRANT USAGE ON SCHEMA public TO emberblocks_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO emberblocks_reader;

Limit Permissions

Section titled “Limit Permissions”

For apps that modify data, grant only the necessary permissions:

-- Only allow specific tables
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE customers, orders TO emberblocks_user;

Use Separate Users per App

Section titled “Use Separate Users per App”

Create different database users for different EmberBlocks apps to:

  • Track which app made changes
  • Revoke access independently
  • Apply different permission levels

Network Security

Section titled “Network Security”
  • Firewall Rules: Only allow EmberBlocks IP ranges to connect
  • VPN/Private Networks: Use VPC peering for cloud databases
  • Connection Pooling: Consider using PgBouncer for high-traffic apps

Troubleshooting

Section titled “Troubleshooting”

Connection Refused

Section titled “Connection Refused”

Possible causes:

  • Firewall blocking the connection
  • Database server not running
  • Incorrect host or port

Solutions:

  • Verify the database server is running
  • Check firewall rules allow connections from EmberBlocks
  • Double-check the host and port

Authentication Failed

Section titled “Authentication Failed”

Possible causes:

  • Incorrect username or password
  • User doesn’t have CONNECT permission

Solutions:

  • Verify credentials in your database
  • Ensure the user has CONNECT permission on the database

SSL Certificate Errors

Section titled “SSL Certificate Errors”

Possible causes:

  • SSL mode too strict for the server configuration
  • Self-signed certificate without proper CA

Solutions:

  • Try a less strict SSL mode (require instead of verify-full)
  • Add your CA certificate if using custom certificates

Timeout Errors

Section titled “Timeout Errors”

Possible causes:

  • Network latency too high
  • Database server overloaded
  • Connection pooling exhausted

Solutions:

  • Check network connectivity
  • Monitor database server performance
  • Increase connection pool size on the database

Schema Introspection

Section titled “Schema Introspection”

Once connected, EmberBlocks automatically introspects your database schema to discover:

  • Tables: All tables in the public schema
  • Columns: Name, data type, nullable status
  • Primary Keys: Identifying columns
  • Foreign Keys: Relationships between tables
  • Default Values: Column defaults

You can manually refresh the schema at any time by clicking the Refresh Schema button on the connection.

Next Steps

Section titled “Next Steps”

Now that you have a database connected, learn how to: