Skip to content
📌 OpenRun 1.0 is released, read the announcement
Service Bindings: PostgreSQL, MySQL, SQLite, Redis and More

Service Bindings: PostgreSQL, MySQL, SQLite, Redis and More

OpenRun is an open-source web app deployment platform with built-in PostgreSQL, MySQL, SQLite and Redis/Valkey service bindings, plus installable binding providers for SQL Server, Oracle, MongoDB (including Atlas), Snowflake and ClickHouse. A service binding automatically provisions isolated database access for an application and injects the generated connection information into its environment.

Teams configure a managed or self-hosted database once, with its backups, monitoring, fault tolerance and capacity management, and safely share that installation across multiple apps. Production and staging environments get separate accounts, and derived bindings let multiple apps share a schema or database with distinct least-privilege credentials. SQLite bindings provide a persistent volume for database files, with optional continuous SQLite replication to S3 with Litestream.

This page covers:

The service types compiled into the server are:

Service typePurpose
postgresCreate Postgres schemas and roles
mysqlCreate MySQL databases and users
sqliteProvide a persistent volume with SQLite database files per app
redisCreate Redis ACL users isolated by key prefix (Redis 7+)
valkeyValkey servers, same ACL-based implementation as redis

Additional service types come from out-of-process binding providers, installed with openrun provider install:

ProviderService typesPurpose
sqlserversqlserverCreate SQL Server schemas and users (SQL Server 2019+)
oracleoracleCreate Oracle users and schemas (pure-Go driver)
mongodbmongodb, atlasCreate MongoDB databases and users, self-hosted or Atlas
snowflakesnowflakeCreate Snowflake roles and schemas with key-pair accounts
clickhouseclickhouseCreate ClickHouse users, self-hosted or ClickHouse Cloud
databricksdatabricksDatabricks SQL warehouses, Unity Catalog schema isolation

All service types share the same workflow: services, base and derived bindings, staging/prod accounts, grants and promotes work identically whether the binding is built in or provider-installed. The built-in types are Apache 2.0 licensed, the providers have a separate license.

Managed PostgreSQL, MySQL and Redis Access

OpenRun automates the database provisioning work normally performed for each web app:

  • Create an isolated PostgreSQL schema and role, MySQL database and user, or key-prefix scoped Redis ACL user.
  • Generate a unique password and application connection URL.
  • Inject database connection information into the app environment.
  • Maintain separate production and staging database accounts.
  • Create derived accounts with read-only, scoped or full-access grants.

The database server remains under the operator’s control and can be self-hosted or provided by a managed database service. OpenRun connects with the configured administrator URL only when it needs to create accounts, apply grants or inspect a binding. Applications never need the administrator credentials of any bound service.

Concepts

TermMeaning
ServiceAn admin connection to an endpoint (database). Apps do not use this connection directly; OpenRun uses it to create database users and apply grants
Base BindingCreated from a service. It creates the main database account for an app: a schema and role for Postgres, a database and user for MySQL
Derived BindingCreated from a base binding. It uses the same schema or database as the base binding but gets a separate account. Grants on the derived binding control what that account can do
A Postgres service with admin credentials creates a base binding with a new schema and role; derived bindings share the schema with their own roles and grants, and each app gets its binding credentials in its environment A Postgres service with admin credentials creates a base binding with a new schema and role; derived bindings share the schema with their own roles and grants, and each app gets its binding credentials in its environment
Service, base binding and derived bindings

Bindings always have a staging and a prod environment:

  • Staging apps are bound to the stage binding env, prod apps to the prod env. The staging app gets an isolated test environment that closely matches prod.
  • Grant related binding changes are applied to the staged binding first. binding update --promote promotes the staged grants to prod.

Create Services

Use openrun service create to create a service. The service id is <service_type>/<service_name>.

openrun service create postgres/main \
  --is-default \
  --config url=postgres://admin:secret@db.example.com:5432/appdb

openrun service create mysql/main \
  --is-default \
  --config url=mysql://admin:secret@db.example.com:3306/

The first service of a type is automatically marked as default; --is-default marks a service as the default explicitly. A binding source can be the full service id like postgres/main, or just the service type like postgres, which uses the default service for that type:

