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:
- Concepts: services, base bindings, derived bindings, staging and prod accounts.
- Managing services, bindings, grants and attaching bindings to apps.
- Per-backend behavior for PostgreSQL, MySQL, Redis/Valkey and SQLite.
- Binding providers for additional databases.
The service types compiled into the server are:
| Service type | Purpose |
|---|---|
postgres | Create Postgres schemas and roles |
mysql | Create MySQL databases and users |
sqlite | Provide a persistent volume with SQLite database files per app |
redis | Create Redis ACL users isolated by key prefix (Redis 7+) |
valkey | Valkey servers, same ACL-based implementation as redis |
Additional service types come from out-of-process binding providers, installed with openrun provider install:
| Provider | Service types | Purpose |
|---|---|---|
sqlserver | sqlserver | Create SQL Server schemas and users (SQL Server 2019+) |
oracle | oracle | Create Oracle users and schemas (pure-Go driver) |
mongodb | mongodb, atlas | Create MongoDB databases and users, self-hosted or Atlas |
snowflake | snowflake | Create Snowflake roles and schemas with key-pair accounts |
clickhouse | clickhouse | Create ClickHouse users, self-hosted or ClickHouse Cloud |
databricks | databricks | Databricks 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
| Term | Meaning |
|---|---|
| Service | An admin connection to an endpoint (database). Apps do not use this connection directly; OpenRun uses it to create database users and apply grants |
| Base Binding | Created 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 Binding | Created 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 |
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 --promotepromotes 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-dbSecret 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/mainUpdate service default status with:
openrun service update postgres/main --set-default=trueService 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/appdbDelete 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 field | Hostname | Used by |
|---|---|---|
url | Service URL hostname, replaced by the service config key binding_hostname when it is set | App containers |
url_direct | Original service URL hostname | OpenRun 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.internalfor Docker,host.containers.internalfor other local container runtimes. - Set
binding_hostnameexplicitly to override that value. - Set
binding_hostname=disableto 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/appdbYou 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-dbBase 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-dbWith 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-adminDerived 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.
| Grant | Meaning |
|---|---|
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-readProd is not updated until the binding is promoted:
openrun binding update --promote /apps/reporting-readYou can update and promote in one command:
openrun binding update \
--add-grant "read:*" \
--delete-grant "read:old_table" \
--promote \
/apps/reporting-readUse --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-readapp 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-dbservice healthconnects with the service’s admin credentials (secret references resolved the same way as other operations).binding healthconnects 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 healthrequiresservice:readon the service andbinding healthrequiresbinding:readon the binding path.
Delete Bindings
openrun binding delete /apps/reporting-read
openrun binding delete --dry-run /apps/reporting-dbDeleting 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:
| Backend | Base binding delete | Derived binding delete |
|---|---|---|
| Postgres | The binding’s role and schema are dropped, including everything in the schema (CASCADE) and any objects the role still owns elsewhere | Only that binding’s role is dropped (plus objects it still owns, such as tables it created in the shared schema) |
| MySQL | The binding’s user and database are dropped, including the database contents | Only that binding’s user is dropped (plus objects it still owns) |
| Redis/Valkey | The 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 too | The derived ACL users are removed |
| SQLite | The volume and any replicated data are kept (details) | Not applicable |
| Providers | Provider service types drop the users/schemas/databases the binding created, per the provider’s documentation | Per the provider’s documentation |
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-runvalidates 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 \
/reportingBinding order is preserved. To update the binding list for an existing app:
openrun app update bindings /apps/reporting-read /apps/metrics-read /reportingThis 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 type | Account fields | Example variables |
|---|---|---|
postgres | url, url_direct, schema, role | POSTGRES_URL, POSTGRES_URL_DIRECT, POSTGRES_SCHEMA, POSTGRES_ROLE |
mysql | url, url_direct, database, user, host | MYSQL_URL, MYSQL_DATABASE, MYSQL_USER |
redis/valkey | url, url_direct, username, password, key_prefix | REDIS_URL, REDIS_KEY_PREFIX (VALKEY_URL, … for the valkey type) |
sqlite | url, db_path, dir | SQLITE_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.
| Operation | Permission required |
|---|---|
| Attach a binding to an app | binding:use on that binding path, in addition to the app permission for the update itself |
| Attach an auto binding created from a service source | service: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 binding | service:bind on the service |
binding run-command | binding:run_command |
binding show-account | binding:reveal |
service health / binding health | service:read / binding:read |
| Make a service the default of its type | service: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 \
/reportingThe 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
/autopath 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 \
/notesThis 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.
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={})| Property | Optional | Type | Default | Notes |
|---|---|---|---|---|
| path | False | string | The unique path for the binding | |
| source | False | string | The source for binding, service or based binding path | |
| grants | true | string array | The permission grants for a derived binding | |
| config | true | dict | The config map |
The source rules are the same as the CLI:
source="postgres/main"orsource="postgres"creates a base binding.source="/apps/reporting-db"creates a derived binding.grantsis valid only for derived bindings.configis 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 /reportingWith --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.
| Key | Required | Description |
|---|---|---|
url | Yes | Admin Postgres connection URL. The admin user must be able to create roles, create schemas, grant privileges and alter default privileges |
binding_hostname | No | Hostname 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/appdbPostgres bindings support one create-time binding config key:
| Key | Default | Description |
|---|---|---|
inherit_default | true | Whether the generated role is created with INHERIT rather than NOINHERIT |
For example:
openrun binding create \
--config inherit_default=false \
postgres/main \
/apps/reporting-dbIf 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.
| Grant | Postgres 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.
| Key | Required | Description |
|---|---|---|
url | Yes | Admin MySQL URL. The admin user must be able to create users, create databases, and grant and revoke privileges |
host_pattern | No | Host part for generated MySQL users. Defaults to % |
binding_hostname | No | Hostname 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.
| Grant | MySQL 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).
| Key | Required | Description |
|---|---|---|
url | Yes | Admin Redis/Valkey connection URL (redis://, rediss://, valkey:// or valkeys://) |
binding_hostname | No | Hostname 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:6379Unlike 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.
| Grant | Redis 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 |
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 /notesThe 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
Recreatedeploy 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):
| Key | Description |
|---|---|
litestream_config | Name of a [litestream.<name>] server config entry. Enables continuous replication to S3-compatible storage for bindings of this service |
path_prefix | Overrides the litestream config’s replica key prefix for bindings of this service |
volume_size | Kubernetes PVC size (default kubernetes.default_volume_size, 10Gi). Ignored for Docker/Podman |
SQLite bindings support these create-time binding config keys:
| Key | Default | Description |
|---|---|---|
path | /data | Absolute path where the volume is mounted in the container |
pattern | *.db | File 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-dbApps 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-commandis not supported: the database file is only reachable inside the app container.binding show-accountshows 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
chmodruns using the Litestream image, so any app image works. For local-only SQLite bindings (nolitestream_config), thechmodruns 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
mongodbandatlasservice 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
postgresbinding.
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| Flag | Effect |
|---|---|
--version | Provider 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-url | Installs 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 (--forceremoves 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:
| Key | Default | Description |
|---|---|---|
cache_dir | $OPENRUN_HOME/bindings | Node-local cache where installed provider executables are materialized |
release_url_template | openrundev/bindings GitHub releases | Download 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_http | false | Allow plain http:// provider source URLs. Not recommended: the downloaded binaries run as the server user |
preinstalled_dir | Directory of pre-placed openrun-binding-<name> executables, registered at startup without downloads or database registration (used by the Kubernetes OCI image path) | |
disable_install | false | Reject 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.