Connect managed databases
Provision project data, use named bindings in preview and production, and keep provider credentials behind BlinkHost.
Last updated 2026-09-30
What you'll achieve
- Choose the supported database path.
- Use a sole DEFAULT without losing legacy data.
- Understand primary and replica consistency.
One database per application environment
New managed database configurations use one database named DEFAULT per application environment. Preview and production are separate environments. Multiple database bindings and cross-database transactions are outside the supported native contract. Existing legacy aliases require a planned migration that preserves their database and data; do not delete a database to resolve a binding error.
Open your project's Databases area to check availability, its current binding and environment. Provisioning a database does not by itself enable every runtime database capability.
Backend modules that only read can query the existing read-only SDK. For a project whose binding is already DEFAULT, the Rust call is:
let rows = blinkhost_sdk::query("DEFAULT", "SELECT id, name FROM users LIMIT 20", "[]")?;
Keep schema and forward migrations with the project under database/DEFAULT/. Review them with the application change. Editing a declaration or source scaffold does not apply a live database migration. Never place provider tokens or production snapshots in this source directory.
Choose the execution path
| Path | What it provides |
|---|---|
Legacy backend query_db / query_db_v2 |
Bounded read-only queries through a database binding. These imports reject mutations. |
Native database_v1 |
Single-database reads, writes, atomic batches and operation status, only after explicit native admission and a compatible managed compiler/SDK release. |
| Backend outbound HTTPS to a database provider | A separate external-service request. It requires application credentials and outbound permission and does not use the native binding's receipt or replica contract. |
| Control-plane database tools | Authorized management operations. Their availability does not prove a guest module can call the same operation. |
Native transactions are undergoing production acceptance. Do not assume they are available to an existing project because a binding or example is present. See the native contract before planning a cutover.
Primary and replicas
Turso is the write authority for a managed database. A local edge replica can serve eligible reads. It is not an independent writable database: the runtime does not execute the same business mutation separately against Turso and a local SQLite file. Other edge nodes synchronize their own replicas from the authority.
Primary or session reads are needed when the application must observe a committed operation immediately. Eventual reads can be stale and are appropriate only when that is acceptable to the application. An unavailable primary never authorizes local fallback writes.
Keep migrations explicit
Review backups, schema compatibility, current writers and the exact database identity before adopting the native interface. Fence the old writer and reconcile uncertain requests before switching traffic. Changing a secret or removing a URL from source does not revoke an old provider credential. Do not run the legacy HTTP writer and native writer concurrently as an implicit migration strategy.
Applications remain responsible for user authentication, row-level authorization, constraints and conflict handling. An application database and Hosted Object Storage do not share an atomic transaction.
Help improve this page
Sign in to send page-specific feedback. For account-specific help, email support@blinkhost.me.