The nova.db.api Module

Defines interface for DB access.

The underlying driver is loaded as a LazyPluggable.

Functions in this module are imported into the nova.db namespace. Call these functions from nova.db namespace, not the nova.db.api namespace.

All functions in this module return objects that implement a dictionary-like interface. Currently, many of these objects are sqlalchemy objects that implement a dictionary interface. However, a future goal is to have all of these objects be simple dictionaries.

Related Flags

db_backend:string to lookup in the list of LazyPluggable backends. sqlalchemy is the only supported backend right now. sql_connection:string specifying the sqlalchemy connection to use, like: sqlite:///var/lib/nova/nova.sqlite. enable_new_services:  when adding a new service to the database, is it in the pool of available hardware (Default: True)

exception NoMoreNetworks(message=None, **kwargs)

Bases: nova.exception.NovaException

No more available networks.

exception NoMoreTargets(message=None, **kwargs)

Bases: nova.exception.NovaException

No more available targets.

action_event_finish(context, values)

Finish an event on an instance action.

action_event_get_by_id(context, action_id, event_id)

action_event_start(context, values)

Start an event on an instance action.

action_events_get(context, action_id)

Get the events by action id.

action_finish(context, values)

Finish an action for an instance.

action_get_by_request_id(context, uuid, request_id)

Get the action by request_id and given instance.

action_start(context, values)

Start an action for an instance.

actions_get(context, uuid)

Get all instance actions for the provided instance.

agent_build_create(context, values)

Create a new agent build entry.

agent_build_destroy(context, agent_update_id)

Destroy agent build entry.

agent_build_get_all(context, hypervisor=None)

Get all agent builds.

agent_build_get_by_triple(context, hypervisor, os, architecture)

Get agent build by hypervisor/OS/architecture triple.

agent_build_update(context, agent_build_id, values)

Update agent build entry.

aggregate_create(context, values, metadata=None)

Create a new aggregate with metadata.

aggregate_delete(context, aggregate_id)

Delete an aggregate.

aggregate_get(context, aggregate_id)

Get a specific aggregate by id.

aggregate_get_all(context)

Get all aggregates.

aggregate_get_by_host(context, host, key=None)

Get a list of aggregates that host belongs to.

aggregate_host_add(context, aggregate_id, host)

Add host to the aggregate.

aggregate_host_delete(context, aggregate_id, host)

Delete the given host from the aggregate.

aggregate_host_get_all(context, aggregate_id)

Get hosts for the specified aggregate.

aggregate_host_get_by_metadata_key(context, key)

Get hosts with a specific metadata key metadata for all aggregates.

Returns a dictionary where each key is a hostname and each value is a set of the key values return value: {machine: set( az1, az2 )}

aggregate_metadata_add(context, aggregate_id, metadata, set_delete=False)

Add/update metadata. If set_delete=True, it adds only.

aggregate_metadata_delete(context, aggregate_id, key)

Delete the given metadata key.

aggregate_metadata_get(context, aggregate_id)

Get metadata for the specified aggregate.

aggregate_metadata_get_by_host(context, host, key=None)

Get metadata for all aggregates that host belongs to.

Returns a dictionary where each value is a set, this is to cover the case where there two aggregates have different values for the same key. Optional key filter

aggregate_update(context, aggregate_id, values)

Update the attributes of an aggregates. If values contains a metadata key, it updates the aggregate metadata too.

archive_deleted_rows(context, max_rows=None)

Move up to max_rows rows from production tables to corresponding shadow tables.

Returns:number of rows archived.

archive_deleted_rows_for_table(context, tablename, max_rows=None)

Move up to max_rows rows from tablename to corresponding shadow table.

Returns:number of rows archived.

block_device_mapping_create(context, values)

Create an entry of block device mapping.

block_device_mapping_destroy(context, bdm_id)

Destroy the block device mapping.

block_device_mapping_destroy_by_instance_and_device(context, instance_uuid, device_name)

Destroy the block device mapping.

block_device_mapping_destroy_by_instance_and_volume(context, instance_uuid, volume_id)

Destroy the block device mapping.

block_device_mapping_get_all_by_instance(context, instance_uuid)

Get all block device mapping belonging to an instance.