openrun binding create postgres /apps/reporting-db

Secret references in service config

Service config values can reference secrets with {{secret ...}} or {{secret_from ...}} template references, so credentials do not have to be stored in the metadata database:

openrun service create postgres/main \
  --config 'url={{secret_from "asm" "prod_db_admin_url"}}'

The reference is stored as is and resolved through the secret provider each time the service connection is used. A rotated secret value takes effect on the next operation without a service update.

Under RBAC, creating or updating a service whose config references a secret additionally requires the secret:read permission. The referenced value flows resolved to the service’s binding provider, so selecting which secrets a service uses is restricted to users allowed to use the secret store, rather than implied by service:manage alone.

List, update and delete services

List services with:

openrun service list
openrun service list postgres
openrun service list postgres/main

Update service default status with:

openrun service update postgres/main --set-default=true

Service config values can be changed in place with --config key=value; an empty value (--config key=) deletes the key. The new config is used from the next operation on the service. Accounts already generated for existing bindings are not changed:

openrun service update postgres/main --config url=postgres://admin:newsecret@db.example.com:5432/appdb

Delete a service with:

openrun service delete postgres/main
  • A service cannot be deleted while bindings created from it exist; delete the bindings first.
  • A service linked as the staging service of another service is likewise blocked while that other service has bindings, since their staged accounts are provisioned on the staging service.
  • Deleting a service removes only OpenRun’s record of the admin connection. Nothing is changed on the backend database itself.

Hostname Mapping Basics

Service connection URLs are used in two places, and the hostnames can differ: OpenRun uses the admin URL to create and manage binding accounts, and app containers use generated account URLs to connect at runtime. Generated binding accounts therefore include two URLs:

Account fieldHostnameUsed by
urlService URL hostname, replaced by the service config key binding_hostname when it is setApp containers
url_directOriginal service URL hostnameOpenRun commands such as binding run-command

This matters for local database services. If a Postgres, MySQL or Redis service URL points at localhost, 127.0.0.1 or ::1, app containers usually cannot use that hostname to reach the host database:

  • Outside Kubernetes, OpenRun automatically maps those local hostnames to a container-reachable hostname: host.docker.internal for Docker, host.containers.internal for other local container runtimes.
  • Set binding_hostname explicitly to override that value.
  • Set binding_hostname=disable to keep the service URL hostname unchanged and skip automatic mapping.

Staging Services

A service can specify a separate staging service of the same service type. When a binding is created, OpenRun creates the staged account using the staging service and the prod account using the main service. Create the staging service first, then reference it from the main service:

openrun service create postgres/stage \
  --config url=postgres://admin:secret@stage-db.example.com:5432/appdb

openrun service create postgres/main \
  --is-default \
  --stage stage \
  --config url=postgres://admin:secret@prod-db.example.com:5432/appdb

You can add, change, or clear the staging service later:

openrun service update postgres/main --stage stage
openrun service update postgres/main --stage ""

The staging service cannot refer to itself. If no staging service is linked, stage bindings are created on the same endpoint as prod, just in a separate schema/database. Stage performance issues can impact prod in that case.

Create Base Bindings

Create a base binding using a service source:

openrun binding create postgres/main /apps/reporting-db
openrun binding create mysql/main /apps/inventory-db

Base bindings cannot have grants. The generated account owns the binding’s schema or database.

The account information is not shown by binding get or binding list (binding list --source postgres/main lists the bindings created from a service or base binding). Use binding show-account to view the generated connection information:

openrun binding show-account /apps/reporting-db
openrun binding show-account --stage /apps/reporting-db

With RBAC enabled, show-account needs the binding:reveal permission, which requires an explicit grant: it is not implied by binding:manage and binding owners do not hold it by default.

For testing, SQL can be run as the binding account. Output can be truncated for large result sets.

openrun binding run-command /apps/reporting-db "select current_user"
openrun binding run-command --stage /apps/reporting-db "select current_user"

Create Derived Bindings

Create a derived binding by using a base binding path as the source.

