deltabase deploy

Deploy event stores and subscriptions from a deltabase.config.ts file.

Usage

deltabase deploy [options]

Or without global installation:

pnpx @delta-base/cli deploy [options]

---

Options

Option	Description	Default
--config <path>	Path to config file	deltabase.config.ts
--api-key <key>	DeltaBase API key	$DELTABASE_API_KEY
--api-url <url>	API URL	https://api.delta-base.com
--dry-run	Preview changes without applying	false
--verbose	Show detailed output	false

---

Examples

Basic Deployment

pnpx @delta-base/cli deploy --api-key your-api-key

With Environment Variable

export DELTABASE_API_KEY=your-api-key
pnpx @delta-base/cli deploy

Custom Config File

pnpx @delta-base/cli deploy --config ./config/production.ts

Dry Run (Preview)

pnpx @delta-base/cli deploy --dry-run --api-key your-api-key

Verbose Output

pnpx @delta-base/cli deploy --verbose --api-key your-api-key

---

Configuration File

The deploy command reads from deltabase.config.ts:

import type { InfrastructureConfig as DeltaBaseConfig } from '@delta-base/server';

const config: DeltaBaseConfig = {
  eventStores: [
    {
      name: 'my-service-events',
      description: 'Events for my service',
      settings: {
        retentionPeriodDays: 365,
        maxStreamSizeBytes: 1073741824,  // 1GB
      },
      subscriptions: [
        {
          id: 'users-projection',
          eventFilter: ['user.created', 'user.updated', 'user.deleted'],
          subscriberType: 'webhook',
          webhook: {
            url: process.env.WEBHOOK_URL || 'https://my-app.com/webhooks',
            headers: {
              Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
            },
            retryPolicy: {
              maxAttempts: 5,
              backoffMinutes: 2,
            },
          },
        },
      ],
    },
  ],
};

export default config;

---

Reconciliation

The deploy command performs reconciliation - comparing your config to the current state and making only necessary changes.

Event Stores

Scenario	Action
In config, doesn’t exist	Create
In config, exists with different settings	Update
In config, matches current state	No change

Subscriptions

Scenario	Action
In config, doesn’t exist	Create
In config, exists with different settings	Update
Exists but not in config	Delete
In config, matches current state	No change

Warning: Subscriptions not in your config file will be deleted. This ensures your config is the single source of truth.

---

Output

Successful Deployment

Deploying DeltaBase infrastructure...

Event Stores:
  ✓ my-service-events (created)

Subscriptions:
  ✓ users-projection (created)

Deployment complete!

Dry Run Output

DRY RUN - No changes will be applied

Event Stores:
  + my-service-events (would create)

Subscriptions:
  + users-projection (would create)

Run without --dry-run to apply changes.

---

Authentication

API Key Methods

1. Command line flag:

pnpx @delta-base/cli deploy --api-key your-api-key

2. Environment variable:

export DELTABASE_API_KEY=your-api-key
pnpx @delta-base/cli deploy

3. .env file:

.env

DELTABASE_API_KEY=your-api-key

source .env && pnpx @delta-base/cli deploy

---

CI/CD Integration

GitHub Actions

name: Deploy Infrastructure

on:
  push:
    branches: [main]
    paths:
      - 'deltabase.config.ts'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Deploy DeltaBase
        run: pnpx @delta-base/cli deploy
        env:
          DELTABASE_API_KEY: ${{ secrets.DELTABASE_API_KEY }}
          WEBHOOK_URL: ${{ vars.WEBHOOK_URL }}
          WEBHOOK_TOKEN: ${{ secrets.WEBHOOK_TOKEN }}

GitLab CI

deploy:
  stage: deploy
  image: node:20
  script:
    - npx @delta-base/cli deploy
  only:
    - main
  variables:
    DELTABASE_API_KEY: $DELTABASE_API_KEY

---

Error Handling

Common Errors

“Configuration not found”

Error: Could not find deltabase.config.ts

Ensure the file exists or use --config to specify the path.

“Authentication failed”

Error: Invalid API key

Check your API key is correct and has the necessary permissions.

“Validation error”

Error: Event store name must be 3-63 characters

Fix the validation error in your config file.

Exit Codes

Code	Meaning
0	Success
1	Error

---

Best Practices

1. Use Dry Run First

Always preview changes before applying:

pnpx @delta-base/cli deploy --dry-run

2. Version Control Your Config

Treat deltabase.config.ts like any infrastructure code:

git add deltabase.config.ts
git commit -m "Add users projection subscription"

3. Use Environment Variables for Secrets

// Good
headers: {
  Authorization: `Bearer ${process.env.WEBHOOK_TOKEN}`,
}

// Bad - never commit secrets
headers: {
  Authorization: 'Bearer actual-secret-token',
}

4. Separate Configs per Environment

# Development
pnpx @delta-base/cli deploy --config config/development.ts

# Production
pnpx @delta-base/cli deploy --config config/production.ts

---

What’s Next?

• Infrastructure as Code Guide - Detailed configuration guide
• Deploy to Production - Full deployment walkthrough
• dev command - Local development