Schema management

#Schema management

The SvelteSync client exposes five methods for managing collection schemas: listCollections(), getCollection(), createCollection(), updateCollection(), and deleteCollection(). Record CRUD lives on the collection handle; schema management lives directly on the client.

Schema operations require elevated permissions — createCollection and updateCollection need schema/*:update, and deleteCollection needs schema/*:delete (typically the super_admin or admin role, or an API key with equivalent access).

listCollections and getCollection require an authenticated caller (any signed-in role) — collection schemas are not public. Each returns the field shape of the collections the caller can read; the access-control policy and other builder-only config (accessControl, databaseId, policyKey, columnStatuses) are included only for callers with system/roles:read.

#listCollections

sdk.listCollections(): Promise<CollectionSchema[]>

Lists all collections in the current project.

import { EmuView } from '@emuview/sdk';

const sdk = new EmuView({
	url: 'https://your-api.example.com',
	auth: { apiKey: 'sk-your-api-key' }
});

const collections = await sdk.listCollections();
console.log(collections.map((c) => c.name));
// ['posts', 'products', 'users']

#getCollection

sdk.getCollection(name: string): Promise<CollectionSchema>

Fetches a single collection's schema by name. Throws ApiError with status 404 if the collection doesn't exist.

const schema = await sdk.getCollection('products');
console.log(schema.schemaVersion, schema.fields.length);

#createCollection

sdk.createCollection(name: string, options?): Promise<CollectionSchema>

Creates a new collection and returns its schema. The name must be a valid SQL identifier and not a reserved name.

#Parameters

Parameter	Type	Required	Description
name	string	Yes	Collection name (lowercase, valid SQL identifier)
options.fields	FieldDef[]	No	Field definitions. Defaults to [] — you can add fields later
options.storageType	string	No	Storage backend. Defaults to 'd1'
options.databaseId	string	No	Target database ID for sharded collections

const schema = await sdk.createCollection('products', {
	fields: [
		{ name: 'title', type: 'text', required: true },
		{ name: 'price', type: 'decimal' },
		{ name: 'published', type: 'boolean', defaultValue: false }
	]
});

Throws ApiError with status 409 if a collection with this name already exists.

#updateCollection

sdk.updateCollection(name: string, updates): Promise<CollectionSchema>

Updates a collection's schema. Send the complete fields array — existing fields plus any new ones. The schema version increments automatically.

#Parameters

Parameter	Type	Required	Description
name	string	Yes	Collection name to update
updates.fields	FieldDef[]	No	Complete field array (existing + new fields)
updates.accessControl	unknown	No	Access control configuration

// Fetch the current schema, then append a new field
const schema = await sdk.getCollection('products');

const updated = await sdk.updateCollection('products', {
	fields: [...schema.fields, { name: 'sku', type: 'text', required: true, unique: true }]
});

#deleteCollection

sdk.deleteCollection(name: string): Promise<void>

Deletes a collection and all its records.

await sdk.deleteCollection('old_products');

#FieldDef shape

Every field definition passed to createCollection or updateCollection has this shape. The full list of the 23 field types is in field types.

Property	Type	Description
name	string	Column name (valid SQL identifier)
type	FieldType	Data type, e.g. 'text', 'decimal', 'boolean', 'enum', 'relation'
label	string	Human-readable label for the admin UI
required	boolean	Whether the field is NOT NULL
unique	boolean	Whether values must be unique
indexed	boolean	Whether to create an index on this field
defaultValue	unknown	Default value
enumValues	string[]	Allowed values (for enum type)
relationConfig	object	Relation configuration (for relation type) — see below
lookup	object	Lookup configuration (for lookup type) — see below
rollup	object	Rollup configuration (for rollup type) — see below

#relationConfig

Property	Type	Description
targetCollection	string	Name of the target collection
relationType	'belongsTo' | 'hasMany'	Relation cardinality
reverseVia	string	For hasMany: the belongsTo field on the target collection that holds the foreign key. The reverse relation is virtual (no column)

#lookup

A read-only, server-maintained copy of a field on a belongsTo relation's target, filled at write time. Cannot be combined with required, unique, or defaultValue.

Property	Type	Description
relation	string	Name of a belongsTo relation field on this collection
field	string	Field to copy from the target collection
resultType	FieldType	Resolved by the server — don't set this yourself

#rollup

A read-only, server-maintained aggregate over a declared reverse relation's children (e.g. a post_count on a forum). Recomputed automatically on child create/update/delete; client-submitted values are ignored. Cannot be required, unique, or have a defaultValue.

Property	Type	Description
relation	string	Name of a reverse-relation field (hasMany + reverseVia) on this collection
op	'count' | 'sum' | 'min' | 'max' | 'avg'	Aggregate operation. count ignores field; the others require it
field	string | null	Child field to aggregate (required for sum/min/max/avg)
filter	Record<string, unknown>	Optional simple child-side filter (no dot-paths, no _some/_none, no $ variables)
resultType	FieldType	Resolved by the server — don't set this yourself

#CollectionSchema shape

All five methods return (or list) CollectionSchema objects:

Property	Type	Description
id	string	Unique schema identifier
projectId	string	Project this collection belongs to
name	string	Collection name (used in API paths)
storageType	string	Storage backend type (usually 'd1')
databaseId	string | null	Target database ID (for sharded collections)
schemaVersion	number	Version number, incremented on field changes
fields	FieldDef[]	Field definitions
accessControl	unknown	Access control configuration
createdAt	number	Unix timestamp (seconds) when created
updatedAt	number	Unix timestamp (seconds) when the schema last changed

#Errors

Status	When	Thrown as
403	Missing schema/*:update or schema/*:delete permission	ApiError
404	getCollection, updateCollection, or deleteCollection on a name that doesn't exist	ApiError
409	createCollection with a name that already exists	ApiError

See error handling for catching and inspecting ApiError.