Configuration

Secrets

Secrets let you pass sensitive values (API keys, tokens, connection strings) to functions without embedding them in code.

Create a secret

# From stdin (recommended for CI/CD)
echo -n "sk-abc123" | db9 functions secrets set MY_API_KEY --db myapp --value-stdin

# Inline (visible in shell history — not recommended)
db9 functions secrets set MY_API_KEY --db myapp --value "sk-abc123"

Bind secrets to a function

The --secret flag maps an alias (used in your code) to a secret name (stored in the database):

db9 functions create my-func --db myapp -f index.js \
  --secret API_KEY=MY_API_KEY \
  --secret DB_TOKEN=external_db_token

Access secrets in code

module.exports = {
  handler: async (input, ctx) => {
    const apiKey = ctx.secrets.get("API_KEY");

    const response = await fetch("https://api.example.com/data", {
      headers: { "Authorization": `Bearer ${apiKey}` },
    });

    return await response.json();
  }
};

Manage secrets

# List secrets (names only — values are never shown)
db9 functions secrets list --db myapp

# Update (set uses create-or-update semantics)
db9 functions secrets set MY_API_KEY --db myapp --value "new-value"

# Delete
db9 functions secrets delete MY_API_KEY --db myapp

Filesystem Access (fs9)

Functions can read and write files in the database’s filesystem. Access is controlled by --fs9-scope flags at deploy time:

db9 functions create my-func --db myapp -f index.js \
  --fs9-scope /data:ro \
  --fs9-scope /output:rw

Mode	Description
`ro`	Read-only access to the path and its children
`rw`	Read-write access to the path and its children

The --fs9-scope flags declare which paths your function intends to access and whether access is read-only or read-write. Currently, ctx.fs9 calls succeed even without --fs9-scope, but you should always declare scopes explicitly — enforcement may be enabled in a future release.

Reading files

// Read as UTF-8 string
const text = await ctx.fs9.read("/data/config.json");
const config = JSON.parse(text);

// Read as base64 (for binary files like images, xlsx)
const base64 = await ctx.fs9.readBase64("/data/image.png");
const buffer = Buffer.from(base64, "base64");

Writing files

await ctx.fs9.write("/output/report.csv", csvContent);
await ctx.fs9.write("/output/data.json", JSON.stringify(results, null, 2));

Listing and inspecting

const entries = await ctx.fs9.list("/data/");
// Returns: [{ path, type, size, mtime, ... }, ...]

const stat = await ctx.fs9.stat("/data/file.txt");
// Returns: { path, type: "file", size: 1024, mtime: "2026-04-01T...",
//            generation: 1, mode: 420, sealed: false, storage: "inline" }

Deleting

await ctx.fs9.delete("/output/old-report.csv");

Network Access (fetch)

Functions have access to the global fetch() API for outbound HTTP requests. Network access is blocked by default — only URLs on the allowlist can be reached.

module.exports = {
  handler: async (input, ctx) => {
    const response = await fetch("https://api.example.com/data", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query: input.query }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }
};

If a URL is not in the allowlist, fetch() throws with:

EACCES: permission denied, connect 'https://...': url not in allowlist

Cron Scheduling

Functions can be invoked on a schedule using pg_cron. This is useful for periodic data cleanup, report generation, and automated maintenance.

Schedule via SQL

Use cron.schedule() to invoke a function on a recurring schedule:

SELECT cron.schedule(
  'nightly-cleanup',
  '0 3 * * *',
  $$SELECT extensions.http_post(
    'https://api.db9.ai/customer/databases/{db_id}/functions/{function_id}/invoke',
    '{"input": {}}',
    'application/json',
    ARRAY[ARRAY['Authorization', 'Bearer ' || current_setting('app.api_token')]]
  )$$
);

Cron expression format

Expression	Meaning
`/5 * * *`	Every 5 minutes
`0 * * * *`	Every hour
`0 3 * * *`	Daily at 3:00 AM UTC
`0 0 * * 0`	Weekly on Sunday at midnight
`0 12 1 * *`	Monthly on the 1st at noon

See Scheduled Jobs with pg_cron for the complete scheduling guide.

Versioning

Every db9 functions update creates a new version. The active version is updated immediately — there is no staged deployment.

# Deploy version 1
db9 functions create my-func --db myapp -f v1.js

# Deploy version 2 (replaces version 1 immediately)
db9 functions update my-func --db myapp -f v2.js

Each run record stores the version_id that was used, so you can trace which version produced a given result:

db9 functions history my-func --db myapp -n 5 --json

There is currently no built-in rollback command. To revert, re-deploy the previous version’s code:

db9 functions update my-func --db myapp -f previous-version.js

Execution Limits

Limit	Default	Max	Description
`timeout_ms`	30,000 (30s)	300,000 (5 min)	Maximum execution time
`memory_mb`	System default	—	Memory limit
`max_db_queries`	System default	—	SQL queries per invocation
`max_db_rows`	System default	—	Total rows returned across queries
`max_outbound_requests`	System default	—	Outbound HTTP requests
`max_response_bytes`	System default	—	Max size per HTTP response
`network_timeout_ms`	System default	—	Per-request network timeout
`max_fs9_requests`	System default	—	fs9 API calls per invocation
`max_fs9_read_bytes`	System default	—	Total bytes read from fs9
`max_fs9_write_bytes`	System default	—	Total bytes written to fs9

Set limits via flags or JSON:

# Convenience flag (timeout only)
db9 functions create my-func --db myapp -f index.js --timeout 60000

# Full limits JSON
db9 functions create my-func --db myapp -f index.js \
  --limits-json '{"timeout_ms":60000,"memory_mb":256,"max_db_queries":100}'

# From file
db9 functions create my-func --db myapp -f index.js \
  --limits-file ./limits.json

Visibility

Functions have a visibility field that defaults to private. This controls whether the function can be invoked via a publishable key (public endpoint) without authentication.

Next Steps

Overview — Quick start and deployment basics
Runtime & ctx — ctx.db, ctx.fs9, ctx.self API
Examples — Real-world patterns
Troubleshooting — Errors, logs, debugging