block_device_mapping_update(context, bdm_id, values)

Update an entry of block device mapping.

block_device_mapping_update_or_create(context, values)

Update an entry of block device mapping. If not existed, create a new entry

bw_usage_get(context, uuid, start_period, mac)

Return bw usage for instance and mac in a given audit period.

bw_usage_get_by_uuids(context, uuids, start_period)

Return bw usages for instance(s) in a given audit period.

bw_usage_update(context, uuid, mac, start_period, bw_in, bw_out, last_ctr_in, last_ctr_out, last_refreshed=None, update_cells=True)

Update cached bandwidth usage for an instance’s network based on mac address. Creates new record if needed.

cell_create(context, values)

Create a new child Cell entry.

cell_delete(context, cell_name)

Delete a child Cell.

cell_get(context, cell_name)

Get a specific child Cell.

cell_get_all(context)

Get all child Cells.

cell_update(context, cell_name, values)

Update a child Cell entry.

certificate_create(context, values)

Create a certificate from the values dictionary.

certificate_get_all_by_project(context, project_id)

Get all certificates for a project.

certificate_get_all_by_user(context, user_id)

Get all certificates for a user.

certificate_get_all_by_user_and_project(context, user_id, project_id)

Get all certificates for a user and project.

compute_node_create(context, values)

Create a computeNode from the values dictionary.

compute_node_delete(context, compute_id)

Delete a computeNode from the database.

Raises ComputeHostNotFound if computeNode does not exist.

compute_node_get(context, compute_id)

Get a computeNode.

compute_node_get_all(context)

Get all computeNodes.

compute_node_search_by_hypervisor(context, hypervisor_match)

Get computeNodes given a hypervisor hostname match string.

compute_node_statistics(context)

compute_node_update(context, compute_id, values, prune_stats=False)

Set the given properties on a computeNode and update it.

Raises ComputeHostNotFound if computeNode does not exist.

console_create(context, values)

Create a console.

console_delete(context, console_id)

Delete a console.

console_get(context, console_id, instance_uuid=None)

Get a specific console (possibly on a given instance).

console_get_all_by_instance(context, instance_uuid)

Get consoles for a given instance.

console_get_by_pool_instance(context, pool_id, instance_uuid)

Get console entry for a given instance and pool.

console_pool_create(context, values)

Create console pool.

console_pool_get_all_by_host_type(context, host, console_type)

Fetch all pools for given proxy host and type.

console_pool_get_by_host_type(context, compute_host, proxy_host, console_type)

Fetch a console pool for a given proxy host, compute host, and type.

constraint(**conditions)

Return a constraint object suitable for use with some updates.

dnsdomain_get(context, fqdomain)

Get the db record for the specified domain.

dnsdomain_list(context)

Get a list of all zones in our database, public and private.

dnsdomain_register_for_project(context, fqdomain, project)

Associated a DNS domain with a project id.

dnsdomain_register_for_zone(context, fqdomain, zone)

Associated a DNS domain with an availability zone.

dnsdomain_unregister(context, fqdomain)

Purge associations for the specified DNS zone.

ec2_instance_create(context, instance_uuid, id=None)

Create the ec2 id to instance uuid mapping on demand.

ec2_snapshot_create(context, snapshot_id, forced_id=None)

ec2_volume_create(context, volume_id, forced_id=None)

equal_any(*values)

Return an equality condition object suitable for use in a constraint.

Equal_any conditions require that a model object’s attribute equal any one of the given values.

fixed_ip_associate(context, address, instance_uuid, network_id=None, reserved=False)

Associate fixed ip to instance.

Raises if fixed ip is not available.

fixed_ip_associate_pool(context, network_id, instance_uuid=None, host=None)

Find free ip in network and associate it to instance or host.

Raises if one is not available.

fixed_ip_bulk_create(context, ips)

Create a lot of fixed ips from the values dictionary.

fixed_ip_count_by_project(context, project_id, session=None)

Count fixed ips used by project.

fixed_ip_create(context, values)

Create a fixed ip from the values dictionary.

fixed_ip_disassociate(context, address)

Disassociate a fixed ip from an instance by address.

fixed_ip_disassociate_all_by_timeout(context, host, time)

Disassociate old fixed ips from host.

