Using Database from Cloud Flow

Cloud Flow can read and modify Project Database records from the server. Use it when a Database operation needs trusted authorization, business-rule enforcement, coordinated processing, an external Integration, or work that should not depend entirely on the user's browser.

For example, an event registration workflow can use Cloud Flow to verify registration eligibility and capacity, create an allowed registration, and return a result that the frontend uses to update the Page.

This guide focuses on using Project Database data inside Cloud Flow. For Cloud Flow creation, Web Hooks, access settings, and runtime configuration, see Cloud Flow and Using Database. For exact block inputs and Server API signatures, use the Programming Guide.

When to Use Cloud Flow with Database

Not every Database operation needs Cloud Flow. A Table-Backed Form, Data Table Widget, Page Flow block, or custom frontend implementation can use permitted Database operations through ioLoop's Client APIs.

Choose Cloud Flow when the operation needs server-side trust or coordination beyond ordinary client access.

Requirement	Recommended Approach
Display records the current user is allowed to read	Frontend feature or Client API, subject to Table Access.
Create or edit a permitted record without additional protected rules	Table-Backed Form, Page Flow, or supported Client API.
Validate ownership before modifying a particular record	Cloud Flow with trusted authorization checks.
Enforce capacity, eligibility, or other sensitive business rules	Cloud Flow.
Coordinate changes to several related records	Cloud Flow, with explicit failure and consistency handling.
Use an external provider with protected credentials	Cloud Flow with a configured Connection.
Process a file or generate a file on the server	Cloud Flow file operations.
Return a restricted or derived result from sensitive records	Cloud Flow, with authorization and controlled output.
Implement an AI Agent function that needs trusted data operations	An appropriately configured backend workflow.
Use a Database method or capability exposed only by the Server API	Cloud Flow using the supported $io.db Server API operation.

Cloud Flow is not only a security boundary. It also provides access to additional Database functionality available through the Server API that is not exposed by the browser-side Client API.

Visual programming versus custom code is a separate choice from browser versus server execution. Cloud Flow supports visual blocks and server-side JavaScript using ioLoop Server APIs; Page Flow blocks, built-in Forms and Widgets, and custom frontend JavaScript use supported Client APIs.

Client Database API vs. Server Database API

ioLoop exposes Database functionality through both browser-side and server-side APIs, but their method sets and capabilities are not identical.

API	Where It Runs	Scope
Client $io.db.*	Pages, Forms, Page Flow, Widgets, and custom frontend JavaScript in the browser.	Supported client-side Database operations, subject to the applicable Project access rules.
Server $io.db.*	Cloud Flow and supported server-side JavaScript.	A broader Database API with additional methods and functionality beyond the Client API, appropriate to the server environment.

This distinction is about available operations, not merely where the same code executes.

The built-in frontend components and custom frontend implementations share the same Client API capabilities. That equivalence does not extend to parity between the Client and Server Database APIs. A feature provided by $io.db on the server should not be assumed to exist in browser-side $io.db, or to have the same parameters or runtime behavior.

When choosing an implementation:

1. Check whether the required Database functionality is supported by the Client API.
2. If it is supported and the current user's access rules permit it, a direct frontend operation may be appropriate.
3. If it requires a server-only $io.db method, trusted processing, or additional protected rules, implement it through Cloud Flow.
4. Use the appropriate API reference for the selected environment and handle its documented inputs, results, and errors.

For the exact differences in methods and signatures, consult the $io.db Client API and $io.db Server API. This guide does not attempt to reproduce the method lists maintained in those references.

How Database Operations Work in Cloud Flow

Cloud Flow can use Database operations to retrieve records, create records, update existing records, and delete records when the workflow permits those changes. The following operations illustrate common record workflows; they are not an exhaustive list of the methods or functionality available through the $io.db Server API.

Operation	Typical Use	Important Consideration
Read	Retrieve records for validation or processing.	Read only the records and fields needed.
Lookup	Retrieve a specific record or matching record.	Handle missing records and verify access to the selected record.
Create	Add a record after a trusted check.	Validate required values and prevent unintended duplicate submissions.
Update	Change a record's status or other fields.	Identify the intended record and verify that the change is allowed.
Delete	Remove an approved record.	Apply authorization and consider related records or files.
Count	Check how many records meet a condition.	Distinguish the full matching count from a count of records in a loaded page.

