dev.env.example

# OSDU Delivery: what a local run needs, in the form of .sqlflow/env, the file dev.bat (Windows) and ./dev.sh (macOS,
# Linux) run the control plane, the GUI and the sqlflow command line with.
#
# You do not need to edit this file. On the first start, dev.bat or ./dev.sh asks for what it cannot know (the SQL
# Server, the OSDU platform and its client, a flow repository), writes .sqlflow/env from this template, creates the
# databases and registers the partition ('sqlflow dev setup'). Then, at every start, it says what is set and what is
# missing, with the fix for each, and stops only when a start would fail ('sqlflow dev check').
#   dev.bat setup / ./dev.sh setup    ask the questions again, offering the current values
#   dev.bat check / ./dev.sh check    the check alone, with a test sign-in to OSDU; changes nothing
# To set up by hand instead, copy this file to .sqlflow/env and replace every value written as <...>.
#
# .sqlflow/env is git-ignored and stays on this machine: it holds this machine's values, secrets included. Never copy a
# value from it into this file, a flow, a mapping, a commit or a chat.
#
# Format: NAME=value, one per line; a line that starts with # is a comment. The value is everything after the first =,
# spaces and ; included, so a connection string needs no quotes. A name is letters, digits and _ only; a setting of the
# control plane's configuration spells each : as __ (ControlPlane:Jwt:SigningKey is ControlPlane__Jwt__SigningKey).
#
# The sections say what each setting is needed for, which is what the check reports against. A section's title starts
# with "===== Needed to start", "===== Needed to run flows" or "===== Optional"; keep those words when editing.

# ===== Needed to start: dev.bat and ./dev.sh stop until each of these is set =====

# The catalog database: SQLFlow's metadata (schema catalog) and the module's ledger, mappings, templates, caches and
# partitions (schema osdu). The setup creates it on request ('sqlflow db migrate --create'); after that, every start applies
# its pending migrations. The client encrypts by default, so a server on this machine (whose certificate is self-signed)
# needs TrustServerCertificate=True. On macOS and Linux, sign in with a SQL login (User ID=...;Password=...): Windows
# authentication needs Windows.
SQLFLOW_CATALOG_DB=Server=localhost;Database=OsduDelivery;Integrated Security=True;TrustServerCertificate=True

# Signs the control plane's session tokens: at least 32 characters, made for this machine alone. The setup generates it,
# and so does a start for a file copied from here; never use a deployed estate's key.
ControlPlane__Jwt__SigningKey=<generated>

# The GUI's origin (Vite, on port 5173). The allowlist is empty by default, and empty means every GUI call fails with a
# CORS error.
ControlPlane__Cors__AllowedOrigins__0=http://localhost:5173

# The first admin, created at start when the catalog has no user of that name. An existing user's password is never
# reset, so changing the password here after the first start changes nothing; change it on the GUI's Users page instead.
# At least 12 characters. The setup generates it (or takes yours); sign in with the value of SQLFLOW_ADMIN_PASSWORD.
# A catalog that already has users needs none of the three.
ControlPlane__Bootstrap__AdminUsername=admin
ControlPlane__Bootstrap__AdminPasswordReference=${env:SQLFLOW_ADMIN_PASSWORD}
SQLFLOW_ADMIN_PASSWORD=<generated>

# ===== Needed to run flows: dev.bat and ./dev.sh start without them; a run that needs one fails until it is set =====

# The data database: the pre-ingestion flows land the source files here, the ingestion flows load the keyed tables, and
# the delivery flows read them, each in a schema of its own. Flows name it in three-part names (OsduData.silver.Wellbore),
# so keep its name. A delivery reads under snapshot isolation, so the database allows it (the setup creates it so):
# ALTER DATABASE [OsduData] SET ALLOW_SNAPSHOT_ISOLATION ON;
OSDU_DATA_DB=Server=localhost;Database=OsduData;Integrated Security=True;TrustServerCertificate=True

# The OSDU platform the flows deliver to, and the partition (data-partition-id) they deliver in. The setup registers the
# partition in the catalog ('sqlflow partition add'): cache, dimension and assertion flows work only in a registered
# partition, and the control plane reports itself not ready until one is.
OSDU_URL=<the platform's base URL, such as https://<instance>.energy.azure.com>
OSDU_DATA_PARTITION=<the data-partition-id, such as dev>

# The OAuth2 client the flows sign in with (client credentials): the token endpoint, the scope the token is asked for, and
# the client's id and secret. On Azure Data Manager for Energy the token URL is
# https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token and the scope https://energy.azure.com/.default.
OSDU_TOKEN_URL=<the token endpoint, such as https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token>
OSDU_SCOPE=<the scope, such as https://energy.azure.com/.default>
OSDU_CLIENT_ID=<the client's application id>
OSDU_CLIENT_SECRET=<the client's secret>

# Who owns and may read what the flows deliver, and the legal tag the records carry: what a record's acl.owners,
# acl.viewers and legal.legaltags default to when a flow sets no value. The groups and the tag must exist in the
# partition. On Azure Data Manager for Energy a group is <group>@<partition>.dataservices.energy.
OSDU_ACL_OWNER=<the owners group, such as data.default.owners@dev.dataservices.energy>
OSDU_ACL_VIEWER=<the viewers group, such as data.default.viewers@dev.dataservices.energy>
OSDU_LEGAL_TAG=<a legal tag the partition holds>

# ===== Optional: each has a default; set it to change what this machine does =====