openrun binding create --grant "read:*" /apps/reporting-db /apps/reporting-read
openrun binding create --grant "create:*" /apps/reporting-db /apps/reporting-writer
openrun binding create --grant "full:events" /apps/reporting-db /apps/reporting-events-admin

Derived bindings have to be created from base bindings. A derived binding cannot be used as the source for another derived binding.

Grants are supported only on derived bindings. A grant is specified as type:target.

GrantMeaning
read:*Read all tables
read:<table>Read one table. If the table does not exist yet, the grant is deferred.
create:*Create tables
full:*Read, write and create
full:<table>Read and write one table

create:<table> is not supported. Create access applies to the schema or database.

If a table-specific grant references a table which does not exist yet, OpenRun skips the grant for that run. The grant is kept in the metadata and applied on the next update/apply call or with --reapply-all. The backend-specific effect of each grant is listed in the PostgreSQL, MySQL and Redis sections.

Update and Promote Grants

Grant updates are staged. The update is applied to the staged account first.

openrun binding update --add-grant "read:*" /apps/reporting-read
openrun binding update --delete-grant "read:old_table" /apps/reporting-read

Prod is not updated until the binding is promoted:

openrun binding update --promote /apps/reporting-read

You can update and promote in one command:

openrun binding update \
  --add-grant "read:*" \
  --delete-grant "read:old_table" \
  --promote \
  /apps/reporting-read

Use --reapply-all to apply all grants again, after creating a table for which a table-specific grant was previously deferred, or after manual database changes.

openrun binding update --reapply-all --promote /apps/reporting-read
Binding promotion is separate from app promotion. app promote promotes the app version and app metadata, including the list of binding paths attached to the app. It does not promote staged grant changes inside a binding. Use binding update --promote or apply --promote for that.

Health Checks

Health checks verify a service or a binding account end to end. The server actually connects to the backend and runs a no-op operation (select 1 / ping), so the checks catch unreachable endpoints, rotated or expired admin credentials, and binding accounts dropped or disabled outside OpenRun:

openrun service health postgres/main
openrun binding health /apps/reporting-db
openrun binding health --stage /apps/reporting-db
  • service health connects with the service’s admin credentials (secret references resolved the same way as other operations).
  • binding health connects as the binding’s generated account: the production account by default, the staged account (against the linked staging service, when one is configured) with --stage.
  • Exit status: a healthy check exits 0; any failure exits non-zero with the backend error.
  • Providers: the checks work uniformly for the built-in service types and installed provider service types. A provider built with an SDK that predates health checks reports that the provider needs an update.
  • SQLite: SQLite bindings have no endpoint or accounts to probe; their checks validate the binding configuration and otherwise always report healthy.
  • RBAC: under RBAC, service health requires service:read on the service and binding health requires binding:read on the binding path.

Delete Bindings

openrun binding delete /apps/reporting-read
openrun binding delete --dry-run /apps/reporting-db

Deleting a binding also deletes the account objects that were created for it on the backend service, for both the production and staging accounts (using the linked staging service when one is configured). The objects recorded when the binding account was generated are dropped in reverse creation order:

BackendBase binding deleteDerived binding delete
PostgresThe binding’s role and schema are dropped, including everything in the schema (CASCADE) and any objects the role still owns elsewhereOnly that binding’s role is dropped (plus objects it still owns, such as tables it created in the shared schema)
MySQLThe binding’s user and database are dropped, including the database contentsOnly that binding’s user is dropped (plus objects it still owns)
Redis/ValkeyThe binding’s ACL users (production and staging) are removed. Keys under the binding’s prefix are not touched; have the app clear its keys first if the data should go tooThe derived ACL users are removed
SQLiteThe volume and any replicated data are kept (details)Not applicable
ProvidersProvider service types drop the users/schemas/databases the binding created, per the provider’s documentationPer the provider’s documentation
For Postgres and MySQL, deleting a base binding deletes the schema or database data. There is no separate confirmation, so treat binding delete of a base binding like a DROP statement. Deleting a derived binding leaves the base binding’s schema/database and data untouched.

A base binding cannot be deleted while bindings derived from it exist, since their accounts live in the base binding’s schema/database. Delete the derived bindings first.