ioLoop provides Database blocks in the Cloud Flow editor and Database functions in the $io.db Server API. Use the appropriate approach for the workflow; both operate within the supported server-side Database environment. The visual Database block set and the complete Server API should not be assumed to have identical coverage.

For exact server-side methods, parameters, return values, dataset behavior, and asynchronous options, see Cloud Flow Database Blocks and the $io.db Server API. Do not use the Client API reference as the complete specification of server-side Database functionality.

Working with Record Identifiers

Updates and deletes commonly require identifying an existing record.

A record ID supplied by Page Flow, custom JavaScript, an AI Agent, or an external Web Hook is input, not proof that the caller may use that record.

Before changing a record:

1. Validate that the submitted identifier has the expected form.
2. Retrieve the intended record using a supported Database operation.
3. Confirm the record exists.
4. Verify the caller's permission to perform the requested action on that particular record.
5. Check the record's current status and any business conditions.
6. Apply the change only if the checks succeed.
7. Return a result appropriate for the caller.

A successful lookup does not itself establish authorization.

Typical Page-to-Cloud Flow Workflow

A common application pattern is:

1. The user performs an action on a Page, Form, Widget, or custom frontend interface.
2. Page Flow or custom JavaScript collects the required input and invokes a Cloud Flow Web Hook.
3. The Web Hook receives the request and validates its structure.
4. Cloud Flow establishes the trustworthy caller context and checks whether the requested operation is allowed.
5. Cloud Flow reads existing data and applies the business rules.
6. Cloud Flow performs the permitted Database operations and any required trusted processing.
7. Cloud Flow returns a success or error result.
8. The frontend updates the interface only after interpreting that result.

Page, Form, Widget, or Custom Frontend
  Collect input and call Cloud Flow
              |
              v
Cloud Flow Web Hook
  Validate request and authorization
              |
              v
Project Database
  Read, create, update, or delete records
              |
              v
Cloud Flow Result
  Success information or safe error details
              |
              v
Frontend
  Confirm, refresh, or explain failure

This is a conceptual workflow, not a specific Cloud Flow block sequence or API contract. For configuring the invocation itself, see Calling Cloud Flow from Pages.

Queries in Cloud Flow

Named Queries provide reusable record-retrieval patterns defined under a Database table.

They are useful when Cloud Flow needs to:

• Find active registrations for a selected event.
• Retrieve orders related to a customer.
• Load pending approvals for processing.
• Read records in a predictable sorting order.
• Include related fields through a configured Data Join.
• Retrieve selected fields rather than a complete record.

The Query editor defines Search Criteria, Field Selection, Data Joins, and Sorting Order. Criteria use positional runtime values shown as Input-1, Input-2, and so on; the editor does not store fixed literal operands. Cloud Flow supplies those inputs in the defined order.

Passing Query Inputs

For example, a named query called RegistrationsByEvent can use an event identifier supplied by the Cloud Flow workflow. Cloud Flow should validate the identifier and the caller's right to use that event before relying on the query results.

When using the direct $io.db.readQuery Server API, queryInput is an array, and values must follow the parameter order defined by the query. Do not assume that the input object used by a visual block can be passed unchanged to the API.

The full signature and usage requirements belong in the $io.db Server API. For configuring the query itself, see Queries.

Reading Results and Counts

Database read operations may be asynchronous. Continue dependent processing only after the relevant operation has completed successfully.

Distinguish:

• No matching records: A successful read that returns an empty result.
• Failed read: An operation that did not complete successfully.
• Current-page record count: The number of records loaded in a dataset page.
• Full matching count: The number of records satisfying a query across the relevant result set.

When a workflow needs a total matching count, use a supported count operation appropriate to that purpose rather than assuming that the number of records currently loaded equals the total.

Check the documented result structure of each block or API before reading its data or error values.

Validation and Authorization

Cloud Flow executes on the server, but server-side execution does not automatically establish that an operation is authorized.

A Cloud Flow Web Hook may be callable by a signed-in Project User, a particular User Group, or an external system. Its access configuration controls who can invoke it. The workflow must still decide whether the specific requested action is allowed.

Before sensitive Database operations, check:

