Database Sync - Blue Docs

Database Sync copies rows from one table in your own MySQL or PostgreSQL database into a Blue workspace. Each row becomes a record. Blue reads the table on a schedule and updates the mirrored records.

The mirror is one-way. Blue never writes to your database. Mirrored fields are read-only in Blue and must be changed at the source.

Before you start

You must be a Project Administrator in the workspace that receives the records.

Your database must meet these conditions:

The provider is MySQL or PostgreSQL.
The database accepts connections from the internet. Blue refuses hosts that resolve to a private, internal, or link-local address.
The database accepts TLS connections with a certificate that a public certificate authority signed. Blue always connects with TLS and verifies the certificate. You cannot disable TLS.
The source table has one primary key column. Blue does not support composite primary keys.
The source table has a timestamp column that records the last change to each row. The column cannot contain null values.

Create a database user with read-only permission on the source table. Blue only reads.

Connect a database

Open the workspace that will receive the records.
Open Settings > Database Sync.
Enter a Connection name.
Enter the connection details with one of these methods:
- Paste a URL into Connection URL. Blue fills the connection fields.
- Select Database type, then enter the Host, Port, Database, Username, and Password.
Review the connection fields. You can change each field separately.
Select Test connection. Blue confirms that it can reach the database with these credentials.
Select Load tables.

Database Sync connection form with a Test connection button

Blue stores the password encrypted. After the connection is saved, leave the password field blank to keep the saved password.

Blue accepts URLs that start with mysql://, postgres://, or postgresql://. Blue clears the URL after it fills the fields and does not save the complete URL. Add a private CA certificate separately in CA certificate.

Blue connects with TLS and verifies the server certificate on every connection, including the connection test. If the database refuses TLS, the test fails.

Select the table and map the columns

Open Source table.
Enter part of the schema or table name to filter the table list.
Select a table. Blue reads the table structure and shows the first rows in Preview.
Select the Primary key column. Blue uses this value to match a source row to its Blue record.
Select the Updated at column. Blue uses this timestamp to find changed rows.
Select the Title column. This column becomes the record title and is required.
Enter Interval seconds to set how often Blue syncs. The default is 900 seconds. The permitted range is 60 seconds to 24 hours.
Set Mirror to for each remaining column.
Select Activate mirror. Blue queues the initial import and syncs the whole table.

Column mapping table with a Blue field selected for each external column

For each column, Mirror to accepts:

Do not mirror: Blue ignores the column.
A default field: Description, List, Start date, or Due date.
An existing custom field in the workspace.
+ Create new field…: Blue creates a custom field for the column. Enter a Field name, select a Field type, then select Create field.

The Suggestion column shows the field type Blue derives from the column name and SQL type. Confirm or change the suggestion. Two columns cannot mirror to the same Blue field.

Blue locks the selected Title column to Record title in the mapping table. To use a different source column for record titles, change Title column above the table.

Supported field types

You can mirror a column to a custom field of these types:

Single line text, Multi line text, Email, URL, Phone, Number, Percent, Rating, Currency, Checkbox, Date, Single select, Multi select, and Country.

You cannot mirror a binary column, such as blob, binary, varbinary, or bytea.

A single select or multi select field accepts a maximum of 500 new options for each sync. If a column produces more options, the sync fails and names the column. Map a high-cardinality column to a text field instead.

Read the sync status

The Database Sync page shows the connection status, the last successful sync, the last attempted sync, the number of mapped fields, and the ten most recent runs.

Active database sync connection with status tiles and the sync history table

Each run reports its duration, the rows scanned, and the records created, updated, and skipped. A running sync shows its current elapsed time. Blue skips a row when the source values did not change.

Use these actions on an active connection:

Sync now: Blue queues one sync of the rows changed since the last successful sync.
Full refresh: Blue rereads the whole table. This run takes longer than a scheduled sync.
Pause: Blue stops scheduled syncs. Mirrored records and fields stay read-only.
Resume: Blue restarts scheduled syncs and queues a catch-up sync.
Delete: Blue stops the sync and deletes the saved credentials.

The workspace name shows a Mirrored badge while a connection exists.

Work with mirrored records

Blue locks mirrored data so that the source database stays the only place to change it. A mirrored field shows Synced from database above its value.

Record fields marked "Synced from database" with an unmirrored field below them

While a connection exists, you cannot:

Change a mirrored field on a mirrored record.
Change or delete a custom field that a mapping targets.
Delete a mirrored record, or move it to the trash.
Delete the list that holds mirrored records.
Rename that list, if a column mirrors to List.
Delete the workspace.

Fields that no mapping targets stay editable. You can also comment on a mirrored record, add checklists and files to it, and use it in views, reports, and automations.

The locks stay in place while the connection is paused or in error. Delete the connection to release them.

Deleted and missing rows

Blue never deletes a record because its source row disappeared.

A scheduled sync reads only changed rows, so it does not detect a deleted source row. Select Full refresh to find them. Blue marks a record whose source row no longer exists as missing at source. The record stays in the workspace, and its fields become editable again.

When the source schema changes

Blue compares your table structure against the saved mappings before each sync.

If a mapped column is removed, or its type is no longer compatible with the Blue field, Blue pauses that one mapping and continues the sync. The mapping shows the status paused in the field table.
If the primary key column or the timestamp column is removed, or the timestamp column is no longer a timestamp, Blue pauses the whole connection and marks the run as failed.

To restart a paused connection after you correct the source table, select Resume.

Troubleshooting

Result	Cause and action
Test connection fails	Check the host, port, credentials, and that your database accepts connections from the internet.
Blue refuses the host	The host resolves to a private or internal address. Use a publicly reachable host.
Test connection reports a TLS or certificate error	The database does not accept TLS connections, or its certificate is self-signed, expired, or issued for a different host name. Correct the certificate on the database.
A warning asks for a stable primary key	The table has no single primary key column, or you selected a column that is not one.
A warning asks for a non-null timestamp column	The Updated at column accepts null values, or is not a timestamp type. Correct the column in your database.
The connection status is error	Read the message on the connection and in Sync history. Blue retries automatically, and returns the connection to active after a successful sync.
A field is paused in the field table	The source column changed. Correct the column, or delete and recreate the connection with a new mapping.
Records were not deleted after you deleted source rows	This is expected. Select Full refresh to mark them as missing at source.

For further help, email support@blue.app.