Dry runs, failures and older bindings
  • --dry-run validates the delete without removing anything, on the backend or in the metadata.
  • If dropping a backend object fails, the whole delete is rolled back and can be retried. The drops are idempotent, so a partially completed delete retries cleanly.
  • Bindings created by OpenRun versions that did not record their created objects are deleted from the metadata only: a warning is logged and the backend objects are left in place for manual cleanup.

Attach Bindings to Apps

Attach existing bindings when creating an app:

openrun app create \
  --bind /apps/reporting-db \
  github.com/example/reporting-app \
  /reporting

Binding order is preserved. To update the binding list for an existing app:

openrun app update bindings /apps/reporting-read /apps/metrics-read /reporting

This updates staging. Add --promote to update prod in the same command.

Environment Variables

Each attached binding’s account is injected into the app container as environment variables named <SERVICE_TYPE>_<FIELD> (upper-cased), one variable per account field:

Service typeAccount fieldsExample variables
postgresurl, url_direct, schema, rolePOSTGRES_URL, POSTGRES_URL_DIRECT, POSTGRES_SCHEMA, POSTGRES_ROLE
mysqlurl, url_direct, database, user, hostMYSQL_URL, MYSQL_DATABASE, MYSQL_USER
redis/valkeyurl, url_direct, username, password, key_prefixREDIS_URL, REDIS_KEY_PREFIX (VALKEY_URL, … for the valkey type)
sqliteurl, db_path, dirSQLITE_URL, SQLITE_DB_PATH, SQLITE_DIR
  • Several bindings of one type: the second and later ones get a numeric suffix on the type, in binding order: POSTGRES_URL, POSTGRES2_URL, POSTGRES3_URL.
  • Which account: production apps receive the prod account; staging, preview and dev apps receive the staged account.
  • Providers: provider service types follow the same scheme with the account fields the provider defines.

Binding Access Control

Access to services and bindings is controlled through RBAC. The service:* and binding:* permissions are scoped by the grant’s service:<glob> / binding:<glob> target entries.

OperationPermission required
Attach a binding to an appbinding:use on that binding path, in addition to the app permission for the update itself
Attach an auto binding created from a service sourceservice:bind on the service (and on its linked staging service, when one is configured), in addition to the app permission for the update itself
Create a base bindingservice:bind on the service
binding run-commandbinding:run_command
binding show-accountbinding:reveal
service health / binding healthservice:read / binding:read
Make a service the default of its typeservice:update on the service it displaces

The creator of a service or binding holds the owner permissions (service:manage / binding:manage by default) on their own entries.

When RBAC is not enabled, management operations are restricted to the admin user, so no separate approval step applies to binding access.

Auto Bindings

When the value passed to --bind starts with /, OpenRun treats it as an existing binding path. When it does not start with /, OpenRun treats it as a service source and creates a base binding automatically if the binding does not already exist.

openrun app create \
  --bind postgres/main \
  --approve \
  github.com/example/reporting-app \
  /reporting

The generated binding is stored under:

/auto/<main-app-id>/<service-type>

For example, a Postgres auto binding is stored as /auto/app_prd_.../postgres. Duplicate service references in the same command resolve to one auto binding.

  • Reserved path: the /auto path is reserved for auto bindings. Users cannot create bindings under that path directly.
  • Owned by the app: auto bindings cannot be shared. They cannot be used as the source for a derived binding, and another app cannot attach them with --bind. Use a regular base binding when multiple apps or derived accounts need to share a schema or database.
  • Deleted with the app: deleting the app deletes its auto bindings along with it, dropping their backend account objects the same way as binding delete. For Postgres/MySQL auto bindings this drops the schema or database including its data. An auto binding that (from an older OpenRun version) still has derived bindings blocks the app delete until the derived bindings are deleted.

Binding config can be passed through the service source using ; followed by comma separated key=value entries. The params become the auto binding’s config, exactly like binding create --config:

openrun app create \
  --bind "sqlite;path=/mydata" \
  --approve \
  github.com/example/notes-app \
  /notes

This works for any service type. The config is used when the auto binding is first created; referencing an existing auto binding with a different config is an error (delete the auto binding to recreate it with new config).