fixed_ip_get(context, id, get_network=False)

Get fixed ip by id or raise if it does not exist.

If get_network is true, also return the assocated network.

fixed_ip_get_all(context)

Get all defined fixed ips.

fixed_ip_get_by_address(context, address)

Get a fixed ip by address or raise if it does not exist.

fixed_ip_get_by_address_detailed(context, address)

Get detailed fixed ip info by address or raise if it does not exist.

fixed_ip_get_by_floating_address(context, floating_address)

Get a fixed ip by a floating address.

fixed_ip_get_by_host(context, host)

Get fixed ips by compute host.

fixed_ip_get_by_instance(context, instance_uuid)

Get fixed ips by instance or raise if none exist.

fixed_ip_get_by_network_host(context, network_uuid, host)

Get fixed ip for a host in a network.

fixed_ip_update(context, address, values)

Create a fixed ip from the values dictionary.

fixed_ips_by_virtual_interface(context, vif_id)

Get fixed ips by virtual interface or raise if none exist.

floating_ip_allocate_address(context, project_id, pool)

Allocate free floating ip from specified pool and return the address.

Raises if one is not available.

floating_ip_bulk_create(context, ips)

Create a lot of floating ips from the values dictionary.

floating_ip_bulk_destroy(context, ips)

Destroy a lot of floating ips from the values dictionary.

floating_ip_count_by_project(context, project_id, session=None)

Count floating ips used by project.

floating_ip_create(context, values)

Create a floating ip from the values dictionary.

floating_ip_deallocate(context, address)

Deallocate a floating ip by address.

floating_ip_destroy(context, address)

Destroy the floating_ip or raise if it does not exist.

floating_ip_disassociate(context, address)

Disassociate a floating ip from a fixed ip by address.

Returns:the fixed ip record joined to network record or None if the ip was not associated to an ip.

floating_ip_fixed_ip_associate(context, floating_address, fixed_address, host)

Associate a floating ip to a fixed_ip by address.

Returns:the fixed ip record joined to network record or None if the ip was already associated to the fixed ip.

floating_ip_get(context, id)

floating_ip_get_all(context)

Get all floating ips.

floating_ip_get_all_by_host(context, host)

Get all floating ips by host.

floating_ip_get_all_by_project(context, project_id)

Get all floating ips by project.

floating_ip_get_by_address(context, address)

Get a floating ip by address or raise if it doesn’t exist.

floating_ip_get_by_fixed_address(context, fixed_address)

Get a floating ips by fixed address.

floating_ip_get_by_fixed_ip_id(context, fixed_ip_id)

Get a floating ips by fixed address.

floating_ip_get_pools(context)

Returns a list of floating ip pools.

floating_ip_set_auto_assigned(context, address)

Set auto_assigned flag to floating ip.

floating_ip_update(context, address, values)

Update a floating ip by address or raise if it doesn’t exist.

get_ec2_instance_id_by_uuid(context, instance_id)

Get ec2 id through uuid from instance_id_mappings table.

get_ec2_snapshot_id_by_uuid(context, snapshot_id)

get_ec2_volume_id_by_uuid(context, volume_id)

get_instance_uuid_by_ec2_id(context, ec2_id)

Get uuid through ec2 id from instance_id_mappings table.

get_snapshot_uuid_by_ec2_id(context, ec2_id)

get_volume_uuid_by_ec2_id(context, ec2_id)

instance_add_security_group(context, instance_id, security_group_id)

Associate the given security group with the given instance.

instance_create(context, values)

Create an instance from the values dictionary.

instance_data_get_for_project(context, project_id, session=None)

Get (instance_count, total_cores, total_ram) for project.

instance_destroy(context, instance_uuid, constraint=None, update_cells=True)

Destroy the instance or raise if it does not exist.

instance_fault_create(context, values, update_cells=True)

Create a new Instance Fault.

instance_fault_get_by_instance_uuids(context, instance_uuids)

Get all instance faults for the provided instance_uuids.

instance_floating_address_get_all(context, instance_uuid)

Get all floating ip addresses of an instance.

instance_get(context, instance_id)

Get an instance or raise if it does not exist.

instance_get_active_by_window_joined(context, begin, end=None, project_id=None, host=None)

