diff --git a/.codespellignore b/.codespellignore index ab827362edb..e2bbe946a42 100644 --- a/.codespellignore +++ b/.codespellignore @@ -1,4 +1,5 @@ -SME -te +hasTable jus nin +SME +te diff --git a/admin_manual/occ_command.rst b/admin_manual/occ_command.rst index a5e8fee3c75..61be8b4906d 100644 --- a/admin_manual/occ_command.rst +++ b/admin_manual/occ_command.rst @@ -46,6 +46,7 @@ occ command Directory * :ref:`system_tags_commands_label` * :ref:`antivirus_commands_label` * :ref:`setupchecks_commands_label` +* :ref:`snowflakes_commands_label` * :ref:`share_operations_label` * `Debugging`_ @@ -2273,6 +2274,28 @@ Example output:: ✓ Internet connectivity ... +.. _snowflakes_commands_label: + +Snowflake IDs +------------- + +You can decode Snowflake IDs with occ:: + + sudo -E -u www-data php occ decode-snowflake + +Example output:: + + +--------------------+-------------------------+ + | Snowflake ID | 6768789079123765868 | + | Seconds | 1575981518 | + | Milliseconds | 50 | + | Created from CLI | no | + | Server ID | 441 | + | Sequence ID | 2668 | + | Creation timestamp | 3335258318.050 | + | Creation date | 2075-09-09 12:38:38.050 | + +--------------------+-------------------------+ + .. _share_operations_label: Share operations diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst index 8d449e75150..0f152d42016 100644 --- a/developer_manual/digging_deeper/index.rst +++ b/developer_manual/digging_deeper/index.rst @@ -38,6 +38,7 @@ Digging deeper security settings setup_checks + snowflake_ids speech-to-text talk task_processing diff --git a/developer_manual/digging_deeper/snowflake_ids.rst b/developer_manual/digging_deeper/snowflake_ids.rst new file mode 100644 index 00000000000..b809b47f1b4 --- /dev/null +++ b/developer_manual/digging_deeper/snowflake_ids.rst @@ -0,0 +1,103 @@ +.. _snowflake_ids: + +============= +Snowflake IDs +============= + +.. versionadded:: 33 + +Nextcloud integrates a customized version of Snowflake IDs (https://en.wikipedia.org/wiki/Snowflake_ID). + +It allows to generates unique IDs in advance and also contains information about creation: + - creation time at millisecond precision + - identifier of server which created the ID. It's usually a hash of server hostname or random if not hostname found. + - whether the ID was created from CLI or not + +Store a Snowflake ID in database +-------------------------------- + +Snowflake IDs are designed to be used as primary key in database. +They should be stored as ``UNSIGNED BIGINT`` (64 bits integer, always positive) + +In Nextcloud migrations it looks like: + +.. code-block:: php + + public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper { + /** @var ISchemaWrapper $schema */ + $schema = $schemaClosure(); + + if (!$schema->hasTable('my_table')) { + $table = $schema->createTable('my_table'); + $table->addColumn( + 'id', + Types::BIGINT, + ['notnull' => true, 'unsigned' => true] + ); + $table->setPrimaryKey(['id']); + + // TODO Add other fields + } + + +Generate a Snowflake ID +----------------------- + +To generate a new ID, call ``nextId`` function on the generator: + +.. code-block:: php + + generator->nextId(); + + // TODO Create other properties and insert into database + } + } + + +Decode a Snowflake ID +--------------------- + +IDs can be decoded with ``occ decode-snowflake `` command. + +It’s also possible to decode IDs in your code, for example to get creation time of your object: + + +.. code-block:: php + + decoder->decode($this->id)['createdAt']; + } + }