--- name: azion-create-and-manage-databases description: >- Create a database in SQL Database from Azion Console, the Azion API, or the azion library, then list, retrieve, and delete it. --- # Create and manage databases You create a database in [SQL Database](/en/documentation/platform/sql-database/) from Azion Console, the Azion API, or the `azion` library. The same three interfaces list the databases of your account, retrieve one, and delete one. A new database carries the name you set and nothing else. For the tables, the rows, and the SQL that reads them, refer to [Create tables and query data](/en/documentation/guides/application-development/data/create-tables-sql-database/). --- ## Prerequisites - SQL Database enabled on your account. The product is in Preview and is not enabled by default, so request access through [Technical Support](/en/documentation/support/). - A name for the database, no shorter than 6 characters and no longer than 50, spelled with letters, numbers, and the hyphen. No two databases in one account share a name. - The **Edit SQL Database** permission, which grants permission to create and edit databases and their data through the Azion API. **View SQL Database** grants permission to view them. Refer to [Teams Permissions](/en/documentation/fundamentals/teams-permissions/). - An account that reaches Azion Console, for the three Console procedures. Refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/) to authorize the four API requests. - Node and the `azion` package, for the library procedures. The library reads your token from `AZION_TOKEN`, and `AZION_DEBUG` turns on request logging. Refer to [Azion SQL library](/en/documentation/devtools/azion-lib/sql/). --- ## Create a database using Azion Console A database is created from the **SQL Database** page, and the form asks for a name and nothing else. To create the database: 1. **Open the database list** Access [Azion Console](https://console.azion.com/) > **SQL Database**. 2. **Start a new database** Select the **SQL Database** create control. The **Create Database** page opens. 3. **Name the database** In **General**, enter a **Name** of 6 to 50 characters, built from letters, numbers, and the hyphen. Any other character is refused with "Use only letters, numbers and hyphen (-)". 4. **Select Save** The database appears in the **SQL Database** list. Its **Status** reads `creating` until the database is ready, which takes roughly 15 seconds. --- ## Create a database using the API Send a `POST` request to the databases endpoint. The body accepts `name` and `active`, and no other field. To create the database: 1. **Send the create request** ```bash curl --location --request POST 'https://api.azion.com/v4/workspace/sql/databases' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --data '{"name":"my-database"}' ``` 2. **Read the response** The API answers with HTTP `202`. The envelope's `state` is `pending` while the database's own `status` is `creating`: ```json { "state": "pending", "data": { "id": 1234, "name": "my-database", "status": "creating", "active": true, "last_modified": "2026-01-01T12:00:00.000000Z", "last_editor": "user@example.com", "product_version": "1.0" } } ``` 3. **Poll until the database is ready** Provisioning takes roughly 15 seconds. Send `GET /databases/{database_id}` until `status` reads `created`. The database is stored under the integer identifier in `data.id`, and every other operation takes that identifier in its path. `last_modified`, `last_editor`, and `product_version` are read-only. > **Note** > > A name shorter than 6 characters or longer than 50 returns HTTP `400` with error `14000`, `Invalid Database Name Format`. A name under 6 characters also returns `10048`, `Min Length`. A name the account already holds returns HTTP `400` with error `14001`, `Name Already In Use.` --- ## Create a database using the azion library `azion/sql` runs the same operations from Node and TypeScript. One flat import carries the database functions and the query functions: ```javascript import { createDatabase, getDatabase, getDatabases, deleteDatabase, useQuery, useExecute, getTables } from 'azion/sql'; ``` The library is not a passthrough on the API's shapes. It camelCases the record fields to `lastModified`, `lastEditor`, and `productVersion`, and a query it runs returns `columns` and `rows` without `rows_read`, `rows_written`, or `query_duration_ms`. To create the database, pass the name to `createDatabase`: ```javascript import { createDatabase } from 'azion/sql'; const { data, error } = await createDatabase('my-database'); ``` The database is created under the name you passed, and it appears in the **SQL Database** list of your account. `data` carries the stored record, and `error` carries a `message` and the `operation` that failed. --- ## List your databases A list is scoped to the account the request authenticates as, and it holds every database that account created. ### Azion Console The **SQL Database** page of Azion Console lists every database in your account, with the columns **Name**, **Status**, **Last Editor**, and **Last Modified**. An account that holds no database shows the empty state "No SQL Databases yet", with the line "Create your first database to store relational data and run SQL queries." ### The API Send a `GET` request to the databases endpoint: ```bash curl --location 'https://api.azion.com/v4/workspace/sql/databases' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` The response carries one database object per entry under `results`, with the page they belong to: ```json { "count": 1, "total_pages": 1, "page": 1, "page_size": 10, "next": null, "previous": null, "results": [ { "id": 1234, "name": "my-database", "status": "created", "active": true, "last_modified": "2026-01-01T12:00:00.000000Z", "last_editor": "user@example.com", "product_version": "1.0" } ] } ``` `count` is how many databases match the request, and `total_pages` is how many pages they divide into at the current `page_size`. `next` and `previous` hold the adjacent pages, and they are `null` at either end. Four query parameters shape the response. `page` selects the page, and `page_size` sets how many databases it holds: the default is 10 and the ceiling is 100, above which the endpoint returns HTTP `400` with error `10097`, `Invalid Page Size`. `search` matches a name partially. `ordering` takes a field name, prefixed with `-` for descending order. ### The azion library Pass the same parameters to `getDatabases`: ```javascript import { getDatabases } from 'azion/sql'; const { data, error } = await getDatabases({ page: 1, page_size: 10 }); ``` `data` carries the databases of your account. `page`, `page_size`, `search`, and `ordering` narrow the list, as they do on the API endpoint. --- ## Retrieve a database A retrieve returns one database and the state it is in. The API finds it by its identifier; the `azion` library finds it by its name. ### Azion Console Access [Azion Console](https://console.azion.com/) > **SQL Database**, then select the database in the list. The database view opens with three tabs: **Tables**, **Editor**, and **Settings**. ### The API Send a `GET` request to the database, with its identifier in the path: ```bash curl --location 'https://api.azion.com/v4/workspace/sql/databases/' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` The API answers with HTTP `200` and returns the record under `data`. This envelope carries no `state` key, unlike the create response: ```json { "data": { "id": 1234, "name": "my-database", "status": "created", "active": true, "last_modified": "2026-01-01T12:00:00.000000Z", "last_editor": "user@example.com", "product_version": "1.0" } } ``` `status` reads `created` once the database is ready. An identifier the account does not hold returns HTTP `404` with error `10004`, `Not Found`. > **Note** > > `name` is read-only after creation, and `active` is accepted at creation only. Neither field can be edited afterwards: `PATCH` and `PUT` on a database return HTTP `405` with error `10007`, `Method Not Allowed`. A different name means a new database. ### The azion library `getDatabase` takes the database name, not its identifier: ```javascript import { getDatabase } from 'azion/sql'; const { data, error } = await getDatabase('my-database'); ``` The call returns the record with its fields camelCased: ```json { "data": { "id": 1234, "name": "my-database", "status": "created", "active": true, "lastModified": "2026-01-01T12:00:00.000000Z", "lastEditor": "user@example.com", "productVersion": "1.0" } } ``` A name the account does not hold returns `{}`, with neither `data` nor `error`. Test `data` before you read a field from it. --- ## Delete a database A database is deleted by the identity each interface knows: Azion Console by its row, the API and the `azion` library by its identifier. > **Caution** > > A delete cannot be undone. Azion removes the database and its data, and you can no longer write to or read from it. Its information cannot be retrieved afterwards. ### Azion Console Access [Azion Console](https://console.azion.com/) > **SQL Database**, then select **Delete** on the row of the database. The action is disabled while the status is `creating` or `deleting`. The row disappears from the **SQL Database** list. ### The API Send a `DELETE` request to the database, with its identifier in the path: ```bash curl --location --request DELETE 'https://api.azion.com/v4/workspace/sql/databases/' \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` The API answers with HTTP `202` and reports that it accepted the request, with no record echoed back: ```json {"state": "pending"} ``` The API accepts the delete even while the status is still `creating`. Within seconds, the database returns HTTP `404` with error `10004`, `Not Found`. ### The azion library `deleteDatabase` takes the database identifier, not its name: ```javascript import { deleteDatabase } from 'azion/sql'; const { data, error } = await deleteDatabase(1234); ``` The database is removed from your account, and `data` carries the `state` of the request, as the API's delete envelope does. --- ## Next steps - [Create tables and query data](/en/documentation/guides/application-development/data/create-tables-sql-database.md): Define the tables of the database you created, insert rows, and read them back with SQL. - [Databases and queries](/en/documentation/platform/sql-database/databases-and-queries.md): Every field, operation, envelope, and error code of the SQL Database endpoints. - [Query a database from a function](/en/documentation/guides/application-development/data/retrieve-data-with-functions.md): Reach the database from a function and return its rows to a request. - [SQL Database limits](/en/documentation/platform/sql-database/limits.md): The name, column, and page-size bounds, and the usage each plan includes.