Declarative Apply

Apply files can define bindings using the binding builtin.

apps.ace
binding("/apps/reporting-db", "postgres/main", config={"inherit_default": "false"})
binding("/apps/reporting-read", "/apps/reporting-db", grants=["read:*"])

app("/reporting", "github.com/example/reporting-app", bindings=["/apps/reporting-read"])

The builtin format is:

binding(path, source, grants=[], config={})
PropertyOptionalTypeDefaultNotes
pathFalsestringThe unique path for the binding
sourceFalsestringThe source for binding, service or based binding path
grantstruestring arrayThe permission grants for a derived binding
configtruedictThe config map

The source rules are the same as the CLI:

  • source="postgres/main" or source="postgres" creates a base binding.
  • source="/apps/reporting-db" creates a derived binding.
  • grants is valid only for derived bindings.
  • config is used only when the binding is first created.

openrun apply creates bindings even if the app glob does not match any apps. Existing binding sources and binding config cannot be changed.

For existing bindings, apply does a three-way merge for grants. Grant changes in the apply file are applied, and grant changes made using the CLI are preserved. Use --clobber to make the staged grants match the apply file.

openrun apply --reload=none apps.ace /reporting
openrun apply --promote --reload=none apps.ace /reporting

With --promote, apply promotes binding metadata after updating staged metadata.

PostgreSQL (Postgres) Service Bindings

PostgreSQL service bindings automatically create a schema and login role for each base binding.

KeyRequiredDescription
urlYesAdmin Postgres connection URL. The admin user must be able to create roles, create schemas, grant privileges and alter default privileges
binding_hostnameNoHostname to substitute into generated url account URLs; disable keeps url unchanged and skips automatic mapping. See Hostname Mapping Basics

For example:

openrun service create postgres/main \
  --config url=postgres://admin:secret@localhost:5432/appdb

Postgres bindings support one create-time binding config key:

KeyDefaultDescription
inherit_defaulttrueWhether the generated role is created with INHERIT rather than NOINHERIT

For example:

openrun binding create \
  --config inherit_default=false \
  postgres/main \
  /apps/reporting-db

If inherit_default is set to false, the generated role is created with NOINHERIT. This does not remove privileges granted to PUBLIC, which apply to every role. Review database-wide PUBLIC grants separately when configuring isolation; see the PostgreSQL GRANT documentation.

Base binding: OpenRun creates a schema and a login role, and sets the role’s default search_path to the binding schema. The generated account includes url (service URL with the generated username and password, hostname substituted as described in Hostname Mapping Basics) and url_direct (original service URL hostname). Containers receive both as POSTGRES_URL and POSTGRES_URL_DIRECT; binding run-command uses url_direct.

Derived binding: OpenRun creates a separate login role and uses the base binding schema. The derived role gets USAGE on the schema before grants are applied.

GrantPostgres effect
read:*SELECT on all current tables; default privileges are changed so future tables created by the base role are readable by the derived role
create:*CREATE on the schema
full:*All table privileges, all sequence privileges and CREATE on the schema. Default privileges are also updated for future tables and sequences
read:<table>, full:<table>Apply only to the specified table. If the table does not exist, the grant is skipped for that run and applied on the next update/apply run

MySQL Service Bindings

MySQL service bindings automatically create a database and user for each base binding.

KeyRequiredDescription
urlYesAdmin MySQL URL. The admin user must be able to create users, create databases, and grant and revoke privileges
host_patternNoHost part for generated MySQL users. Defaults to %
binding_hostnameNoHostname to substitute into generated url account URLs; disable keeps url unchanged and skips automatic mapping. See Hostname Mapping Basics

For example:

openrun service create mysql/main \
  --config url=mysql://admin:secret@localhost:3306/ \
  --config host_pattern=10.0.%

Base binding: OpenRun creates a database and user. The base user gets ALL PRIVILEGES on the generated database. The generated account includes url (hostname substituted as described in Hostname Mapping Basics) and url_direct (original service URL hostname). Containers receive both as MYSQL_URL and MYSQL_URL_DIRECT; binding run-command uses url_direct.