# The Entra tenant of the OSDU client. Nothing reads it: the setup builds OSDU_TOKEN_URL from it and keeps it here.
# OSDU_TENANT_ID=<tenant id>

# A flow repository the control plane registers at start and keeps synced: a folder on this machine, read live (its
# uncommitted edits included), or a git remote cloned and pulled every SyncIntervalSeconds (300 by default). Without one,
# register repositories on the GUI's Repositories page. Replace <name> with the repository's name (letters, digits and _
# here); set LocalPath or RemoteUrl, not both. A private remote names its token as a reference: the token itself goes in
# SQLFLOW_GIT_TOKEN, with the user name the provider expects (x-access-token on GitHub, x-bitbucket-api-token-auth on
# Bitbucket).
# ControlPlane__Bootstrap__Repositories__<name>__LocalPath=<C:\path\to\the\repository or /path/to/the/repository>
# ControlPlane__Bootstrap__Repositories__<name>__RemoteUrl=<https://github.com/<org>/<repository>.git>
# ControlPlane__Bootstrap__Repositories__<name>__Branch=main
# ControlPlane__Bootstrap__Repositories__<name>__CredentialReference=${env:SQLFLOW_GIT_TOKEN}
# ControlPlane__Bootstrap__Repositories__<name>__CredentialUsername=<user name>
# Sync only when an external trigger or Sync now asks, holding the commit until then (unset: an admin decides):
# ControlPlane__Bootstrap__Repositories__<name>__AutoSync=false
# SQLFLOW_GIT_TOKEN=<token>
# A private GitHub repository is best read with a GitHub App instead: read-only, installed on the repository, owned by the
# organization rather than a person (sqlflow/docs/reference/guides/github-app.md). A repository naming no
# CredentialReference is then read with a token the App mints for it alone; the key stays in its .pem file.
# SQLFLOW_GITHUB_APP_ID=<the App's client ID>
# SQLFLOW_GITHUB_APP_PRIVATE_KEY_PATH=<C:\path\to\the-app.private-key.pem or /path/to/the-app.private-key.pem>

# Migrations and provisioning. Every start applies pending migrations itself ('sqlflow db migrate') before the control
# plane starts, so the control plane does not, and an F5 start never changes the database on its own. Keep both false when
# the catalog is shared with a deployed estate: applying a migration its containers do not know yet breaks them.
ControlPlane__Bootstrap__ApplyMigrations=false
ControlPlane__Bootstrap__AllowCreate=false

# The control plane's catalog when it should differ from the command line's. Defaults to ${env:SQLFLOW_CATALOG_DB}.
# ControlPlane__Catalog__ConnectionReference=${env:SQLFLOW_CATALOG_DB}

# The control plane's own node. dev.bat and ./dev.sh start managed workers instead and set this to false for that start;
# 'single' (and F5) keep it, so the control plane runs flows itself (true, the default).
# ControlPlane__Worker__Enabled=true

# The managed sync: the control plane syncs its repositories on their intervals (true, the default). Turn it off when the
# catalog is shared with a deployed estate, or this machine syncs that estate's repositories with its own files.
# ControlPlane__ManagedSync__Enabled=true

# Azure: ${keyvault:...} references and Azure storage are read through your 'az login'. Set it when a flow or this file
# names a Key Vault secret or an Azure storage location; a start then signs you in when you are not.
# SQLFLOW_AZURE_AUTH=cli

# Sign in with Microsoft on the GUI, beside the user name and password: a single-tenant SPA registration whose redirect
# URI is http://localhost:5173. Its first sign-in creates the user, as a viewer.
# ControlPlane__AzureAd__AllowedTenantIds__0=<tenant id>
# ControlPlane__AzureAd__ClientId=<the SPA registration's application id>

# ! questions in the assistant: read-only queries over the AI contexts an admin approved.
# ControlPlane__AiContext__Enabled=true

# The local demo ('dev.bat demo', './dev.sh demo'), which writes these itself: the sample estates' database and the groups
# their curated reference data carries, and a stand-in for OSDU on this machine (osdu/gui/standin), which the launchers
# start when OSDU_STANDIN_WRITES is true and a delivery may reach because SQLFLOW_DELIVERY_ALLOW_LOOPBACK is. Never set
# either beside a real OSDU.
# SQLFLOW_DEMO_DB=Server=localhost;Database=SqlFlowDemo;Integrated Security=True;TrustServerCertificate=True
# OSDU_LOGTYPE_ACL_OWNER=<the owners group of the curated reference data>
# OSDU_LOGTYPE_ACL_VIEWER=<the viewers group of the curated reference data>
# OSDU_STANDIN_WRITES=true
# SQLFLOW_NODE_CACHE=<.sqlflow\node-cache in this checkout, so its checkouts and run history are its own>
# SQLFLOW_DELIVERY_ALLOW_LOOPBACK=true
# ControlPlane__RateLimit__PermitPerWindow=6000

# Managed workers (what dev.bat and ./dev.sh start unless told 'single'): how many worker processes the control plane may
# start (4 by default). Any other ControlPlane__ManagedWorkers__* setting applies as well.
# ControlPlane__ManagedWorkers__MaxWorkers=4

# The database the SQLFlow test suites migrate and seed. Never one that holds real data. The OSDU suites use
# OsduDeliveryTests on localhost without it.
# SQLFLOW_TEST_DB=Server=localhost;Database=OsduDeliveryTests;Integrated Security=True;TrustServerCertificate=True