Get instances and joins active during a certain time window.

Specifying a project_id will filter for a certain project. Specifying a host will filter for instances on a given compute host.

instance_get_all(context, columns_to_join=None)

Get all instances.

instance_get_all_by_filters(context, filters, sort_key='created_at', sort_dir='desc', limit=None, marker=None, columns_to_join=None)

Get all instances that match all filters.

instance_get_all_by_host(context, host, columns_to_join=None)

Get all instances belonging to a host.

instance_get_all_by_host_and_node(context, host, node)

Get all instances belonging to a node.

instance_get_all_by_host_and_not_type(context, host, type_id=None)

Get all instances belonging to a host with a different type_id.

instance_get_all_hung_in_rebooting(context, reboot_window)

Get all instances stuck in a rebooting state.

instance_get_by_uuid(context, uuid)

Get an instance or raise if it does not exist.

instance_get_floating_address(context, instance_id)

Get the first floating ip address of an instance.

instance_info_cache_delete(context, instance_uuid)

Deletes an existing instance_info_cache record

Parameters:instance_uuid – = uuid of the instance tied to the cache record

instance_info_cache_get(context, instance_uuid)

Gets an instance info cache from the table.

Parameters:instance_uuid – = uuid of the info cache’s instance

instance_info_cache_update(context, instance_uuid, values)

Update an instance info cache record in the table.

Parameters:

• instance_uuid – = uuid of info cache’s instance
• values – = dict containing column values to update

instance_metadata_delete(context, instance_uuid, key)

Delete the given metadata item.

instance_metadata_get(context, instance_uuid)

Get all metadata for an instance.

instance_metadata_update(context, instance_uuid, metadata, delete)

Update metadata if it exists, otherwise create it.

instance_remove_security_group(context, instance_id, security_group_id)

Disassociate the given security group from the given instance.

instance_system_metadata_get(context, instance_uuid)

Get all system metadata for an instance.

instance_system_metadata_update(context, instance_uuid, metadata, delete)

Update metadata if it exists, otherwise create it.

instance_test_and_set(context, instance_uuid, attr, ok_states, new_state)

Atomically check if an instance is in a valid state, and if it is, set the instance into a new state.

instance_type_access_add(context, flavor_id, project_id)

Add flavor access for project.

instance_type_access_get_by_flavor_id(context, flavor_id)

Get flavor access by flavor id.

instance_type_access_remove(context, flavor_id, project_id)

Remove flavor access for project.

instance_type_create(context, values)

Create a new instance type.

instance_type_destroy(context, name)

Delete an instance type.

instance_type_extra_specs_delete(context, flavor_id, key)

Delete the given extra specs item.

instance_type_extra_specs_get(context, flavor_id)

Get all extra specs for an instance type.

instance_type_extra_specs_update_or_create(context, flavor_id, extra_specs)

Create or update instance type extra specs. This adds or modifies the key/value pairs specified in the extra specs dict argument

instance_type_get(context, id)

Get instance type by id.

instance_type_get_all(context, inactive=False, filters=None)

Get all instance types.

instance_type_get_by_flavor_id(context, id, read_deleted=None)

Get instance type by flavor id.

instance_type_get_by_name(context, name)

Get instance type by name.

instance_update(context, instance_uuid, values, update_cells=True)

Set the given properties on an instance and update it.

Raises NotFound if instance does not exist.

instance_update_and_get_original(context, instance_uuid, values)

Set the given properties on an instance and update it. Return a shallow copy of the original instance reference, as well as the updated one.

Parameters:

• context – = request context object
• instance_id – = instance id or uuid
• values – = dict containing column values

Returns:

a tuple of the form (old_instance_ref, new_instance_ref)

Raises NotFound if instance does not exist.

key_pair_count_by_user(context, user_id)

Count number of key pairs for the given user ID.

key_pair_create(context, values)

Create a key_pair from the values dictionary.

key_pair_destroy(context, user_id, name)

Destroy the key_pair or raise if it does not exist.

key_pair_get(context, user_id, name)

Get a key_pair or raise if it does not exist.

key_pair_get_all_by_user(context, user_id)

Get all key_pairs by user.

migration_create(context, values)