Derived binding: OpenRun creates a separate user and uses the base binding database. The derived user gets a minimal database-level SHOW VIEW grant so it can connect using the generated database as the default database.

GrantMySQL effect
read:*SELECT on the database. This applies to current and future tables
create:*CREATE, ALTER, INDEX, DROP, and REFERENCES on the database
full:*Read, write, create, alter, index, drop, references, trigger, create view, temporary table and lock privileges on the database
read:<table>, full:<table>Apply only to the specified table. If the table does not exist, the grant is skipped for that run and applied on the next update/apply run

MySQL DDL statements auto-commit. If binding creation fails part way through, OpenRun does best-effort cleanup for users and databases created during that operation.

Redis and Valkey Service Bindings

Redis service bindings automatically create a dedicated ACL user for each base binding, restricted to a unique key prefix with server-enforced ACLs. The same implementation serves the valkey service type; valkey:// and valkeys:// service URLs are normalized to redis:///rediss:// in generated account URLs. Redis 7 or newer (or any Valkey release) is required, running as a standalone server (cluster mode is not supported).

KeyRequiredDescription
urlYesAdmin Redis/Valkey connection URL (redis://, rediss://, valkey:// or valkeys://)
binding_hostnameNoHostname to substitute into generated url account URLs; disable keeps url unchanged and skips automatic mapping. See Hostname Mapping Basics

For example:

openrun service create redis/main \
  --config url=redis://admin:secret@localhost:6379

Unlike SQL databases, Redis has no schema to scope: isolation comes from a generated key prefix. The account exposes url, url_direct, username, password and key_prefix (as REDIS_URL, REDIS_KEY_PREFIX and so on in the app environment). Apps must prepend key_prefix to every key they use; access outside the prefix fails with a Redis NOPERM error, so a misconfigured app fails loudly instead of silently reading or clobbering another app’s keys. Production and staging accounts get separate ACL users and separate key prefixes.

Base binding: the user gets full access to its key prefix and to pub/sub channels under the same prefix. Administrative and cross-keyspace commands (CONFIG, ACL, FLUSHALL, KEYS, RANDOMKEY, PUBSUB introspection and similar) are denied for binding accounts; SCAN is allowed so apps can enumerate and clear their own keys.

Derived binding: OpenRun creates a separate ACL user that shares the base binding’s key prefix, with no access until grants are applied.

GrantRedis effect
read:*Server-enforced read-only access to all keys under the base prefix. Writes fail with NOPERM. Read grants include no pub/sub access
full:*Read-write access to all keys under the base prefix, plus pub/sub channels under the prefix
read:<target>, full:<target>Scope the grant to keys starting with <key_prefix><target>. Targets may use letters, digits and _ . : -; glob characters are rejected
create:*Not supported
ACL changes only modify the server’s in-memory state. Configure an aclfile on the Redis/Valkey server so binding users survive a server restart (OpenRun runs ACL SAVE after every change when an aclfile is configured, and logs a warning at service creation when none is). Without an aclfile, a derived user lost to a restart can be recreated with binding update --reapply-all; base users need the aclfile.

Deleting a binding deletes its ACL users (production and staging) but leaves keys under the binding’s prefix in place, unlike Postgres/MySQL where deleting a base binding drops the data. See Delete Bindings.

SQLite Config and Behavior

The sqlite service type has no external endpoint. A SQLite binding gives the app a persistent named volume (Docker/Podman) or PersistentVolumeClaim (Kubernetes) mounted into the app container, holding the app’s SQLite database files. Creating the service and binding needs no connection information:

openrun service create sqlite/main --is-default
openrun app create --bind sqlite --approve github.com/example/notes-app /notes

The app finds its database through environment variables:

SQLITE_URL=file:/data/data.db
SQLITE_DB_PATH=/data/data.db
SQLITE_DIR=/data
  • Volume lifecycle: the volume is created automatically when the app first starts and is reused across app updates and redeploys. The volume identity follows the binding, so attaching the binding to a different app later does not carry over another binding’s data.
  • Kubernetes: apps with a SQLite binding automatically run as a single replica with the Recreate deploy strategy, matching SQLite’s single-writer model.
  • Disaster recovery: enable continuous SQLite replication to S3 with Litestream. OpenRun continuously replicates the binding’s database files to S3-compatible storage and automatically restores them before the app starts after volume or node loss.

SQLite services support these config keys (all optional):

KeyDescription
litestream_configName of a [litestream.<name>] server config entry. Enables continuous replication to S3-compatible storage for bindings of this service
path_prefixOverrides the litestream config’s replica key prefix for bindings of this service
volume_sizeKubernetes PVC size (default kubernetes.default_volume_size, 10Gi). Ignored for Docker/Podman

SQLite bindings support these create-time binding config keys:

KeyDefaultDescription
path/dataAbsolute path where the volume is mounted in the container
pattern*.dbFile glob (relative to the binding directory) selecting which files are replicated when replication is enabled
openrun binding create --config path=/mydata sqlite/main /apps/notes-db
openrun binding create --config "pattern=*.sqlite3" sqlite/main /apps/notes-db

Apps can create additional database files under SQLITE_DIR (for example per-tenant databases); with replication enabled, every file matching the binding’s pattern (default *.db) in the directory is replicated. The default database file the binding’s environment variables point at is data.db, so a custom pattern should either match data.db or the app should use its own file names.

Differences from Postgres/MySQL bindings:

  • An app can have at most one SQLite binding, and a SQLite binding can be attached to only one app: the database is a single-writer file on a per-app volume.
  • Derived bindings and grants are not supported. SQLite has no accounts or roles to scope; bind the base binding directly.
  • binding run-command is not supported: the database file is only reachable inside the app container.
  • binding show-account shows the computed paths; there are no credentials.
  • SQLite bindings are not available for preview apps.
  • Deleting an app removes its managed Docker/Podman volumes or Kubernetes PVCs, including SQLite data volumes. Deleting a detached SQLite binding does not remove volumes or object-storage replicas: SQLite bindings have no backend accounts to drop. App deletion does not remove the replica, but recreating a deleted binding gives it a new identity and therefore a different replica location.

A staging service can be linked like any other service type. Staged apps then follow the staging service’s config: its own litestream_config (or none), path_prefix and volume_size, so staged data can replicate to a separate location or skip replication entirely.

WAL mode and volume permissions
  • WAL mode: for best results the app should open the database in WAL mode with a busy timeout, for example file:...?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000) (driver dependent). With replication enabled, WAL mode is required, but litestream enables it automatically if the app has not.
  • Volume permissions: OpenRun makes the volume writable for non-root app users automatically. With replication enabled, the chmod runs using the Litestream image, so any app image works. For local-only SQLite bindings (no litestream_config), the chmod runs with the app’s own image, so the app image must not be distroless.
  • Kubernetes: pods with a SQLite binding additionally get fsGroup: 65532, which makes the volume group-writable at mount time on storage classes with ownership management.

