SQLDatabaseProvider

Specify an encryption key to be used when the provider creates or opens a database.

Should this provider automatically generate primary keys? Defaults to true. If the provider doesn’t generate keys, then the client will have to provide them.

Should this provider automatically bind entities in createEntity or updateEntity, if bound entities are provided by the client. Defaults to true.

Should this provider automatically unbind entities in createEntity or updateEntity, if unbound entities are provided by the client. Defaults to true.

Should this provider automatically create parents in createEntity (“deep insert” calls), if nested parents are provided by the client. Defaults to true.

Should this provider automatically create children in createEntity (“deep insert” calls), if nested children are provided by the client. Defaults to true.

Should this provider automatically delete children in deleteEntity (“on delete” actions), if specified with OnDelete in the service metadata. Defaults to true.

Should this provider automatically expand itemns in executeQuery, if requested in the client’s query. Defaults to true.

Should entities be reselected after createEntity (SQL insert)? Defaults to true. This ensures that database-generated column values will be available in the entity parameter. Setting this property to false will result in better createEntity performance, but database-generated values will not be available in the entity parameter. Database-generated primary keys (see autoGenerateKeys) will still be available without setting selectAfterCreate as they are obtained without reselecting the entity. Note: if enableRowVersioning is true and maintainVersionColumns is false, then entities will be automatically reselected after createEntity even if selectAfterCreate is false.

Should entities be reselected after updateEntity (SQL update)? Defaults to true. This ensures that database-generated column values will be available in the entity parameter. Setting this property to false will result in better updateEntity performance, but database-generated values will not be available in the entity parameter. Database-generated primary keys (see autoGenerateKeys) will still be available without setting selectAfterUpdate as they are obtained without reselecting the entity. Note: if enableRowVersioning is true and maintainVersionColumns is false, then entities will be automatically reselected after createEntity even if selectAfterUpdate is false.

Should this provider use key tracking for determining when “delete” is required in delta responses? Defaults to false.

Should this provider be enabled for row versioning? Defaults to false. When row versioning is enabled, each table row contains a version number that is incremented by one for each update. All updates apply optimistic concurrency control to check that the pre-update row version matches the version known to the client.

Should this provider maintain the row version column? Defaults to false. Only applicable if enableRowVersioning is true. By default, a database is assumed to maintain the row version itself (e.g. using triggers).

Should complex properties be flattened into separate columns for database storage? Defaults to false.

Should the provider generate foreign key constraints when it creates database tables? Defaults to false. Foreign key constraints ensure that related rows do in fact exist. Foreign key constraints should not be used for tables with inline isDeleted / lastModified columns (for change tracking).

Should the provider generate unique constraints when it creates database tables? Defaults to false. Unique constraints ensure the integrity of one-to-one relationships (i.e. that we do not have many related rows). Unique constraints should not be used for tables with inline isDeleted / lastModified columns (for change tracking).

Batch size to be used for statement batching with this provider. Defaults to 100. Set this to zero to disable statement batching.

Cache size to be used for statement caching with this provider (per connection). Defaults to 100. Set this to zero to disable statement caching.

Is this provider permitted to modify the database schema, e.g. by adding required tables? Defaults to true. If not enabled, then schema changes will need to be managed by the database administrator.

Is this database a cache (staging) database for a backend system? Defaults to false.

Is this provider used for data metrics?

Should executeQuery with non-null DataQuery.searchExpression use database-level implementation of full-text searching. Defaults to false. Currently this is only supported for SAP HANA.

Should createEntity use client-provided keys (when available), in preference to server-generated keys? Defaults to false.

Constructs a SQL database provider which will execute OData requests against a SQL database. A remote OData service is not required in order to use this provider. The serviceName is used for logging. The optional databaseURL specifies a database URL for SQLite (SQLCipher), e.g. "sqlite:~/my-database.db". If not specified, the serviceName will be used to construct a default URL.

Apply the changes from a change set to the target system.

Begin a new transaction, or begin a nested transaction if a transaction is already active for this provider in the current thread.

This function may be used in the implementation of entity binding calls, e.g. by EntityValue.bindEntity. It relies on the existence of appropriate referential constraints in the service metadata, or an appropriately set join entity set.

This function may be used in the implementation of entity binding calls after the main create action of createEntity. It relies on the existence of appropriate referential constraints in the service metadata.

This function may be used in the implementation of entity binding calls after the main update action of updateEntity. It relies on the existence of appropriate referential constraints in the service metadata.

If the current thread is connected to this database, then disconnect it.

Commit the current transaction. If the current transaction is a nested transaction, then decrease the nesting level.

This function may be used in the implementation of “deep insert” calls, e.g. by createEntity. This function will execute “deep insert” if the parent-child entity relationship is fulfilled through join set.

Create an entity in the target system. Automatically calls CsdlDocument.resolveEntity to ensure that EntityValue.entitySet is available.

Call createEntity but catch any exception it throws (non-logged) and return it.

Define a database index for an entity set. Actual creation of the index is deferred until the first database connection is opened (explicitly or implicitly).

Create a link from a source entity to a target entity.

Default implementation of ‘createLink’ using foreign keys from referential constraints in service metadata.

