PySpiral

PySpiral is the legacy SpiralDB Python API. It remains available as pip install pyspiral with import spiral, and continues to target the old table format.

The new engine SDK is published separately as spiraldb and uses import spiraldb.

Third-Party Notices

PySpiral packages include spiral/THIRD_PARTY_NOTICES.md.

Volumes on hosted SpiralDB

Choose an existing Volume when creating a project:

import spiral

client = spiral.Spiral()
project = client.create_project(description="Archive", volume_id="vol_example")
print(project.get_storage())

List available Volumes with client.api.volumes.list(). To register an existing AWS bucket or prefix with OIDC credentials:

from spiral.api.volumes import AwsOidcCredential, RegisterVolumeRequest

volume = client.api.volumes.register(
    RegisterVolumeRequest(
        name="Archive",
        uri="s3://my-bucket/archive/",
        region="eu-west-2",
        credential=AwsOidcCredential(
            role_arn="arn:aws:iam::123456789012:role/spiral-storage",
            region="eu-west-2",
        ),
    )
)
print(volume.identity.trust_policy)

Apply the returned trust policy to the AWS role before using the storage. Registration does not create a bucket or test object reads and writes. Volume registration and changes require organization owner permissions.

The same API accepts GcsOidcCredential, R2Credential, and S3LikeCredential (providers minio, rustfs, and s3_like). Read responses omit secrets. Organization members can receive only a Volume's ID and name; its storage details and identity are available to owners.

Use client.api.volumes.update_status(volume.id, "retired") to stop new allocations, or "revoked" to stop issuing or renewing access. Already issued credentials remain usable until they expire. Use "active" to reactivate it. client.api.volumes.update_credential(volume.id, credential) replaces the credential while retaining the storage root.

For an existing project:

from spiral.api.volumes import FileSystemStorage, VolumeStorage

project.select_storage(VolumeStorage(volume_id="vol_example"))
project.select_storage(FileSystemStorage())

Storage selection controls allocation of new managed tables on servers that support Volumes. It does not move existing data or change PySpiral's legacy table format. This client support does not port the new engine's data path.

Without volume_id, project creation keeps the organization's default-storage behavior. The filesystem parameter remains available for legacy servers; current hosted servers require Volumes instead of an explicit filesystem. Do not pass both parameters.

The legacy CLI provides the same operations:

spiral volumes ls
spiral volumes register --name Archive --uri s3://my-bucket/archive/ \
  --provider aws --role-arn arn:aws:iam::123456789012:role/spiral-storage --region eu-west-2
spiral projects create --description Archive --volume vol_example
spiral projects storage project_example
spiral projects storage project_example --volume vol_example
spiral projects storage project_example --file-system
spiral volumes status vol_example retired
spiral volumes credential vol_example --provider aws \
  --role-arn arn:aws:iam::123456789012:role/spiral-storage --region eu-west-2

For S3-compatible storage, use --provider s3_like (or minio / rustfs) and --endpoint. For R2, use --provider r2 --account-id ACCOUNT_ID and, if needed, --jurisdiction eu. These providers read AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from the environment, as legacy fs update does. For GCS OIDC, use --provider gcs --workload-identity-provider PROVIDER_RESOURCE and --service-account EMAIL.

JSON files remain optional: spiral volumes register --request-file volume.json or spiral volumes credential vol_example --request-file credential.json. Do not combine --request-file with storage flags. volume.json uses the server's registration format:

{
  "name": "Archive",
  "uri": "s3://my-bucket/archive/",
  "region": "eu-west-2",
  "credential": {
    "provider": "aws",
    "type": "oidc",
    "roleArn": "arn:aws:iam::123456789012:role/spiral-storage",
    "region": "eu-west-2"
  }
}

credential.json contains just the credential field with the replacement credential. Access-key secrets come from environment variables or the optional JSON file; they do not need to appear in shell arguments.

Migrating legacy fs commands

The following commands are deprecated. They still call the legacy APIs for compatibility, and print a warning and migration instructions to stderr.

Choose a platform Volume from volumes ls instead of a built-in provider. For a custom bucket, register its root once and select that Volume for each project that should use it. An AWS or GCS Volume has its own OIDC identity: configure the returned trust policy instead of reusing a legacy file system's identity. Volume selection does not migrate existing files.

spiral fs mounts remains available. Mount management has no equivalent in the Volume API, and its server endpoints are not deprecated.