Binding Providers (SQL Server, Oracle, MongoDB, Snowflake, ClickHouse)

Beyond the built-in service types, OpenRun supports out-of-process binding providers: standalone executables from the openrundev/bindings repository that add more service types.

  • Microsoft SQL Server: schema-based isolation, SQL Server 2019+.
  • Oracle Database: pure-Go driver, no Oracle client needed.
  • MongoDB: self-hosted servers and MongoDB Atlas, via the mongodb and atlas service types.
  • Snowflake: role/schema isolation with key-pair authentication.
  • ClickHouse: self-hosted and ClickHouse Cloud.
  • Databricks: SQL warehouses with Unity Catalog schema isolation. Databricks Lakebase needs no provider: it speaks the Postgres protocol and works with the built-in postgres binding.
License: The OpenRun server and the built-in service types (Postgres, MySQL, SQLite, Redis and Valkey) are Apache 2.0 licensed. The binding providers listed above are separate downloads and are not Apache 2.0 licensed. They are under the PolyForm Free Trial License 1.0.0, which permits evaluation use for less than 32 consecutive days. Use beyond the evaluation period requires a commercial license, email contact@openrun.dev.

Install a provider by name and version; the binary is downloaded from the provider releases (or a configured mirror), checksum-verified and registered:

openrun provider install sqlserver --version v0.1.0
openrun provider list
FlagEffect
--versionProvider version to install; required when no --source-url is given
--sha256 <hex>[,<hex>]Pins the accepted binary digests (one per platform for mixed-architecture deployments) and fails the install on a mismatch
--source-urlInstalls from another URL (with {version}, {os} and {arch} placeholders) or from a server-local file path