Create a media entity with the specified content in the target system. If the entity has non-stream structural properties in addition to the key properties and media content, such as label in the examples below, then this function will send two requests to the server: a first request to upload (POST) the media stream, and a second request (PATCH/PUT) to update the non-stream properties. It is not currently supported to make these two calls atomic. Caution: Having too many threads simultaneously creating streams may result in out-of-memory conditions on memory-constrained devices.

This function may be used in the implementation of “deep insert” calls, e.g. by createEntity. This function will not execute “deep insert” if the parent-child entity relationship is fulfilled through join set.

Create (if non-existent) the database schema artifacts (e.g. tables) for this provider.

Create (if non-existent) the database schema artifacts (e.g. tables) for this provider. If creation fails, then retry (potentially forever) with a one minute delay between retries.

Should all connections (opening/closing) to this SQL database service be logged at debug level? Defaults to false.

Execute query to delete data from the target system.

This function may be used in the implementation of “on delete” actions, e.g. by deleteEntity.

Delete an entity from the target system.

Call deleteEntity but catch any exception it throws (non-logged) and return it.

Delete a link from a source entity to a target entity.

Default implementation of ‘deleteLink’ using foreign keys from referential constraints in service metadata.

Delete (if existing) the database schema artifacts (e.g. tables) for this provider.

Delete the content of a stream property from the target system.

Obtain a stream for downloading the content of a media entity from the target system. Caution: streams are often used for large content that may not fit (all at once) in available application memory. Having too many threads simultaneously downloading streams, or using ByteStream.readAndClose, may result in out-of-memory conditions on memory-constrained devices.

Obtain a stream for downloading the content of a stream property from the target system. Caution: streams are often used for large content that may not fit (all at once) in available application memory. Having too many threads simultaneously downloading streams, or using ByteStream.readAndClose, may result in out-of-memory conditions on memory-constrained devices.

If the current thread’s connection has batched statements, execute them now.

Execute a data method (action or function) in the target system. Actions may have backend side-effects. Functions should not have backend side-effects.

Execute a data query to get data from the target system.

Override this function to implement item expansion for this service. If not overridden, referential constraints are used to implement automatic expansion.

If query contains any DataQuery.expandItems, apply them to result.

Fetch latest service metadata and return it, but don’t change the metadata property.

Has service metadata been loaded.

Reload an existing entity from the target system.

Example using proxy classes

open func loadEntityExample() throws -> Void {
    let service = self.service
    let customer = Customer()
    customer.customerID = "ALFKI"
    try service.loadEntity(customer)
    self.showCustomer(customer)
}

Example using dynamic API

open func loadEntityExample() throws -> Void {
    let service = self.service
    let customersEntitySet = service.entitySet(withName: "Customers")
    let customerEntityType = customersEntitySet.entityType
    let customerIDProperty = customerEntityType.property(withName: "CustomerID")
    let customer = EntityValue.ofType(customerEntityType)
    customerIDProperty.setStringValue(in: customer, to: "ALFKI")
    try service.loadEntity(customer)
    self.showCustomer(customer)
}

Load service metadata (if not already loaded).

Load the value of a property into an existing entity. This can be applied to both structural and navigation properties.

Should all database exceptions be logged?

Service metadata.

If the current thread is not connected to this database, then connect it.

Open the database schema for this provider. Ensures that database connectivity is available and that (in principle) database operations can proceed.

Open the database schema for this provider. Ensures that database connectivity is available and that (in principle) database operations can proceed. If opening fails, then retry (potentially forever) with a one minute delay between retries.

Ping the server.

Execute work within a transaction.

Execute a request batch in the target system.

Rollback the current transaction. If the current transaction is a nested transaction, then decrease the nesting level, and mark the outermost (non-nested) transaction for eventual rollback.

Service name.

Register a callback handler which will be used for loading initial data into the database.

Options for database storage.

Should all connections (opening/closing) to this SQL database service be logged at trace level? Defaults to false.

Should all requests for this SQL database service be traced? Defaults to false.

Should all rollbacks for this SQL database service be traced (with a stack trace)? Defaults to false.

If traceRequests is also true, should all requests for this SQL database be traced with data? Defaults to false. Note that care must be taken when enabling tracing with data, as the resulting log files may contain sensitive information. On the other hand, tracing with data may sometimes be invaluable for troubleshooting purposes.

Perform some work within a database transaction. If a transaction is already active, then the work will be performed within a nested transaction.

This function may be used in the implementation of entity binding calls, e.g. by EntityValue.unbindEntity. It relies on the existence of appropriate referential constraints in the service metadata.

Unload service metadata (if previously loaded).

Update an entity in the target system.

Call updateEntity but catch any exception it throws (non-logged) and return it.

Update a link from a source entity to a target entity.

Default implementation of ‘updateLink’ using foreign keys from referential constraints in service metadata.

Upload content for a media entity to the target system Caution: Having too many threads simultaneously uploading streams may result in out-of-memory conditions on memory-constrained devices. Note: this function cannot be used to create a media entity. See DataService.createMedia.

Upload content for a stream property to the target system. Caution: Having too many threads simultaneously uploading streams may result in out-of-memory conditions on memory-constrained devices.