Create a migration record.

migration_get(context, migration_id)

Finds a migration by the id.

migration_get_by_instance_and_status(context, instance_uuid, status)

Finds a migration by the instance uuid its migrating.

migration_get_in_progress_by_host_and_node(context, host, node)

Finds all migrations for the given host + node that are not yet confirmed or reverted.

migration_get_unconfirmed_by_dest_compute(context, confirm_window, dest_compute)

Finds all unconfirmed migrations within the confirmation window for a specific destination compute host.

migration_update(context, id, values)

Update a migration instance.

network_associate(context, project_id, network_id=None, force=False)

Associate a free network to a project.

network_count_reserved_ips(context, network_id)

Return the number of reserved ips in the network.

network_create_safe(context, values)

Create a network from the values dict.

The network is only returned if the create succeeds. If the create violates constraints because the network already exists, no exception is raised.

network_delete_safe(context, network_id)

Delete network with key network_id.

This method assumes that the network is not associated with any project

network_disassociate(context, network_id, disassociate_host=True, disassociate_project=True)

Disassociate the network from project or host and raise if it does not exist.

network_get(context, network_id, project_only='allow_none')

Get a network or raise if it does not exist.

network_get_all(context)

Return all defined networks.

network_get_all_by_host(context, host)

All networks for which the given host is the network host.

network_get_all_by_instance(context, instance_id)

Get all networks by instance id or raise if none exist.

network_get_all_by_uuids(context, network_uuids, project_only='allow_none')

Return networks by ids.

network_get_associated_fixed_ips(context, network_id, host=None)

Get all network’s ips that have been associated.

network_get_by_cidr(context, cidr)

Get a network by cidr or raise if it does not exist.

network_get_by_uuid(context, uuid)

Get a network by uuid or raise if it does not exist.

network_in_use_on_host(context, network_id, host=None)

Indicates if a network is currently in use on host.

network_set_host(context, network_id, host_id)

Safely set the host for network.

network_update(context, network_id, values)

Set the given properties on a network and update it.

Raises NotFound if network does not exist.

not_equal(*values)

Return an inequality condition object suitable for use in a constraint.

Not_equal conditions require that a model object’s attribute differs from all of the given values.

project_get_networks(context, project_id, associate=True)

Return the network associated with the project.

If associate is true, it will attempt to associate a new network if one is not found, otherwise it returns None.

provider_fw_rule_create(context, rule)

Add a firewall rule at the provider level (all hosts & instances).

provider_fw_rule_destroy(context, rule_id)

Delete a provider firewall rule from the database.

provider_fw_rule_get_all(context)

Get all provider-level firewall rules.

quota_class_create(context, class_name, resource, limit)

Create a quota class for the given name and resource.

quota_class_get(context, class_name, resource)

Retrieve a quota class or raise if it does not exist.

quota_class_get_all_by_name(context, class_name)

Retrieve all quotas associated with a given quota class.

quota_class_update(context, class_name, resource, limit)

Update a quota class or raise if it does not exist.

quota_create(context, project_id, resource, limit)

Create a quota for the given project and resource.

quota_destroy_all_by_project(context, project_id)

Destroy all quotas associated with a given project.

quota_get(context, project_id, resource)

Retrieve a quota or raise if it does not exist.

quota_get_all_by_project(context, project_id)

Retrieve all quotas associated with a given project.

quota_reserve(context, resources, quotas, deltas, expire, until_refresh, max_age, project_id=None)

Check quotas and create appropriate reservations.

quota_update(context, project_id, resource, limit)

Update a quota or raise if it does not exist.

quota_usage_get(context, project_id, resource)

Retrieve a quota usage or raise if it does not exist.

quota_usage_get_all_by_project(context, project_id)

Retrieve all usage associated with a given resource.

quota_usage_update(context, project_id, resource, **kwargs)

Update a quota usage or raise if it does not exist.

reservation_commit(context, reservations, project_id=None)

Commit quota reservations.

reservation_create(context, uuid, usage, project_id, resource, delta, expire)

Create a reservation for the given project and resource.

reservation_expire(context)

Roll back any expired reservations.

reservation_get(context, uuid)

Retrieve a reservation or raise if it does not exist.