The provider’s service types then work exactly like the built-in ones:

openrun service create sqlserver/main \
  --config url=sqlserver://admin:secret@db.example.com:1433
openrun binding create sqlserver/main /apps/reporting-db
  • Lifecycle: provider processes are launched on demand when a service connection is needed and stopped when it is closed.
  • Uninstall: openrun provider uninstall <name> removes a provider once no services of its types exist (--force removes it regardless).
  • Declarative installs: for config-managed deployments, providers can instead be declared in the [bindings.install] server config section (or the equivalent Helm values / Terraform variables for Kubernetes), with optional @sha256:<hex> digest pinning.
  • Provider details: per-provider configuration (service config keys, grant semantics) is documented in the bindings repository.

The [bindings] server config section controls how providers are installed:

KeyDefaultDescription
cache_dir$OPENRUN_HOME/bindingsNode-local cache where installed provider executables are materialized
release_url_templateopenrundev/bindings GitHub releasesDownload URL used when no --source-url is given; {provider}, {version}, {os}, {arch} and {ext} (.exe on Windows) are replaced. Point it at a mirror for restricted networks
install[bindings.install] table of name = "version" (or "version@sha256:<hex>[,<hex>]") entries installed at server startup. Providers listed here cannot be changed with the provider CLI; removing an entry does not uninstall the provider
unsafe_allow_httpfalseAllow plain http:// provider source URLs. Not recommended: the downloaded binaries run as the server user
preinstalled_dirDirectory of pre-placed openrun-binding-<name> executables, registered at startup without downloads or database registration (used by the Kubernetes OCI image path)
disable_installfalseReject the imperative provider install/uninstall API/CLI; providers come only from install or preinstalled_dir
dev_providers[bindings.dev_providers.<name>] with path = "/path/to/executable" registers a provider from a local path, skipping checksum verification. Development use only

Frequently Asked Questions

How do I connect a web app to PostgreSQL with OpenRun?

Create a PostgreSQL service with an administrator connection URL, then create or automatically attach a binding from that service. OpenRun creates an isolated schema and login role and supplies the generated PostgreSQL connection information to the app environment.

How do MySQL service bindings work?

Create a MySQL service that points to an existing managed or self-hosted MySQL server. For each base binding, OpenRun creates a dedicated database and user, then makes the generated connection URL available to the application.

Does each app get a separate PostgreSQL schema or MySQL database?

Yes. A PostgreSQL base binding owns its own schema and role, while a MySQL base binding owns its own database and user. Staging and production also use separate accounts and separate schemas or databases.

Can multiple apps securely share a PostgreSQL schema or MySQL database?

Yes. Derived bindings create a separate role or user for each app while sharing the base binding’s schema or database. Grants can provide read-only, table-specific, create or full access without sharing credentials between apps.

How do Redis service bindings keep apps isolated?

Each base binding gets a dedicated Redis ACL user restricted to a unique key prefix (and matching pub/sub channel prefix), enforced by the server: any access outside the prefix fails with NOPERM. Derived bindings share the base prefix with separate ACL users whose access is controlled by grants. Redis 7+ or Valkey is required.

Can OpenRun provision SQL Server, Oracle, MongoDB, Snowflake or ClickHouse access?

Yes. Install the matching binding provider with openrun provider install <name> and the provider’s service types (sqlserver, oracle, mongodb/atlas, snowflake, clickhouse, databricks) become available for service create, with the same binding, grant and staging workflow as the built-in types. The providers are under the PolyForm Free Trial License, see binding providers for the license terms.

Are database administrator credentials exposed to applications?

No. OpenRun uses the administrator URL to provision and manage binding accounts, but applications receive only their generated binding credentials. The administrator URL can reference OpenRun’s supported secret providers instead of being stored directly.