Check	Example
Caller identity	Determine the authenticated user or trusted external caller where required.
Operation permission	Confirm that the caller is allowed to request this operation.
Record authorization	Confirm the user may view or change this specific order or registration.
Required values	Reject missing or invalid fields.
Current record state	An archived order should not be modified through an active-order workflow.
Business conditions	A registration is allowed only while capacity remains.
Response scope	Return a confirmation rather than sensitive internal fields.

Treat browser-provided user IDs, User Group names, record IDs, amounts, and status values as untrusted inputs. A hidden field or disabled button is not a security control.

Table Access and Cloud Flow authorization have different roles. Table Access governs permitted Database operations under the Project's access model. Cloud Flow can enforce additional trusted rules such as record ownership, eligibility, state transitions, or restricted fields. Do not assume that a table permission or a Web Hook's access setting automatically implements all of those business rules.

For more information, see Table Access and Cloud Flow Access Security.

Creating and Updating Multiple Records

Some workflows involve more than one Database record. For example, accepting a registration may require creating a registration and updating an event's registration count.

Cloud Flow is a suitable place to coordinate these steps, but multiple Database operations should not be assumed to form an automatic atomic transaction.

Plan for:

• A validation succeeding but a later write failing.
• Two callers attempting the same action at nearly the same time.
• A request being retried after a timeout.
• One related record changing while another operation is underway.
• Partial results that require recovery or reconciliation.

Use the supported Database and Backend facilities appropriate to the consistency requirement. If a workflow must enforce a limit under concurrency, a simple read-count followed by create may be insufficient by itself; the server-side implementation must account for overlapping requests.

Do not report complete success until the required operations have actually succeeded.

Example: Event Registration with Capacity Rules

Consider a Project with Events and Registrations tables.

A registration Page collects the attendee's details and selected event. Its Form or custom frontend implementation calls a Cloud Flow Web Hook to process the request.

1. Receive and validate the request

Cloud Flow receives the event identifier and attendee information. It validates required values and establishes any required caller context.

2. Retrieve the relevant records

Cloud Flow looks up the event and uses the appropriate records or named query to examine current registration data.

3. Apply trusted rules

The workflow checks that the event exists, registration is open, eligibility conditions are satisfied, and capacity is available. It also accounts for duplicate or concurrent submissions according to the application's requirements.

4. Apply permitted changes

If the checks succeed, Cloud Flow creates the registration and performs any other required related updates through supported operations.

5. Return a controlled result

On success, Cloud Flow can return a status, registration identifier, and concise confirmation data. On failure, it returns an appropriate error outcome, such as registration closed or request not permitted.

6. Update the frontend

Page Flow or custom JavaScript interprets the result, confirms success, or explains the failure without assuming the operation succeeded merely because the Web Hook was invoked.

This example illustrates responsibilities; it is not a guarantee that a particular sequence of reads and writes automatically enforces capacity safely under concurrent requests.

Database Files and File Fields

Cloud Flow can work with files associated with Database records, including processing uploads, generating documents, and updating file-related record values.

Database file fields are different from public frontend Media assets. Files associated with Database file fields inherit the access rules of the table that owns them. If a table permits public Read access, its associated files must also be treated as publicly accessible.

For sensitive documents:

• Avoid placing them in file fields of publicly readable tables.
• Confirm that the table's permissions match the intended audience for the files.
• Check record-specific authorization when protected access depends on ownership or other application rules.
• Use an appropriate private-file workflow when access must be more restrictive than the table's access model allows.
• Do not assume that returning a public file URL after a Cloud Flow authorization check makes that URL private.

For file generation, file storage, links, and processing, see File Fields and Using Files. For exact server-side file functions, use the Server API.

Returning Data to the Caller

A Cloud Flow response should contain enough information for the caller to take the next step, but no more than necessary.

Examples include:

Outcome	Useful Response Information
Record created	Success status, new record ID, confirmation message.
Record updated	Success status and relevant updated summary.
Validation failed	A safe, actionable message about the invalid input.
Operation denied	A failure result without exposing protected record information.
External service failed	A suitable error outcome and recovery guidance.

Avoid returning full records, private fields, provider tokens, or internal diagnostic details when the frontend only needs a small response.