reservation_rollback(context, reservations, project_id=None)

Roll back quota reservations.

s3_image_create(context, image_uuid)

Create local s3 image represented by provided uuid.

s3_image_get(context, image_id)

Find local s3 image represented by the provided id.

s3_image_get_by_uuid(context, image_uuid)

Find local s3 image represented by the provided uuid.

security_group_count_by_project(context, project_id, session=None)

Count number of security groups in a project.

security_group_create(context, values)

Create a new security group.

security_group_default_rule_create(context, values)

security_group_default_rule_destroy(context, security_group_rule_default_id)

security_group_default_rule_get(context, security_group_rule_default_id)

security_group_default_rule_list(context)

security_group_destroy(context, security_group_id)

Deletes a security group.

security_group_ensure_default(context)

Ensure default security group exists for a project_id.

Returns a tuple with the first element being a bool indicating if the default security group previously existed. Second element is the dict used to create the default security group.

security_group_exists(context, project_id, group_name)

Indicates if a group name exists in a project.

security_group_get(context, security_group_id)

Get security group by its id.

security_group_get_all(context)

Get all security groups.

security_group_get_by_instance(context, instance_id)

Get security groups to which the instance is assigned.

security_group_get_by_name(context, project_id, group_name)

Returns a security group with the specified name from a project.

security_group_get_by_project(context, project_id)

Get all security groups belonging to a project.

security_group_in_use(context, group_id)

Indicates if a security group is currently in use.

security_group_rule_count_by_group(context, security_group_id)

Count rules in a given security group.

security_group_rule_create(context, values)

Create a new security group.

security_group_rule_destroy(context, security_group_rule_id)

Deletes a security group rule.

security_group_rule_get(context, security_group_rule_id)

Gets a security group rule.

security_group_rule_get_by_security_group(context, security_group_id)

Get all rules for a given security group.

security_group_rule_get_by_security_group_grantee(context, security_group_id)

Get all rules that grant access to the given security group.

service_create(context, values)

Create a service from the values dictionary.

service_destroy(context, instance_id)

Destroy the service or raise if it does not exist.

service_get(context, service_id)

Get a service or raise if it does not exist.

service_get_all(context, disabled=None)

Get all services.

service_get_all_by_host(context, host)

Get all services for a given host.

service_get_all_by_topic(context, topic)

Get all services for a given topic.

service_get_by_args(context, host, binary)

Get the state of a service by node name and binary.

service_get_by_compute_host(context, host)

Get the service entry for a given compute host.

Returns the service entry joined with the compute_node entry.

service_get_by_host_and_topic(context, host, topic)

Get a service by host it’s on and topic it listens to.

service_update(context, service_id, values)

Set the given properties on a service and update it.

Raises NotFound if service does not exist.

task_log_begin_task(context, task_name, period_beginning, period_ending, host, task_items=None, message=None)

Mark a task as started for a given host/time period.

task_log_end_task(context, task_name, period_beginning, period_ending, host, errors, message=None)

Mark a task as complete for a given host/time period.

task_log_get(context, task_name, period_beginning, period_ending, host, state=None)

task_log_get_all(context, task_name, period_beginning, period_ending, host=None, state=None)

virtual_interface_create(context, values)

Create a virtual interface record in the database.

virtual_interface_delete_by_instance(context, instance_id)

Delete virtual interface records associated with instance.

virtual_interface_get(context, vif_id)

Gets a virtual interface from the table.

virtual_interface_get_all(context)

Gets all virtual interfaces from the table.

virtual_interface_get_by_address(context, address)

Gets a virtual interface from the table filtering on address.

virtual_interface_get_by_instance(context, instance_id)

Gets all virtual_interfaces for instance.

virtual_interface_get_by_instance_and_network(context, instance_id, network_id)

Gets all virtual interfaces for instance.

virtual_interface_get_by_uuid(context, vif_uuid)

Gets a virtual interface from the table filtering on vif uuid.

vol_get_usage_by_time(context, begin)

Return volumes usage that have been updated after a specified time.

vol_usage_update(context, id, rd_req, rd_bytes, wr_req, wr_bytes, instance_id, last_refreshed=None, update_totals=False)

Update cached volume usage for a volume Creates new record if needed.