What does this PR do?

Stacked on #14471, which adds the description attributes to the collection schema and the V25 upgrade steps. Merge that one first. This PR is the API side: params, response models, search and tests.

Adds an optional description to functions, sites, variables, API keys, webhooks, databases, tables/collections, columns/attributes, indexes, storage buckets and messaging topics. It follows how WAF rules handle descriptions on Cloud (appwrite-labs/cloud, Modules/WAF/Http/Rules/*): same param name, limit, validator, update semantics and wording.

API

Every resource takes the same description param:

The field is returned on every matching response model. Docs text is "Optional description for the {resource}.", as on Cloud.

Behaviour notes:

• description is the last param on each endpoint. Existing params keep their positions, so SDK calls that pass arguments positionally still work. Subclasses that inherit an action (TablesDB, DocumentsDB and VectorsDB on top of the legacy Databases actions) declare it in the same position. A script checked the 109 database, compute, key, variable and webhook endpoints that take description for this. The 4 bucket and topic endpoints were checked by hand.
• Inline column and index definitions on table/collection create also accept description. The Attributes and Indexes validators check it with the same Text(1024, 0).
• Functions, sites, databases, tables/collections, buckets and topics add the description to their search index, so ?search= on those lists matches it. Topics already had description in their topicSearch filter, so they only needed the column. Bucket update now rewrites search too. Before, it never did, so a renamed bucket was only found by its old name. Variables, keys and webhooks have no list search, so their search value is unchanged. Description is not a filterable query attribute anywhere, which matches WAF rules.
• Changing a description does not set a function's or site's live to false. A description-only update on a variable also skips that step. Before, any project variable update set live: false on every function and site in the project.
• A variable update with only description set returns 200. Before, an update with no key, value or secret returned 400.
• The other side of a two-way relationship is created with an empty description. The description sent belongs to the column it was sent for.

Storage

The description attributes (size 1024, default '') and the V25 upgrade steps moved to #14471. Its description lists the collections and the MariaDB row widths.

Not in this PR

• Cloud columns. appwrite-labs/cloud#6485 adds them through patch tasks, and has to run before this ships there. It covers buckets and topics in both the platform and project databases.
• Console UI to show and edit descriptions.
• Carrying description through utopia-php/migration exports and the CLI's appwrite.config.json.
• An update endpoint for indexes. Index descriptions can only be set on create.
• Projects already have a description with a different limit and wording (Text(256), "Project description. Max length: 256 chars."). This PR leaves it unchanged.

SDK usage

await tablesDB.createTable({
    databaseId: 'shop',
    tableId: sdk.ID.unique(),
    name: 'Orders',
    description: 'One row per checkout, written by the checkout function.',
});

await tablesDB.createVarcharColumn({
    databaseId: 'shop',
    tableId: '<TABLE_ID>',
    key: 'status',
    size: 32,
    required: true,
    description: 'pending, paid or refunded.',
});

// Omitting description keeps the stored one
await functions.updateVariable({
    functionId: '<FUNCTION_ID>',
    variableId: '<VARIABLE_ID>',
    value: '<NEW_VALUE>',
});

Test Plan

CI on this PR ran the E2E lanes on PostgreSQL and passed: Databases (1,295 tests), TablesDB (526), Project (977), Sites (65), Organization (102), Webhooks (139), Functions (88). MariaDB, MongoDB and shared-tables lanes did not run. The Storage and Messaging tests for buckets and topics were added after that run and have not run yet. The functions tests also ran locally against Postgres (4 tests, 103 assertions); the rest has not run locally.

E2E:

• Databases/DatabasesBase (Legacy, TablesDB and DocumentsDB):
  • testUpdateDatabaseDescription and testUpdateCollectionDescription: set on create, '' default, kept on update without it, cleared with '', found by search, 1025 chars returns 400 general_argument_invalid.
  • testUpdateAttributeDescription: creates one column of every type with a description, then updates each through its own type endpoint. This catches a mis-wired param in any of the 72 column/attribute files. Spatial types and relationships run where the adapter supports them.
  • testCreateCollectionInlineDescription: inline column and index definitions.
  • testCreateIndexDescription: index create.
• Databases/VectorsDB/DatabasesBase: database, collection and index descriptions.
• Sites (SitesCustomServerTest): the create/get/list/update tests are extended, and testUpdateVariableDescription is new.
• Variables: function, site and project scopes. Each checks a description-only update (200), that a value update keeps the description, and live staying true on a description-only update but going false on a value update.
• Keys: project keys (Project/KeysBase) and organization project keys (Organization/KeysBase).
• Webhooks: the description survives a secret rotation and is returned on list.
• Functions: create/get/list/update, from the first commit.
• Buckets (StorageCustomServerTest::testUpdateBucketDescription): same cases as databases. It also checks that search matches the new description after an update and no longer matches the old one.
• Topics (MessagingBase::testUpdateTopicDescription): same cases as databases, on the PATCH update.

Unit tests for the inline definition validators (AttributesTest::testDescription and the new IndexesTest) pass on the host.

Static checks:

• PHPStan and Pint are clean on all changed files. Rector is clean on the tests. The bucket and topic changes passed Pint, but PHPStan and Rector have not run on them yet.
• MariaDB row widths are listed above.
• A script compared the description param position with the action signature each endpoint runs, including inherited ones. It checked all 109 endpoints that take description and found no mismatches.

Related PRs and Issues

• feat: add the description attribute to the collection schema #14471 (the schema half of this change, merge first)
• appwrite-labs/cloud#6485 (the Cloud patch tasks for these columns)
• 🚀 Feature: Add Description on Attribute #7145 (description on attributes, closed as not planned)

Checklist

• Have you read the Contributing Guidelines on issues?
• If the PR includes a change to an API's metadata (desc, label, params, etc.), does it also include updated API specs and example docs?

🤖 Generated with Claude Code