Different Cloud Flow blocks and Server APIs have their own documented result structures. Do not assume every result uses an identical object shape. Inspect the relevant reference and handle both success and failure explicitly.

Development and Production Data

Database records in development and production are separate.

During Preview, built-in Database operations automatically use the Project's development database. This applies when testing built-in Database workflows through the saved development experience.

The published application uses production data where supported by the Project plan. Development records are not routinely copied into production when publishing.

When testing Cloud Flow:

1. Prepare representative records in the development database.
2. Invoke the workflow through its intended development or Preview path.
3. Verify the Database changes and inspect test logs.
4. Test successful, denied, empty-data, and failed-operation outcomes.
5. Confirm the execution environment and configured Connections when running workflows from other entry points, including externally invoked Web Hooks or scheduled tasks.
6. After publishing, verify the intended production behavior with appropriate safeguards.

Built-in Database environment selection does not automatically put external services into test mode. A Connection or external provider can have independent live/test behavior. Check that configuration before running potentially consequential operations.

For details, see Development and Production Data and Testing and Logs.

Troubleshooting

Problem	What to Check
Record not found	Table name, record ID, data environment, and whether the record exists.
Query returns no records	Query inputs, Search Criteria, and whether an empty result is expected.
Query result is missing fields	Field Selection, Data Joins, and assumptions made by the workflow.
Update affects the wrong record	Record identity, caller-provided input, and authorization checks.
Access denied	Web Hook access configuration, trustworthy caller context, Table Access, and record-specific rules.
Unexpected count	Whether the workflow used a current dataset page count or a full matching count.
Duplicate or partial changes	Repeated calls, overlapping requests, and incomplete multi-step operations.
File is unexpectedly accessible	Parent table Read access, storage type, and whether the file URL is public.
Data differs from published results	Development versus production records and invocation context.
External call fails	Connection configuration, provider environment, response handling, and safe Cloud Flow logs.

Use Testing and Logs to investigate backend execution. Record only the information needed for diagnosis, and avoid logging credentials or sensitive record contents.

Good Practices

• Use Cloud Flow for trusted decisions. Keep authorization, protected rules, and secret-dependent processing on the server.
• Use direct frontend operations where appropriate. Do not add a Web Hook for every simple permitted Database read or write.
• Choose the appropriate API surface. The Server $io.db API provides additional Database methods and functionality beyond Client $io.db; consult the Server API reference for Cloud Flow implementations.
• Validate both requests and records. Do not trust submitted IDs or user claims without appropriate checks.
• Use named queries purposefully. Reuse stable retrieval patterns and supply inputs correctly.
• Handle asynchronous completion. Inspect results before moving to dependent steps.
• Plan for repeated and concurrent calls. Important multi-record operations need explicit consistency handling.
• Limit returned data. Send only the fields and status information callers need.
• Protect files through the correct model. File fields follow their table's access rules.
• Test both data environments deliberately. Preview uses development data; verify production behavior after publishing.

Common Mistakes

Avoid these patterns:

• Treating Cloud Flow access permission as complete record-level authorization.
• Updating a record solely because the browser supplied its ID.
• Assuming a named query grants permission to read the records it selects.
• Using the number of records in one loaded page as the total matching count.
• Assuming several Database writes are automatically transactional.
• Assuming that every Server $io.db method is available through Client $io.db, or that corresponding methods necessarily have identical signatures.
• Displaying success before the required Database operations finish.
• Returning more record data than the caller needs.
• Assuming a Database file field is private when its parent table is publicly readable.
• Assuming Preview places external integrations into test mode.
• Testing only the successful path or only as an administrator.

Cloud Flow and Database work together most effectively when Cloud Flow provides a deliberate trust boundary around the operations that need it, while ordinary permitted data interactions remain straightforward for the frontend.

Technical Reference

For exact block names, inputs, return values, API parameters, and runtime behavior, see:

• Cloud Flow Database Blocks
• $io.db Server API — authoritative reference for the broader server-side Database method set.
• $io.db Client API — reference for the browser-side Database method set.
• Result Objects
• Cloud Flow Access Security

Related Topics

• Database
• Queries
• Table Access
• File Fields
• Development and Production Data
• Using Database from Pages
• Cloud Flow
• Using Database
• Calling Cloud Flow from Pages