Basins are the top-level organizational unit in S2. Each basin contains streams and has configurable defaults for stream creation.
List basins
List all basins in your account:
Output:
my-basin active
prod-data active
test-basin creating
Filter by prefix
s2 list-basins --prefix "prod"
s2 list-basins --limit 50
s2 list-basins --start-after "my-basin"
s2 list-basins --limit 100 --no-auto-paginate
Using the ls shortcut
The ls command lists basins when no argument is provided:
Create a basin
Create a new basin with default settings:
Output:
Set default stream configuration for auto-created streams:
s2 create-basin my-basin \
--storage-class express \
--retention-policy 7d \
--timestamping-mode client-require
Enable stream auto-creation
Allow streams to be created automatically on append or read:
s2 create-basin my-basin \
--create-stream-on-append \
--create-stream-on-read
Get basin configuration
View the current configuration of a basin:
s2 get-basin-config my-basin
┌───────────────────────────────┬─────────────────────────┐
│ default_stream_config │ │
├───────────────────────────────┼─────────────────────────┤
│ storage_class │ express │
│ retention_policy │ 604800 │
│ timestamping │ ... │
│ create_stream_on_append │ true │
│ create_stream_on_read │ false │
└───────────────────────────────┴─────────────────────────┘
s2 reconfigure-basin my-basin \
--create-stream-on-append true \
--storage-class standard
Available reconfiguration options
--create-stream-on-append - Auto-create streams on append (true/false)--create-stream-on-read - Auto-create streams on read (true/false)--storage-class - Default storage class (standard, express)--retention-policy - Default retention (e.g., 7d, 30d, infinite)--timestamping-mode - Timestamping mode (client-prefer, client-require, arrival)--timestamping-uncapped - Allow uncapped timestamps (true/false)--delete-on-empty-min-age - Minimum age before deleting empty streams (e.g., 1d)
Delete a basin
Deleting a basin is irreversible and will delete all streams and records within it.
✓ Basin deletion requested
deleting state and is eventually removed.
Basin states
Basins can be in one of three states:
- active - Basin is ready for use
- creating - Basin is being provisioned
- deleting - Basin is being deleted
Only basins in the active state can be used for stream operations.
Common workflows
Create a production basin with strict settings
s2 create-basin prod \
--storage-class express \
--retention-policy 90d \
--timestamping-mode client-require \
--timestamping-uncapped false
Create a development basin with auto-creation
s2 create-basin dev \
--create-stream-on-append \
--retention-policy 7d \
--delete-on-empty-min-age 1d
Migration workflow
Create new basin
s2 create-basin new-basin --storage-class express
Copy stream configurations
# List streams from old basin
s2 list-streams old-basin
# Create streams in new basin
s2 create-stream s2://new-basin/events --storage-class express
s2 create-stream s2://new-basin/metrics --storage-class standard
Migrate data
# Read from old basin and append to new basin
s2 read s2://old-basin/events | s2 append s2://new-basin/events
Configuration reference
Storage classes
- standard - Cost-optimized storage for most workloads
- express - Low-latency storage for latency-sensitive workloads
Retention policies
Specify as a duration or infinite:
--retention-policy 1d # 1 day
--retention-policy 2w # 2 weeks
--retention-policy 6m # 6 months (approximated as 180d)
--retention-policy 1y # 1 year
--retention-policy infinite
Timestamping modes
- client-prefer - Use client timestamp if provided, otherwise server timestamp
- client-require - Require client timestamp (reject records without one)
- arrival - Always use server arrival timestamp
See Timestamping for details.
Examples
List basins with production prefix
s2 list-basins --prefix "prod-"
Create a basin for log aggregation
s2 create-basin logs \
--storage-class standard \
--retention-policy 30d \
--create-stream-on-append \
--timestamping-mode arrival
s2 reconfigure-basin logs --retention-policy 90d