SQLite — Nubes Docs

Declare the database

Use a sqlite block to name a database.

nubes.hcl

version = 1

sqlite "db" {}

Declare the database at the top level. Migration configuration is not implemented; migrations_folder is rejected.

Connect the app

Inside an app block, reference the database outputs in its environment configuration:

env = {
  DATABASE_AUTH_TOKEN = sqlite.db.auth_token
  DATABASE_URL        = sqlite.db.url
}

Use names that match what your application reads. Nubes provisions a Turso database scoped to the project, environment, and resource name, creates a database access token, and stores that token in WorkOS Vault. Deployment state holds only the Vault object ID.

Referencing sqlite.db.auth_token grants the app access: Nubes reads the token from Vault when deploying the app and injects it into the named environment variable. Apps without that reference do not receive the token. The token grants read and write access to that database; cross-database attach must be disabled.

Your app supplies its own database client, queries, schema, and migrations. Read the URL and token from the environment variables above to connect directly to Turso.

Provider configuration

The Convex backend uses the official @tursodatabase/api SDK in a Node.js action. Configure NUBES_TURSO_PROVIDER_MODE=turso, NUBES_TURSO_ORGANIZATION, NUBES_TURSO_GROUP, NUBES_TURSO_PLATFORM_TOKEN, and WORKOS_API_KEY. The group must already exist with cross-database attach disabled.

New tokens default to never expiration because application credentials are reused across deployments. NUBES_TURSO_TOKEN_EXPIRATION can override this with a duration such as 2w, but automatic token rotation is not implemented. Existing Vault tokens retain their original expiration. Provisioning retries reuse the database and Vault object.

Review data changes

Keep migrations in version control and inspect them as carefully as application code. Before applying changes to important data, make sure you understand the migration and have a recovery plan.